This guide provides instructions for developing an integration to the Push Cash Hosted Payment Experience.
Examples in this guide call the sandbox API hosted at https://sandbox.pushcash.com and do not trigger real money-movement.

​
Overview

An integration to the Hosted Payment Experience entails changes to both your frontend and backend systems. At a high level, the steps are:
  1. Install the button
  2. Call the API
  3. Receive webhook
interaction sequence diagram

​
Before you begin

Before starting your integration, please note the following requirement: Users must first deposit funds before they are allowed to withdraw using Push. Please hide or disable the Push button for withdrawals until the user deposits funds.

​
Steps to integrate

​
Install the button

First, add an entry point to the payment flow. The quickest way is to use the PushJS package to render a button on your cashier page. Start by adding a script tag to load the package on your website. 
<script src="https://cdn.pushcash.com/sdk/push.umd.js"></script>
Then, implement a function rendering the button onto the page. Provide a selector identifying where to render the button and optional styling parameters to control its appearance 
var push = window.PushCash.Button({
    selector: '#pushcash-button',
    style: {
        color: 'royal',
        height: 50,
    },
}).render();
You should now see the Push Cash button rendered on your cashier page. For more on how to style and configure the button, see the button reference guide.

​
Call the API

Update your backend to call the Push Cash API, using the API key created during the quickstart to authenticate API requests. Store the key securely, for example as an encrypted secret in your cloud environment.

​
Register user

Each user must be registered with the API before they can perform a payment. Register a user by submitting details verified as part of your KYC process, such as name, email, and phone number. For a full list of required fields, see the create user endpoint.
You must store the id for the user returned from the endpoint in your database and provide it each time the user performs a payment using Push.

​
Create intent

After the user has been registered, call the create intent endpoint to initiate a payment session. Submit basic details about the transaction such as the amount, currency, and direction. Set the redirect_url parameter to control where the user will be redirected after the payment session. example create-intent request body 
{
  "amount": 1000,
  "currency": "USD",
  "direction": "cash_in",
  "user_id": "your user ID",  // the registered user's ID
  "redirect_url": "your URL"  // where to redirect the user after the session
}
Return the url field from the response to the frontend to redirect the user to the payment session.

​
Define callback

Set up a callback function on the button to handle clicks. The callback should invoke your backend and return the payment session URL. 
callback = () => {
    const response = await axios.post("/your_backend_endpoint", { 
        // any necessary data about the payment details passed from your frontend
    })
    return response.data['url']
}
push.setCallback(callback);

​
Receive webhook

The final step for the integration is enabling webhooks. Whenever a payment intent is approved, Push will submit a webhook (http POST request) to your backend notifying your system of the event.

​
Configure URL

Specify where Push delivers notifications via the webhook_url parameter passed to create-intent. example create-intent request body 
{
  "amount": 1000,
  "currency": "USD",
  "direction": "cash_in",
  "user_id": "user_5Jun2aRUEs7xGddsARCowB",
  "redirect_url": "https://your-website.com/cashier",
  "webhook_url": "https://your-backend.com/webhook"  // the URL to send webhooks to
}

​
Process payload

Match webhook events to your internal records by populating the X-Idempotency-Key header with your internal transaction identifier. The key will be included in the webhook payload for the payment intent. example webhook payload 
{
  "type": "intent.approved",
  "data": {
    "id": "intent_5Jun2aRUEs7xGddsARCowB",
    "idempotency_key": "ff2394fjdow",  // the idempotency key you provided
    "direction": "cash_in",
    "status": "approved",
    "amount": 1000,
    ... // other fields omitted for brevity
  },
  "timestamp": "2024-01-14T22:31:02.756096Z"
}

​
Next steps

Once you have completed an integration in sandbox, you can move into production and start performing live money-movement. Contact us via Slack or email to receive your production API key.