Payments
6.5. Disbursements Early Access
Note
This chapter includes information about features or aspects of the platform that are deemed Early Access.
Early Access features has added stability and will not encounter breaking changes, offering a backward compatible API Schema.
Certain Early Access features may not be accessible to all Stitch users by default. These features can be enabled on a per-client basis on request.
Disbursements are instructions for Stitch to pay directly to destination accounts. These come in two flavours:
- Unlinked - disbursements to a specified destination account.
- Linked - disbursements to an account that was linked by Stitch (withdrawal use-case).
Note
- Disbursements are currently only available to South African customers.
- A Stitch float account is required.
Please contact the Stitch team for more information on these.
Creating a disbursement directly to a destination (Unlinked)
A client token is required in order to create a disbursement to a particular account. You'll need to follow the steps described
in the client token guide to obtain a client token with the client_disbursement scope.
To create the disbursement, a GraphQL mutation is used to specify the requested amount, the destination account details, a nonce to enforce uniqueness, and a reference that the beneficiary will see on their statement. An example of this can be found below:
The disbursement type allows you to specify either "INSTANT" or "DEFAULT". Leaving it empty will default to the latter. See the table below for more information.
Disbursement Types
| Type | Description |
|---|---|
INSTANT | Attempt to clear this payment with the bank immediately. If submitted after bank cutoff, it will rollover to the next business-day. Can incur additional cost. |
DEFAULT | Attempt to clear this payment with the bank on the same day. If submitted after the bank's cutoff time, it will rollover to the next business-day. |
In order to look up the status of the request in the API you will need the disbursement id from the response. The disbursement id will be also be returned with the subscription payload. Examples of these are below.
If there is insufficient balance in your account to issue the disbursement - the instruction will be accepted but remain on hold until the balance is available.
Note
By default the recipient account linked to a disbursement will be submitted for verification. This can be skipped by setting the input field skipRecipientAccountVerification to true.
Creating a disbursement to a linked user account
A user token previously issued during the LinkPay flow can be used to issue a disbursement directly to the linked account.
To create the disbursement, a GraphQL mutation is used to specify the requested amount, a nonce to enforce uniqueness, and a reference that the beneficiary will see on their statement. An example of this can be found below:
Storing recipient information
When creating either a linked or unlinked disbursement a recipientAccountHolder may be optionally provided. This information is intended for identifying the recipient of funds.
If recipientAccountHolder is provided, name and at least one of phoneNumber and email is required. This information can then be retrieved on the disbursement node.
Retrieving the disbursement status
After handling the response from the disbursement mutation, you will likely want to check the status of the disbursement. Using the
query below you can retrieve the status of a given disbursement by id, provided you have a client token with the client_disbursement scope. This applies to both Linked and Unlinked disbursements.
The DisbursementPaused status indicates that we can no longer continue processing the disbursement until certain conditions are met. These conditions are outlined in the table below.
Disbursement Paused Reasons
| Reason | Description |
|---|---|
insufficient_funds | There are insufficient funds in the account. |
The DisbursementError status indicates that the disbursement has failed. Examples of a failed disbursement are listed below.
Disbursement Error Reasons
| Reason | Description |
|---|---|
failed_account_verification | Disbursement was not processed due to failed account verification. |
payout_error | An error has occurred processing the payout into the provided beneficiary account. |
bank_error | The payout was submitted to the bank but was not completed. |
Subscribing to disbursement webhooks
To create a webhook subscription, you submit a GraphQL query like the one seen below. To learn more about implementing Webhooks with the Stitch API, please visit the Webhooks page.
If the subscription is successfully created, the body returned by the request will look like the following, with data being null,
and the subscriptionId being contained with the extensions field:
1{2 "data": null,3 "extensions": {4 "subscriptionId": "c3ViL2YxYzVjMTZkLWE0NjQtNDgxYS05NTUyLWUyMjhiYjQzNGE0NAo="5 }6}
Visit the Webhooks page for information on receiving webhook events, unsubscribing from webhooks and validating subscriptions.
Examples using Postman
Download the following Postman collection, and import it into Postman:
Disbursements.postman_collection.json