Integration

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": "[e-mail]",
		"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": "[phone]",
		"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

1. User navigates to cashier in operator’s application
2. App makes request to backend endpoint for cashier page
3. Backend submits user data to Push’s User Service
4. Push’s User Service returns identifier for user
5. Backend stores user identifier in database
6. 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
}

Fig 2: Sequence of interactions to render a cashier for a returning user.

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

Step 2: Display Push User Widget on payment page

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

Your payment page	Push User Widget

Generate Widget URL
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"
}

Render Push User Widget
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

1. User selects “Secure Debit” in cashier
2. App makes request to backend endpoint for payment page
3. Backend requests widget url from Push User Service
4. Push User Service returns URL
5. Backend returns URL to app
6. App requests Widget from SDK
7. SDK renders Widget to payment page
8. 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

1. User clicks submit button on payment page
2. App displays processing page to user
3. App requests token from Widget
4. Widget returns token to App
5. App submits token along with payment parameters to operator’s backend
6. 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

For operators with applications accessed via user’s web browsers either on mobile devices or desktop, display the authentication flow in an iframe. Once the iframe is rendered to the DOM, the authentication flow will communicate with the parent website via postMessage. In order to support OAUTH authentication flows, a new browser window will be opened for the user to login to their bank account.

Step 1: Submit iframe parameter to authorization engine
If the authentication flow will be presented in an iframe, you must set the iframe parameter in the request to the authorization engine. Pass “iframe”: true 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"
           "iframe": true,
       }'

Step 2: Render authentication flow iframe
With the URL returned from the Push Authorization Engine, render the authentication flow as an iframe element. Attach a postMessage listener to the iframe to know when the authentication session concludes and the iframe can be removed from the dom. Handle the payment intent ID and retrieve the payment status from the Push API via your backend.

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

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.