Initiate a cashout

post/cashouts

Initiates a cashout request

Endpoint destination URL

https://balanceplatform-api-test.adyen.com/btl/v4/cashouts

Request Parameters

Required

Optional

Contains the amount of the cashout, in minor units.

Contains information about the counterparty of the cashout transfer.

The date and time when the event was triggered, in ISO 8601 extended format. For example, 2025-03-19T10:15:30+01:00.

Allowed and returned only when you provide the counterparty.transferInstrumentId field.

Your description of the cashout transfer. This description is used by most banks as the transfer description. We recommend sending a maximum of 140 characters, otherwise the description may be truncated.

If you do not provide a description, Adyen generates a description automatically. This generated description is not returned in the response.

Supported characters: [a-z] [A-Z] [0-9] / - ? : ( ) . , ' + Space.

Contains the currency and value of the cashout fee, in minor units.

The unique identifier of the balance account that initiates the cashout request.

Allowed and returned only when you provide the counterparty.transferInstrumentId field.

The reference that is sent to the recipient of a cashout transfer. This reference is also sent in all webhooks related to the cashout transfer, so you can use it to track the status of the transfer.

If you do not provide a reference for the beneficiary, Adyen generates one automatically. This generated reference for the beneficiary is not returned in the response.

Supported characters: a-z, A-Z, 0-9.

Use counterparty.transferInstrumentId instead.

The unique identifier of the counterparty transfer instrument.

Response parameters

After submitting a call, you receive a response message to inform you that your request was received and processed.

Depending on the HTTP status code of the response message, it is helpful to build some logic to handle any errors that a request or the system may return.

HTTP Responses

200 - OK
The request has succeeded.
amountobject
Contains the amount of the cashout, in minor units.
currencystring
The three-character ISO currency code of the amount.
valueinteger
The numeric value of the amount, in minor units.
counterpartyobject
Contains information about the counterparty of the cashout transfer.
transferInstrumentIdstring
The unique identifier of the counterparty transfer instrument.

If you do not provide this field, the cashout funds remain in the instructing balance account after the cashout transfer is settled.
creationDatestring
The date and time when the event was triggered, in ISO 8601 extended format. For example, 2025-03-19T10:15:30+01:00.
descriptionstring
Allowed and returned only when you provide the counterparty.transferInstrumentId field.

Your description of the cashout transfer. This description is used by most banks as the transfer description. We recommend sending a maximum of 140 characters, otherwise the description may be truncated.

If you do not provide a description, Adyen generates a description automatically. This generated description is not returned in the response.

Supported characters: [a-z] [A-Z] [0-9] / - ? : ( ) . , ' + Space.
feeobject
Contains the currency and value of the cashout fee, in minor units.
amountobject
Contains the fee amount.
currencystring
The three-character ISO currency code of the amount.
valueinteger
The numeric value of the amount, in minor units.
idstring
The unique identifier of the cashout reference.
instructingBalanceAccountIdstring
The unique identifier of the balance account that initiates the cashout request.
referenceForBeneficiarystring
Allowed and returned only when you provide the counterparty.transferInstrumentId field.

The reference that is sent to the recipient of a cashout transfer. This reference is also sent in all webhooks related to the cashout transfer, so you can use it to track the status of the transfer.

If you do not provide a reference for the beneficiary, Adyen generates one automatically. This generated reference for the beneficiary is not returned in the response.

Supported characters: a-z, A-Z, 0-9.
transferInstrumentIdstringDeprecated
Use counterparty.transferInstrumentId instead.

The unique identifier of the counterparty transfer instrument.
transfersarray[object]
The list of transfers related to cashout.
amountobject
The amount of the cashout instruction transaction, in minor units.
currencystring
The three-character ISO currency code of the amount.
valueinteger
The numeric value of the amount, in minor units.
idstring
The reference of the cashout transfer.
typestring
The type of the cashout transfer.

Possible values:

cashoutRepayment: Corresponds to the transfer created to deduct the cashout amount after settlement.

cashoutFee: Corresponds to the transfer created to debit the cashout fee form the user's balance account.
400 - Bad Request
The request is malformed or is not in the expected format.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
Unique business error code.
instancestring
A URI that identifies the specific occurrence of the problem if applicable.
invalidFieldsarray[object]
Array of fields with validation errors when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
The unique reference for the request.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the validation error type. It points to human-readable documentation for the problem type.
401 - Unauthorized
The API credential used in the request is invalid.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
Unique business error code.
instancestring
A URI that identifies the specific occurrence of the problem if applicable.
invalidFieldsarray[object]
Array of fields with validation errors when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
The unique reference for the request.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the validation error type. It points to human-readable documentation for the problem type.
403 - Forbidden
The API credential does not have the right permissions.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
Unique business error code.
instancestring
A URI that identifies the specific occurrence of the problem if applicable.
invalidFieldsarray[object]
Array of fields with validation errors when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
The unique reference for the request.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the validation error type. It points to human-readable documentation for the problem type.
404 - Not Found
The requested resource was not found.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
Unique business error code.
instancestring
A URI that identifies the specific occurrence of the problem if applicable.
invalidFieldsarray[object]
Array of fields with validation errors when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
The unique reference for the request.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the validation error type. It points to human-readable documentation for the problem type.
422 - Unprocessable Entity
A request validation error.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
Unique business error code.
instancestring
A URI that identifies the specific occurrence of the problem if applicable.
invalidFieldsarray[object]
Array of fields with validation errors when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
The unique reference for the request.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the validation error type. It points to human-readable documentation for the problem type.
429 - Too Many Requests
Request rate limit exceeded.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
Unique business error code.
instancestring
A URI that identifies the specific occurrence of the problem if applicable.
invalidFieldsarray[object]
Array of fields with validation errors when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
The unique reference for the request.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the validation error type. It points to human-readable documentation for the problem type.
500 - Internal Service Error
An unrecoverable error occurred while trying to perform the request.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
Unique business error code.
instancestring
A URI that identifies the specific occurrence of the problem if applicable.
invalidFieldsarray[object]
Array of fields with validation errors when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
The unique reference for the request.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the validation error type. It points to human-readable documentation for the problem type.

Initiate a cashout

HTTP Responses

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

422 - Unprocessable Entity

429 - Too Many Requests

500 - Internal Service Error