Settlements
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 status field provides details about the batched payout made to the client. Possible statuses are outlined below:
| 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 | The settlement failed to be paid 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, you may
query the client.settlements field on the API. This will return a paginated collection of settlements, ordered from most recent to least recent.
To retrieve the payment breakdown for a settlement, query using the settlement ID, or bank reference.
Querying Settlements by ID
Using the query below, you can retrieve the details of a specific settlement by its unique ID. This query returns the payment breakdown of the specified settlement.
Querying Settlements by Bank Reference
When settlements are paid out from Stitch to a settling bank account, the received payment will have a unique reference. As an alternative to querying a settlement by its ID, this reference can also be used to query associated settlement information, by specifying the value as a filter on the query.
Querying Settlements on Payment Nodes
When retrieving a Pay By Bank request or direct deposit, the associated settlement can be added to the node, and the settlement field will provide details and status of the payout.
For clients without a Stitch intermediary account, or payment requests that have not been completed, the settlement will be null.
Querying Pay By Bank Settlements
Querying Direct Deposit Settlements
Subscribing to Settlement Webhooks
To create a webhook subscription, you submit a GraphQL query like the one shown 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.