Skip to main content

​
Overview

Time to complete: < 10 minutes This guide walks you through your first sandbox payment end to end: create an API key, register a user, render the Push Widget, tokenize a test card, and authorize the payment.

​
Create an API key

In order to securely access the API, you must first exchange a temporary code for a durable API key. You can request your temporary code in the dedicated slack channel setup for your organization or by reaching out to hello@pushcash.com. Once you have received your code, exchange it for an API key by making a request to the keys/exchange endpoint.
The steps below use the sandbox host (sandbox.pushcash.com). For production, make the same requests to api.pushcash.com.
$ curl --request POST \
	--url https://sandbox.pushcash.com/keys/exchange \
	--data '{"code": "TEMPORARY_CODE"}'
The response should contain your API key which you can use to authenticate your requests to the Push API. 
Your API key is: pcsk_sandbox_SPBLtVaLWA.EeL0j4DBkp4hDvtuUDO1fACOdOTHzvOzRynMWeHtyuwQ
Save the key to an environment variable so the requests below can reuse it: 
export APIKEY=pcsk_sandbox_...

​
1. Create a user

Register the user you’ll transact on behalf of by calling create-user. Keep the returned id for use in the next step. 
curl --request POST \
	--url https://sandbox.pushcash.com/user \
	--header 'Authorization: Bearer '$APIKEY \
	--header 'Content-Type: application/json' \
	--data '
{
  "name": {
    "first": "Alfred",
    "last": "Hitchcock"
  },
  "email": "alfred@imdb.com",
  "address": {
    "address_line_1": "1609 10th Ave",
    "locality": "Bodega Bay",
    "administrative_area": "CA",
    "postal_code": "94923",
    "country": "US"
  },
  "date_of_birth": "1899-08-13",
  "government_id": {
    "type": "passport",
    "last4": "7349"
  },
  "phone_number": "(555) 681-3485",
  "tag": "quickstart-user-1",
  "identity_verified": true
}
'

{
  "id": "user_lVpbPL0K1XIiHx0DxipRbD"
}

​
2. Render the widget and generate a token

The Push Widget renders a secure card form and exchanges the card details for a short-lived token. Because the widget runs in the browser, you’ll host it in a minimal webpage. First generate a widget URL for the user, then load that URL into a local page. Generate a widget URL by calling create-user-url with the user’s id (from step 1) and the payment direction: 
curl --request POST \
	--url https://sandbox.pushcash.com/user/user_lVpbPL0K1XIiHx0DxipRbD/url \
	--header 'Authorization: Bearer '$APIKEY \
	--header 'Content-Type: application/json' \
	--data '
{
  "direction": "cash_in"
}
'

{
  "url": "https://cdn.pushcash.com/widget/?param=1&param=2&param=3"
}
Next, create a folder with the two files below. index.html loads the Push JS SDK and provides a field to paste the widget URL into; app.js renders the widget and tokenizes the card.
index.html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Push Widget Quickstart</title>
  </head>
  <body>
    <h1>Push Widget Quickstart</h1>

    <label for="widget-url">Widget URL</label>
    <input id="widget-url" type="text" size="60"
      placeholder="Paste the create-user-url response here" />

    <!-- The widget renders into this container -->
    <div id="widget-container"></div>

    <button id="tokenize-button" disabled>Generate token</button>

    <pre id="result"></pre>

    <!-- Load the Push SDK first, then our script -->
    <script src="https://cdn.pushcash.com/sdk/push.umd.js"></script>
    <script src="./app.js"></script>
  </body>
</html>
app.js
const widgetUrl = document.getElementById('widget-url');
const tokenizeButton = document.getElementById('tokenize-button');
const result = document.getElementById('result');

let widget;

// Render (or re-render) the widget whenever a URL is entered.
widgetUrl.addEventListener('input', () => {
  if (widget) {
    widget.destroy();
    widget = undefined;
  }
  tokenizeButton.disabled = true;

  if (!widgetUrl.value.trim()) return;

  widget = new window.PushCash.Widget({
    selector: '#widget-container',
    url: widgetUrl.value.trim(),
    // Enable the button once the card details are valid.
    onValid: () => {
      tokenizeButton.disabled = false;
    },
  });
});

// Exchange the card details for a token.
tokenizeButton.addEventListener('click', async () => {
  try {
    const { token } = await widget.tokenize();
    result.textContent = 'Token: ' + token;
  } catch (err) {
    result.textContent = 'Tokenization failed: ' + err.message;
  }
});
Then:
  1. Open index.html directly in your browser. You’ll need an internet connection so the SDK can load from the CDN.
  2. Paste the url from the previous step into the Widget URL field and verify the card form appears.
  3. Enter the approved sandbox test card 5555 5555 5555 4444. Use any future date for expiration and any 3-digit value for CVV.
  4. Click Generate token. The page displays a token — copy it for the next step.

​
3. Authorize the payment

Submit the token to authorize-payment with the payment details to process the transaction: 
curl --request POST \
	--url https://sandbox.pushcash.com/authorize \
	--header 'Authorization: Bearer '$APIKEY \
	--header 'Content-Type: application/json' \
	--data '
{
  "amount": 2500,
  "currency": "USD",
  "direction": "cash_in",
  "token": "token_mbDRHFi3dxIZEtykHsgUGC"
}
'
A 200 OK response confirms the payment was approved: 
{
  "id": "intent_sandbox_mbDRHFi3dxIZEtykHsgUGC",
  "amount": 2500,
  "direction": "cash_in",
  "currency": "USD",
  "credential": {
    "display_name": "Visa 4444",
    "last4": "4444"
  }
}
Congratulations, you’ve processed your first payment 🎉

​
Next steps

  • Build the production flow (including processing stored credentials, handling step-up authentication, support for withdrawals and refunds) with the Card Payments guide.