Payments
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 https://example.com/payment for payment requests, you'd append the following query string to the url returned from the API:
?redirect_uri=https%3A%2F%2Fexample.com%2Fpayment
Note
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 | ||
|---|---|---|
| Field | Description | Type |
id | The unique id of this payment request | ID |
status | Status 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 |
externalReference | The 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.