Card Payments

​

Overview

​

Integration overview

1. Register the user. Call the create-user endpoint with the user’s identity information (name, email, address, and phone number).
   • Store the returned Push id alongside your internal user record.
   • Register each user only once and reuse the id on every subsequent transaction. Provide your internal user identifier in the tag field to ensure idempotency.
2. Display the widget. Call the create-user-url endpoint with the user’s id and payment direction, then render the widget to your payment page using the returned url.
   • The widget automatically validates the card and invokes the onValid callback when the form is complete — enable your submit button there.
   • For a returning user, you can skip the widget and let them pay with a previously-stored credential instead. See Stored credentials.
3. Authorize the transaction. When the user submits, generate a token from the widget (or use a stored credential_id) and call the authorize-payment endpoint with the payment details (amount, currency, direction), the token, and a redirect_url. Handle the response by its HTTP status code:
   • 202 Accepted — the user must complete authentication. Persist the returned intent id, then continue to step 4 using the returned url.
   • 200 OK — the payment was approved immediately. Notify the user that the payment succeeded.
   • 401 Unauthorized — the payment was declined.
   If your organization is assigned multiple settlement accounts, include the relevant account_id on every authorization request — retrieve the list with list-accounts. Omitting account_id while multiple accounts exist will fail the request. Organizations with a single settlement account can ignore this.
4. Direct the user to complete authentication. Navigate the user to the url returned from the authorize call. When the flow completes, the user is returned to your application via the redirect_url you set on the authorize request. Present the authentication UI in an iframe or the device’s system browser depending on your environment — see Presenting the authentication UI.
5. Retrieve the result. Call the get-an-intent endpoint and inspect the status field.
   • If status is approved, update your internal transaction record and notify the user the payment succeeded.
   • If status is declined, the payment could not be approved (e.g. insufficient_funds).

curl --request POST \
  --url https://sandbox.pushcash.com/user \
  --header 'Authorization: Bearer <token>' \
  --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": "4c8e6b4f",
  "identity_verified": true
}
'

curl --request POST \
  --url https://sandbox.pushcash.com/user/{id}/url \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "direction": "cash_in"
}
'

curl --request GET \
  --url 'https://sandbox.pushcash.com/user/{id}/credentials?type=secure_debit&type=card_only_credit&type=card_only_debit' \
  --header 'Authorization: Bearer <token>'

curl --request POST \
  --url https://sandbox.pushcash.com/authorize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 2500,
  "currency": "USD",
  "direction": "cash_in",
  "tag": "your-internal-transaction-record-id",
  "token": "token_mbDRHFi3dxIZEtykHsgUGC",
  "redirect_url": "https://yourapp.com/payment/complete"
}
'

curl --request GET \
  --url https://sandbox.pushcash.com/intent/intent_sandbox_dMggQ93ZYH6DH9LBhVeijE \
  --header 'Authorization: Bearer <token>'

{
  "id": "user_lVpbPL0K1XIiHx0DxipRbD"
}

{
  "url": "https://cdn.pushcash.com/widget/?param=1&param=2&param=3"
}

{
  "data": [
    {
      "id": "cred_7YlA9IiSl8UZvNwNSbFajV",
      "created_at": "2023-05-24T20:15:18.158Z",
      "card_last4": "4444",
      "card_brand": "visa",
      "authenticated": true,
      "type": "secure_debit",
      "account_last4": "0685",
      "bank_name": "Chase Bank"
    },
    {
      "id": "cred_8ZlB0JjTm9VZaOxOTcGbkW",
      "created_at": "2023-05-25T10:20:30.123Z",
      "card_last4": "1234",
      "card_brand": "mastercard",
      "authenticated": true,
      "type": "card_only_credit",
      "account_last4": null,
      "bank_name": null
    }
  ]
}

{
  "id": "intent_sandbox_mbDRHFi3dxIZEtykHsgUGC",
  "amount": 2500,
  "direction": "cash_in",
  "currency": "USD",
  "credential": {
    "id": "cred_7YlA9IiSl8UZvNwNSbFajV",
    "display_name": "Chase Checking",
    "last4": "6018"
  }
}

{
  "id": "intent_sandbox_dMggQ93ZYH6DH9LBhVeijE",
  "url": "https://cdn.pushcash.com/ux/intent_sandbox_dMggQ93ZYH6DH9LBhVeijE"
}

{
  "id": "intent_sandbox_mbDRHFi3dxIZEtykHsgUGC",
  "status": "declined",
  "decline_reason": "insufficient_funds"
}

{
  "id": "intent_sandbox_dMggQ93ZYH6DH9LBhVeijE",
  "status": "approved",
  "amount": 2500,
  "currency": "USD"
}

{
  "id": "intent_sandbox_dMggQ93ZYH6DH9LBhVeijE",
  "status": "declined",
  "decline_reason": "insufficient_funds"
}

​

Widget

const submitButton = document.querySelector('#submit-button');
submitButton.disabled = true;

const widget = new window.PushCash.Widget({
  // where to render the widget on the page
  selector: '#payment-container',

  // the url returned from the create-user-url endpoint
  url: 'https://cdn.pushcash.com/widget/?param=1&param=2',

  // runs once the user provides valid card information
  onValid: () => {
    submitButton.disabled = false;
  },
});

submitButton.addEventListener('click', async () => {
  try {
    const { token } = await widget.tokenize();
    // send token to your backend, which calls POST /authorize
    await yourBackend.authorize(token);
  } catch (err) {
    console.error('Tokenization failed:', err.message);
  }
});

​

Stored credentials

1. List and display the stored credentials. Call the list-user-credentials endpoint with the user’s id and the type values for the payment. For deposits, pass secure_debit, card_only_credit, and card_only_debit as the allowed types; for withdrawals, pass secure_debit. Display each returned credential’s card_brand and card_last4 and allow the user to select which card to use.
2. Authorize with the credential_id. Call authorize-payment with the selected credential_id (instead of a widget token), the payment details, and a redirect_url. Handle the response by its HTTP status code exactly as in the Integration overview.
3. Direct the user to complete authentication. If authorization returns 202 Accepted, navigate the user to the returned url — authentication may be requested even for a stored credential. See Presenting the authentication UI.
4. Retrieve the result. Call the get-an-intent endpoint and inspect status to confirm the payment was approved or declined.

curl --request POST \
  --url https://sandbox.pushcash.com/authorize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "user_lVpbPL0K1XIiHx0DxipRbD",
  "credential_id": "cred_sandbox_123",
  "amount": 2500,
  "currency": "USD",
  "direction": "cash_in"
}
'

​

Withdrawals

1. Restrict the widget to debit cards. Withdrawals settle to a bank account, so they require a secure_debit credential — a debit card with a linked account. When collecting a new card for a withdrawal, pass type: secure_debit to create-user-url so the widget only accepts debit cards. For a returning user, list stored credentials with ?type=secure_debit before presenting the selection UI (see Stored credentials).
2. Authorize with direction: cash_out. Call authorize-payment with direction: cash_out. Optionally set approval_mode: manual to hold the approved withdrawal for review instead of posting it to the network automatically — see Reviewing withdrawals.
3. Direct the user to complete authentication. Identical to a deposit — when the authorization returns 202 Accepted, navigate the user to the returned url. See Presenting the authentication UI.
4. Retrieve the result. Call get-an-intent and inspect status. A withdrawal authorized with approval_mode: manual returns status: pending — Push has approved it, but it is not posted to the network until you approve it.
5. (Optional) Approve the payment. If you authorized with approval_mode: manual, approve the pending intent to post it to the network — see Reviewing withdrawals.

curl --request POST \
  --url https://sandbox.pushcash.com/user/{id}/url \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "direction": "cash_out",
  "type": "secure_debit"
}
'

​

Reviewing withdrawals

curl --request POST \
  --url https://sandbox.pushcash.com/authorize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "user_lVpbPL0K1XIiHx0DxipRbD",
  "amount": 1000,
  "currency": "USD",
  "direction": "cash_out",
  "approval_mode": "manual",
  "token": "token_mbDRHFi3dxIZEtykHsgUGC"
}
'

curl --request POST \
  --url https://sandbox.pushcash.com/intent/intent_5Jun2aRUEs7xGddsARCowB/approve \
  --header 'Authorization: Bearer <token>'

curl --request POST \
  --url https://sandbox.pushcash.com/intent/intent_5Jun2aRUEs7xGddsARCowB/cancel \
  --header 'Authorization: Bearer <token>'

​

Refunds

1. Submit the refund. Call the create-refund endpoint with the intent_id of the payment you want to refund.
   • Optionally include an amount to refund a portion of the intent. If amount is omitted, the full intent amount is refunded.
   • Only one refund is allowed per intent — subsequent refund attempts on the same intent return a 200 with the already-created refund.
   To check whether an intent has already been refunded, call get-an-intent and inspect the refund field on the response.
   A refund can be declined by the issuer if the user’s bank rejects the transaction.
2. Handle the response. Check the HTTP status code:
   • 200 OK — the refund was created.
   • 401 Unauthorized — the refund was declined by the payment network. The response body includes the id of the declined refund.
   • 400 Bad Request — a validation error (e.g. the refund amount is greater than the intent amount).

curl --request POST \
  --url https://sandbox.pushcash.com/refund \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "intent_id": "intent_R7xKpVwZ3mNqYtFh2sJcAe"
}
'

curl --request POST \
  --url https://sandbox.pushcash.com/refund \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "intent_id": "intent_R7xKpVwZ3mNqYtFh2sJcAe",
  "amount": 500
}
'

​

Disputes

• Card chargebacks — a cardholder or issuer disputes a card payment. The code is the card-network reason code, for example 4853 (Cardholder Dispute) or 13.1 (Merchandise or Services Not Received).
• ACH returns — the receiving bank returns an ACH entry rather than honoring it. The code is the ACH return code, for example R01 (Insufficient Funds) or R02 (Account Closed).

• dispute.created webhook (push). When a dispute is opened against one of your intents, Push sends a signed dispute.created event to the webhook endpoint you configured on the originating payment — the signal to listen for so you learn about a chargeback or return without polling.
• Dispute API (pull). Fetch a single dispute with get-a-dispute, or query them with list-disputes filtering by status, code, type, and creation time. The current dispute is also embedded as the dispute field on the get-an-intent response.

​

Presenting the authentication UI

• Web (mobile or desktop): use the Push JS SDK’s UX to present the Push-hosted UI in a modal, and omit redirect_url from the authorization request. It fires your onExit callback when the flow ends.
• Native mobile app: open the authentication URL in the device’s default system browser (Safari on iOS, Chrome on Android). Set redirect_url on the authorization request to bring the user back to your app when authentication completes.

const ux = window.PushCash.UX({
  // the intent id returned from the authorize 202 response
  intentId: 'intent_sandbox_dMggQ93ZYH6DH9LBhVeijE',
  onExit: async () => {
    // the flow has ended — confirm the result from your backend (GET /intent/{id})
    const intent = await yourBackend.getIntent('intent_sandbox_dMggQ93ZYH6DH9LBhVeijE');
    // update your UI based on intent.status ('approved' | 'declined' | ...)
  },
});

ux.open();

​

Sandbox testing

• Register each user only once and reuse their id on subsequent transactions
• Simulate an approved transaction using test card 5555 5555 5555 4444
• Simulate a declined transaction using test card 5999 9919 6976 9266
• Test an authentication-required (202 Accepted) response using test card 6011 0009 9013 9424, and confirm you persist the intent id and present the authentication UI at url
• Test a payment decline after the user completes authentication using test card 5999 9819 6976 9283
• Add a new card, then submit a second transaction using the stored credential_id
• Verify that only secure_debit credentials are presented for withdrawals
• Process a withdrawal (cash_out) with a secure_debit card, then authorize with approval_mode: manual and approve the pending intent
• Refund an approved intent, and test a partial refund by specifying an amount less than the original intent amount
• Test a refund decline by processing an intent with test card 5999 9619 6976 9301 and then submitting a refund

​

Next steps