6.6. Settlements Early Access


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.

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.


  1. Settlements are currently only available to South African customers.
  2. A Stitch settlement account is required.

Please contact for more information on these.

Settlement Statuses

The following table outlines the possible statuses of a settlement:

Settlement statuses
SettlementPendingPayment has been completed by the user, but the settlement has not yet been 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 destination account.

The SettlementFailed status indicates that the settlement has failed and has an associated settlementFailedReason. Examples of settlement failure reasons are listed below.

Settlement Failure Reasons

bank_errorThe settlement was submitted to the bank but was not completed.
insufficient_fundsThis settlement has failed due to having insufficient funds in the settlement 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, 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 or payment initiation requests.

Querying settlements on payment nodes

When retrieving a payment initiation or payment initiation request, the associated settlement can be added to the node. For clients without a Stitch intermediary account, or paymentRequests that have not been completed, the settlement will be null.