6.2. InstantPay

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.

Creating a payment initiation request

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 client_paymentrequest scope.

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 url. 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.

Why can you specify more than one bank account?

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.

Directing users to complete a payment request

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 for payment requests, you'd append the following query string to the url returned from the API: ?


To add or remove a URL from the whitelist, please reach out to a Stitch Engineer via the usual support channels on Slack or our Support Form.

Handling the payment request callback

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
idThe unique id of this payment requestID
statusStatus will have the value "complete" if successful, "closed" if the user clicked close in the UI, or "failed" if something went wrong when attempting the payment.String
externalReferenceThe value that was provided to the externalReference field when the payment initiation request was created.String

The 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.

Receiving webhooks on payment completion

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.

Retrieving the payment request status

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 PaymentInitiationRequestCancelled state when clientPaymentInitiationRequestCancel or userPaymentInitiationRequestCancel is called.

An optional expireAt DateTime (ISO 8061) can be supplied in the creation of the payment initiation request which marks the payment expired beyond the expireAt value.

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 the client_paymentrequest scope.