Skip to content

Settlement

Settlement APIs enable the allocation of settled funds across multiple recipients. A settlement allocation request specifies how a received amount should be distributed. Wise processes each allocation as an individual payment intent that can be tracked through completion.

Operations
Webhooks

Create a settlement allocation request

Request

Creates a new settlement allocation request with a Settlement Allocation Request (SAR) file containing payment intents

Security
ClientCredentialsToken
Headers
X-External-Correlation-Idstring, (uuid), <= 36 characters

Optional UUID for correlating requests across systems. If provided, Wise echoes it back in the response. Maximum 36 characters. Learn more.

Example:f47ac10b-58cc-4372-a567-0e02b2c3d479
Bodymultipart/form-datarequired
commandobjectrequired
filestring, (binary)required

Settlement Allocation Request (SAR) file containing payment intent details

curl -i -X POST \
  https://api.wise.com/2026Q4/settlement/allocations \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -H 'X-External-Correlation-Id: f47ac10b-58cc-4372-a567-0e02b2c3d479' \
  -F 'command={"paymentReference":"PAY-2024-001234","expectedTotalAmount":10000,"currency":"USD"}' \
  -F file=string

Responses

Settlement allocation request accepted

Headers
X-External-Correlation-Idstring, (uuid), <= 36 characters

Echoed back when X-External-Correlation-Id was included in the request. Learn more.

Example:"f47ac10b-58cc-4372-a567-0e02b2c3d479"
x-trace-idstring

Unique trace identifier assigned by Wise. Useful when contacting support about a specific request.

Example:"fba501b6d453b96789f52338f019341f"
Bodyapplication/json
idstring, (uuid)required

Unique identifier of the settlement allocation request

expectedTotalAmountnumber, (decimal)required

Expected total amount

Example:10000
currencystring^[A-Z]{3}$required

Currency code

Example:"USD"
statestringrequired

State of a funding allocation.

Enum:"NEW""MATCHING_FUNDS""MATCHED""MISMATCHED""PARTIALLY_COMPLETED""COMPLETED""CANCELLED"
paymentReferencestringrequired

Payment reference

Example:"PAY-2024-001234"
createdAtstring, (date-time)required

Creation timestamp

updatedAtstring, (date-time)required

Last update timestamp

Response
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "expectedTotalAmount": 10000,
  "currency": "USD",
  "state": "NEW",
  "paymentReference": "PAY-2024-001234",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}