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.

This endpoint requires HMAC request signing in addition to a bearer token. See HMAC request signing for the full algorithm, a verified test vector, and troubleshooting.

Security
ClientCredentialsToken and HmacSignature and HmacSignatureTimestamp
Headers
X-Signaturestring^[0-9a-f]{64}$required

HMAC-SHA256 signature of the request content, hex-encoded in lowercase (64 characters). Must be sent together with X-Signature-Timestamp.

Example:1023c8e2a19cc42260968ab2dcf1698e8344a2939ac97f686d21aacb650273e2
X-Signature-Timestampstring^[0-9]+$required

Unix timestamp in seconds at which X-Signature was generated, as a decimal string.

This value is part of the signed canonical string, so it must exactly match the timestamp used to compute the signature. Requests more than 300 seconds from Wise server time are rejected in either direction.

Example:1700000000
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/2027Q1/settlement/allocations \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -H 'X-External-Correlation-Id: f47ac10b-58cc-4372-a567-0e02b2c3d479' \
  -H 'X-Signature: YOUR_API_KEY_HERE' \
  -H 'X-Signature-Timestamp: YOUR_API_KEY_HERE' \
  -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"
}