Skip to main content

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

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
SettlementFailedFailed 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.

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 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
## Subscribing to Settlement 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.

Visit the Webhooks page for information on receiving webhook events, unsubscribing from webhooks and validating subscriptions.