Skip to main content


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 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:

SettlementPendingThe settlement has been created but not yet submitted
SettlementSubmittedThe settlement has been submitted to the bank, but confirmation of completion has not been received yet
SettlementCompletedThe settlement has been submitted to the bank, and confirmation of completion has been received
SettlementFailedThe 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.

bank_errorThe settlement was submitted to the bank but was not completed
insufficient_fundsThis settlement has failed due to having insufficient funds in the Stitch intermediary account. Please contact to resolve
invalid_destinationThe provided client account is invalid
internal_errorAn unknown error has occurred processing the settlement into the provided client account

Querying All Settlements

To view the collection of settlements and associated payments (Pay By Bank, or Direct Deposit payments), you may query the client.settlements field on the API. This will return a collection of settlements and collections of associated payments, dated from most recent to least. All collections are paged.

Payment types within a settlement

The paged collection object that can be queried within settlements differ based on types of user payments made, and may be any (or all) of the following, per settlement:

  • paymentInitiationRequests: Pay By Bank payments
  • directDeposits: Direct Deposit payments

Querying Settlements by ID

Using the query below, you can retrieve the status and details of a specific settlement by its unique ID, including all associated user payments (as explained previously).

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.