SettlementsEarly Access
This chapter includes information about features or aspects of the platform that are deemed Early Access.
Early Access features have 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.
A settlement represents a payout made to a client and contains a batched set of user payments.
For test clients, mock settlements are created once a day and include all completed payments for the previous day.
Please note that for our settlements product:
- Settlements are currently only available to South African customers.
- A Stitch intermediary account is required.
Please contact support@stitch.money for more information on these.
Settlement Statuses
The settlement field provides details about the batched payout made to the client. The following table outlines the possible statuses of a settlement:
| Status | Description |
|---|---|
| SettlementPending | The settlement has been created but not yet submitted |
| SettlementSubmitted | The settlement has been submitted to the bank, but confirmation of completion has not been received yet |
| SettlementCompleted | The settlement has been submitted to the bank, and confirmation of completion has been received |
| SettlementFailed | Failed to pay settlement into the destination account |
Settlement Failure Reasons
The SettlementFailed status indicates that the settlement has failed and has an associated settlementFailedReason. Examples of settlement failure reasons are listed below.
| Reason | Description |
|---|---|
| bank_error | The settlement was submitted to the bank but was not completed |
| insufficient_funds | This settlement has failed due to having insufficient funds in the Stitch intermediary account. Please contact support@stitch.money to resolve |
| invalid_destination | The provided client account is invalid |
| internal_error | An unknown error has occurred processing the settlement into the provided client account |
Querying All Settlements
To view the collection of settlements and associated LinkPay payment initiations, you may query the Client.settlements field
on the API. This will return a paged collection of settlements and a paged collection of payment initiations, dated from most
recent to least.
Similarly to query the InstantPay payment initiation requests associated with a settlement you can select the
paymentInitiationRequests on the settlements field.
Querying Settlements by ID
Using the query below you can retrieve the status of a specific settlement and any associated payment initiations, payment initiation requests or direct deposits.
Querying Settlements on Payment Nodes
When retrieving a payment initiation, payment initiation request or direct deposit, the associated settlement can be added to the node, and the settlement field will provide details of the payout, and its status.
For clients without a Stitch intermediary account, or payment requests that have not been completed, the settlement will be null.
Querying LinkPay Settlements
Querying InstantPay Settlements
Querying Direct Deposit Settlements
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.
Visit the Webhooks page for information on receiving webhook events, unsubscribing from webhooks and validating subscriptions.