Introduction

The Push Cash Native Integration removes steps from the payment user experience by allowing operators to embed card-acceptance and the payment authorization process within their applications. This guide provides detailed step-by-step instructions for developers embarking on the integration. Let’s get started.

Guide

Making payments using Push Secure Debit requires a few steps to be performed across your application backend and frontend. Before you get started, make sure you have API access to our sandbox environment.

Step 1: Display button on cashier

Add a button to your cashier which allows users to select “Secure Debit” as their payment option.

New User	Returning User

To include the button in your cashier, download the button in vector format from the image below.

If a user has not previously transacted using Push, you must first register them with the API, submitting information collected from your signup / KYC flow to Push for validation. Make a request to the create user endpoint.

curl --request POST \
	--url https://sandbox.pushcash.com/user \
 	--header 'Authorization: Bearer '$PUSH_API_KEY \
	--header 'X-Idempotency-Key: 1234' \
	--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
	}'

Store the ID from the response in your database. This will be used to generate the UI components for the user and to persist their payment information across sessions.

{
   "id": "user_lVpbPL0K1XIiHx0DxipRbD",
}

Fig 1: Sequence of interactions to display the cashier for a first-time user

User navigates to cashier in operator’s application
App makes request to backend endpoint for cashier page
Backend submits user data to Push’s User Service
Push’s User Service returns identifier for user
Backend stores user identifier in database
App renders cashier to user

If you have already registered the user, fetch their stored payment information and update the button to include the last four of the user’s card. Make a request to get user and parse the response. Example request to Push User Service

curl --request GET \
	--url https://sandbox.pushcash.com/user/user_lVpbPL0K1XIiHx0DxipRbD \
 	--header 'Authorization: Bearer '$PUSH_API_KEY

Example user object with payment credential field

{
  "id": "user_28CJjV7P4Go5PNJvfzghiD",
  "payment_credentials": [
    {
      "card": {
        "primary_account_number_mask": "6018",
      }
    }
  ],
  ... other fields omitted for brevity
}

Update the button with the “primary_account_number_mask” on the first payment credential Fig 2: Sequence of interactions to render a cashier for a returning user.

User navigates to cashier in operator’s application
App makes request to backend endpoint for cashier page
Backend requests user object from Push API
Push API returns user object
Backend parses response, returns information for user’s stored payment info to application.
Application renders cashier to user

Display the Push User Widget when the user selects Push as their payment option.

Your payment page	Push User Widget

Generate the URL for the Push User Widget by making a request to the create widget url endpoint. Provide the user’s ID and direction of their payment.

curl --request POST \
	--url https://sandbox.pushcash.com/user/user_lVpbPL0K1XIiHx0DxipRbD/url \
 	--header 'Authorization: Bearer '$PUSH_API_KEY \
	--data '{
		"direction": "cash_in"
	}'

Return the URL in the response to your frontend.

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

To render the Push User Widget, you must load the Push Javascript SDK from our CDN.

<script src="https://cdn.pushcash.com/sdk/push.umd.js"></script>

Once the package has loaded, access the library at the PushCash namespace on the window. Use the Widget function to render the Push User Widget. Provide the target element on the DOM where the component will render and the URL. Styling & Dimensions

We support customization of the widget’s background and color, font size, border-radius, and container padding.
The dimensions of the Push User Widget are a height of 164px and a minimum width of 303px.

Render Push User Widget with styling parameters

const widget = new window.PushCash.Widget({
    selector: '#payment-container',
    url: 'https://cdn.pushcash.com/widget/?param=1&param=2&param=3',
    background: '#ffffff', // white
    color: '#000000', // black
    fontSize: '14px',
    borderRadius: '2px',
    padding: '24px'
});

Fig 3: Sequence of interactions to display payment page for user

User selects “Secure Debit” in cashier
App makes request to backend endpoint for payment page
Backend requests widget url from Push User Service
Push User Service returns URL
Backend returns URL to app
App requests Widget from SDK
SDK renders Widget to payment page
User interacts with Widget on payment page

Step 3: Submit payment to Push Authorization Engine

Invoke the Push Authorization Engine when the user submits their payment.

First, display a message to the user notifying them that their payment is being processed.
Then, retrieve a token from the Push User Widget.
Finally, make a request to the Push Authorization Engine.

Card Unsubmitted	Payment Processing

Generate the token

When the user submits their payment, invoke the tokenize function and handle the returned Promise.

widget.tokenize()
  .then(({token}) => {
    console.log('Token received:', token);
    // submit token to backend
  })
  .catch((err) => {
    console.error('Tokenization error:', err.message);
    // handle error
  });

Request Authorization

Submit the token to your application backend, then make a request to authorize payment.

curl --request POST \
	--url https://sandbox.pushcash.com/authorize \
 	--header 'Authorization: Bearer '$PUSH_API_KEY \
	--data '{
           "amount": 1000,
           "currency": "USD",
           "direction": "cash_in",
           "token": "token_3r09eejo3r32rjoj3r23r3"
       }'

Fig 4: Sequence of interactions to submit a payment for authorization

User clicks submit button on payment page
App displays processing page to user
App requests token from Widget
Widget returns token to App
App submits token along with payment parameters to operator’s backend
Backend invokes Push Authorization Engine

Step 4: Handle authorization result

The Push Authorization Engine will determine whether to approve, decline, or require user authentication for the payment, then respond with the payment status. Determine the result by inspecting the response’s HTTP status code:

If the payment was approved, the status code will be 200 OK
If the payment was declined, the status code will be 401 Unauthorized
If the payment requires authentication, the status code will be 202 Accepted

Set your timeout to at least 15s in order to allow sufficient time to complete the request.

For approved / declined payments, display a result page to the user.

Transaction Approved	Transaction Declined

If the payment is approved, the payment ID is contained in the response body along with details about the user’s payment credential.

{
  "id": "intent_production_mbDRHFi3dxIZEtykHsgUGC",
  "payment_credential": {
    "bank_name": "Space Coast Credit Union",
    "bank_logo": "https://cdn.pushcash.com/space-coast_512x512.png",
    "card": {
      "primary_account_number_mask": "6018",
      "expiration": "2024-05-01"
    }
  }
}

If a payment is declined, the response body will contain the payment ID and decline category. The full list of decline categories is available in the api reference.

{
    "id": "intent_production_mbDRHFi3dxIZEtykHsgUGC",
    "decline_category": "fraud_risk"
}

Step 5: Redirect user to authentication flow

If the request cannot be immediately authorized, direct the user to the authentication flow to complete the payment.

Payment Unsubmitted	Payment Authorizing	Authentication Required

Parse the URL from the response body and return it to your frontend.

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

Once the user completes the flow, Push will re-authorize the payment and direct the user back to the operator’s application. Make a request from your backend to get an intent to determine the result of the payment. Depending on your application architecture, you must take different approaches to presenting the authentication flow to users so they can complete their payments on Push.

Use the web guide if your cashier and payment pages are websites accessed via the browser.
Use the webview guide if your cashier and payment pages are websites which are viewers through a mobile application in a webview.
Use the mobile guide if your cashier and payment pages are developed using mobile-native technologies (swift / objective-c, android kotlin, react native, etc.)

Web

If users access your application directly through their web browser on mobile / desktop, display the authentication flow in an iframe. Step 1: Render iframe
With the URL returned from the Push Authorization Engine, render the authentication flow as an iframe element on the DOM.

const iframe = document.createElement('iframe');
iframe.src = 'https://cdn.pushcash.com/ux/intent_sandbox_v6w81zLc7EKuGFm9ZVIiXC';
iframe.style.width = '360px';
iframe.style.height = '700px';
iframe.style.border = 'none';
document.getElementById('authentication-container').appendChild(iframe);

Step 2: Handle postMessage and fetch intent status
The authentication flow will submit a post message event when the session concludes. To handle this event,

Attach a listener to the iframe element.
Parse the message for the intent ID and retrieve the payment status from the get an intent endpoint.

window.addEventListener('message', (event) => {
  const data = event.data;
  console.log('✅ Received intent ID:', data.intent_id);
  // Retrieve intent status from API
});

Mobile Webview

For operators with applications developed using browser technology, but are exclusively accessed through a webview in a mobile app, display the authentication flow via redirect. Direct the user to the authentication URL from within your application webview, and they will be redirected back at the conclusion of the flow. Step 1: Submit redirect_url parameter to authorization engine
Define where users will be redirected after the conclusion of the authentication flow in your request to the authorization engine. Pass the redirect_url parameter in the json request body. example request

curl --request POST \
	--url https://sandbox.pushcash.com/authorize \
 	--header 'Authorization: Bearer '$PUSH_API_KEY \
	--data '{
           "amount": 1000,
           "currency": "USD",
           "direction": "cash_in",
           "token": "3r09eejo3r32rjoj3r23r3",
           "redirect_url": "https://cashier.operator-website.com"
       }'

Step 2: Perform redirect to authentication flow
With the URL returned from the authorization engine, re-direct the user to the authentication flow. example javascript

// Redirect to authentication flow
window.location.href = 'https://cdn.pushcash.com/ux/intent_sandbox_v6w81zLc7EKuGFm9ZVIiXC'

Step 3: Handle redirect back to cashier and update payment status
At the conclusion of the flow, the user will be redirected back from the authentication flow to your application. Parse the intent_id parameter from the URL and make an authenticated request to get an intent to determine the status of the payment

Mobile

For operators with applications developed using mobile technologies, display the authentication flow via secure webview technology. Step 1: Submit redirect_url parameter to authorization engine
Submit a redirect_url with a custom-scheme to the Push authorization engine. Use a custom-scheme like pushcash:// or similar. example request

curl --request POST \
	--url https://sandbox.pushcash.com/authorize \
 	--header 'Authorization: Bearer '$PUSH_API_KEY \
	--data '{
           "amount": 1000,
           "currency": "USD",
           "direction": "cash_in",
           "token": "3r09eejo3r32rjoj3r23r3",
           "redirect_url": "pushcash://"
       }'

Step 2: Display authentication session in secure webview
Use a secure webview technology like ASWebAuthenticationSession or similar to display the authentication session to users. Attach listeners for redirects to the custom-scheme to determine when the user has completed the authentication flow. Parse the intent_id parameter from the URL and make an authenticated request to get an intent to determine the status of the payment.

Getting Started

Guides

Reference

Integration

Introduction

Guide

Step 1: Display button on cashier

Step 2: Display Push User Widget on payment page

Generate Widget URL

Render Push User Widget

Step 3: Submit payment to Push Authorization Engine

Generate the token

Request Authorization

Step 4: Handle authorization result

Step 5: Redirect user to authentication flow

Web

Mobile Webview

Mobile

Getting Started

Guides

Reference

​Introduction

​Guide

​Step 1: Display button on cashier

​Step 2: Display Push User Widget on payment page

​Generate Widget URL

​Render Push User Widget

​Step 3: Submit payment to Push Authorization Engine

​Generate the token

​Request Authorization

​Step 4: Handle authorization result

​Step 5: Redirect user to authentication flow

​Web

​Mobile Webview

​Mobile

Introduction

Guide

Step 1: Display button on cashier

Step 2: Display Push User Widget on payment page

Generate Widget URL

Render Push User Widget

Step 3: Submit payment to Push Authorization Engine

Generate the token

Request Authorization

Step 4: Handle authorization result

Step 5: Redirect user to authentication flow

Web

Mobile Webview

Mobile