InstantPay is an easy way to automate payment initiation to a target account.
To use the InstantPay functionality, one creates a payment initiation request. Creating this request generates a unique URL that allows users to complete the request and also handles Multifactor Authentication, CAPTCHAs, logins and other related concerns.
InstantPay are a versatile payment primitive and can be used to build experiences such as checkout flows, peer to peer payments, e-wallets, investment products and more.
To create a payment initiation request, you'll need to ensure that the feature is enabled on your client.
InstantPay creation is protected by a client token. You'll need to follow the steps described
in the client token guide to obtain a client token with the
To create the request, a GraphQL mutation is used to specify the requested amount, the references that will appear on the user and beneficiary's accounts, and the beneficiary details themselves. An example of this can be found below:
The two pieces of information you need from the response at this stage are the payment request
id, and the
The payment request
id is used to correlate responses and to look up the status of the request in the API, and so should be retained for later usage.
If you're eagle-eyed, you may have noticed that you can specify either a single
bankAccount or a list of
bankAccounts when creating a payment request.
The bank account list was added because many companies open accounts at a number of different banks, and instruct users to pay into the same institution that they bank with. Companies often opt for this approach as intra-bank transfers typically clear near instantaneously.
Payment requests automate this account selection process by selecting the optimal account from the list for a given user.The first bank account in the list acts as the preferred account and will be selected if a more optimal route is not found.
The URL returned by the API requires that a whitelisted
redirect_uri is appended to it as a query string argument. If you direct a user to this URL,
they will be guided through the process of completing the payment.
For example, if your whitelist included the URL
https://example.com/payment for payment requests, you'd append the following query string to the
url returned from the API:
Once the user completes or cancels the payment request, they'll be redirected back to the
redirect_uri. The redirect uri will be passed three query string parameters.
|Payment Request Callback Query Parameters|
|The unique id of this payment request||ID|
|Status will have the value ||String|
|The value that was provided to the ||String|
id can be used to retrieve the final payment request status and other details from the Stitch API, as well as relate to incoming webhooks.
To receive a webhook upon payment completion you will need to create a subscription for your client. Please see our documentation on webhook subscriptions for information on how to do so.
When receiving a callback from the payment request, you will likely want to check the status of the payment. Using the query below you can retrieve the status of a given payment by ID, in addition to information about the payer and beneficiary involved.
If a user closed the payment request interface, the payment will remain in the
PaymentInitiationRequestPending state. The request will only be in the
userPaymentInitiationRequestCancel is called.
expireAt DateTime (ISO 8061) can be supplied in the creation of the payment initiation request which marks the payment expired beyond the
When a user has successfully initiated the payment, the state will be
PaymentInitiationRequestCompleted and contain details of the payment, including the account selected and the specific beneficiary payment was made to.
To retrieve the status of a payment request, as described above, you'll need a client token with