Settlement Cycle
After funding a number of transfers over a settlement period, you should then settle for those transfers in bulk. How you do this depends on how refunds are processed for the integration you are building.
There are two steps involved in the settlement process:
- Sending the settlement journal to Wise using API
- Sending the actual funds to Wise using Bank Transfer
Throughout the settlement period you will have called the funding endpoint a number of times to fund transfers. At the end of each settlement period (usually daily), you must run a process to send a journal containing all transfers you wish to settle for to an API endpoint, and then send the total amount of funds to the pre-agreed deposit bank account.
The process is given as below:
- A process should be run to perform settlement, this can be ad hoc or scheduled to run at the same time daily.
- The process should include:
- Query for all transfers that are yet to be settled with Wise. This should be all transfers you have called the funding endpoint for since the previous run of the settlement process.
- Query for all completed refunds that are yet to be notified to Wise. This should be all refunded transfers you have been notified using one of the refund methods since the previous run of the settlement process (Note: This is only applicable for the Net Settlement model.)
- Calculate the
balanceTransferamount based on the logic in the section above. - Get the Client Credentials Token in order to call the settlement journal endpoint. (Note: This is NOT a user access token. See retrieve client credentials token for an example of how to get this token.)
- The settlement journal endpoint should be called first to submit the settlement journal.
- The exact total amount of funds in the settlement journal should be deposited to Wise, to the pre-agreed deposit bank account, with the same settlement reference used in the settlement journal.
totalSettlementAmount = Sum of (sourceAmount * exchangeRate)
The settlement journal API receives the settlement and performs basic verification such as JSON format checks. Additional verification will be performed asynchronously when the transfers are actually settled.
POST /v1/settlements
Sends the settlement journal.
Type of settlement. Always TRUSTED_BULK_SETTLEMENT.
Reference used when paying the end of day settlement monies to Wise to cover all transfers. This should match such that we can link the payment. It can have up to 10 characters and must start with TPFB four letter prefix.
The date you send the settlement funds, ISO8601 format.
The currency in which the transfers in this journal will be settled. If included, the exchangeRate must be set on every transfer in the transfers array. (Note: Only include if you will settle in a currency different to the source currency of transfers.)
Array of transfers that happened on the settlementDate.
ID of the transfer to be settled.
The date the transfer was created, ISO8601 format.
Transfer source amount with fee, always positive.
Transfer source currency.
Name of the customer. Helps to identify customer when manual operation is required.
The transaction/payment identifier in your system, uniquely identifies the transfer in your platform.
Other data about the transfer or sender. For USA, you should send the account refund information for the sending customer (account number, routing number, street address, etc.)
The exchange rate you used to calculate the settlement amount for this transfer. This is only required if the source currency is different from the settlement currency. This is a required field if the settlementCurrency field has been set for the journal, and it must be set for all transfers. You can set this value to be unique per transfer or the same for every transfer, depending on your settlement approach and agreements with Wise.
Array of transfers which refunds have been processed. Only for Net Settlement.
ID of the refunded transfer.
The exchange rate you used to calculate the settlement amount for this transfer. This should be the same value as the one used for the original transfer settlement.
The transaction/payment identifier in your system, uniquely identifies the transfer in you platform.
The amount of money to be deducted from the expected settlement amount based on what is owed to you for previous days where the total settlement from you to Wise was negative. This value must be 0 or negative.
curl -X POST https://api.sandbox.transferwise.tech/v1/settlements \-H "Authorization: Bearer <your client credentials token>" \-H "Content-Type: application/json" \-d '{"type": "TRUSTED_BULK_SETTLEMENT","settlementReference": "TPFB190322","settlementDate": "2019-03-22T23:59:59-05:00","settlementCurrency": "USD","transfers": [{"id": 125678,"date": "2019-03-22T10:00:12-05:00","sourceAmount": 23.24,"sourceCurrency": "PHP","customerName": "Joe Bloggs","partnerReference": "11111","comment": "Extra Data","exchangeRate": 0.875469},{"id": 178889,"date": "2019-03-23T12:40:05-05:00","sourceAmount": 125.67,"sourceCurrency": "PHP","customerName": "Mat Newman","partnerReference": "11112","comment": "Extra Data","exchangeRate": 0.875469}],"refundedTransfers": [{"id": 178889,"partnerReference": "11112"},{"id": 124345,"partnerReference": "11102"}],"balanceTransfer": 0}'
HTTP 200
Empty body