Transfer funds

post/transfers

API Version

Versions 1 and 2 of the Transfers API are deprecated. If you are just starting your implementation, use the latest version.

Starts a transfer request to move funds within your balance platform, or send funds to a transfer instrument. Adyen sends the outcome of the transfer request through webhooks.

To use this endpoint, you need an additional role for your API credential and transfers must be enabled for the source balance account. Your Adyen contact will set these up for you.

Endpoint destination URL

https://balanceplatform-api-test.adyen.com/btl/v1/transfers

Header Parameters

Required

Optional

Header for authenticating through SCA

A unique identifier for the message with a maximum of 64 characters (we recommend a UUID).

Request Parameters

Required

Optional

The amount of the transfer.

A human-readable description for the transfer. You can use alphanumeric characters and hyphens. We recommend sending a maximum of 140 characters, otherwise the description will be truncated in the webhooks that you receive about the transfer.

Contains information about the resource to which funds will be transferred.

Max length: 80

Your unique reference for the transfer. You can use alphanumeric characters and hyphens.

Contains information about the resource from which funds will be taken.

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
The amount of the transfer.
currencystring
Min length: 3Max length: 3
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
descriptionstring
A human-readable description for the transfer. You can use alphanumeric characters and hyphens. We recommend sending a maximum of 140 characters, otherwise the description will be truncated in the webhooks that you receive about the transfer.
destinationobject
Contains information about the resource to which funds will be transferred.
balanceAccountIdstring
The unique identifier of the balance account.
paymentInstrumentIdstring
The unique identifier of the payment instrument.
idstring
Unique identifier of the transfer.
referencestring
Max length: 80
Your unique reference for the transfer. You can use alphanumeric characters and hyphens.
refusalReasonstring
Additional information about the result of the transfer request.
resultCodestring
The result of the transfer request.

Possible values: Authorised, Refused.
sourceobject
Contains information about the resource from which funds will be taken.
balanceAccountIdstring
The unique identifier of the balance account.
paymentInstrumentIdstring
The unique identifier of the payment instrument.
401 - Unauthorized
Authentication required.
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
403 - Forbidden
Insufficient permissions to process the request.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
routingDetailsarray[object]
Detailed explanation of each attempt to route the transfer with the priorities from the request.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
prioritystring
The priority for the bank transfer. This sets the speed at which the transfer is sent and the fees that you have to pay. Required for transfers with category bank.

Possible values:

regular: for normal, low-value transactions.

fast: a faster way to transfer funds, but the fees are higher. Recommended for high-priority, low-value transactions.

wire: the fastest way to transfer funds, but this has the highest fees. Recommended for high-priority, high-value transactions.

instant: for instant funds transfers within the United States and in SEPA locations.

crossBorder: for high-value transfers to a recipient in a different country.

internal: for transfers to an Adyen-issued business bank account (by bank account number/IBAN).

titlestring
A short, human-readable summary of the problem type.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
422 - Unprocessable Entity
A request validation error.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
routingDetailsarray[object]
Detailed explanation of each attempt to route the transfer with the priorities from the request.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
prioritystring
The priority for the bank transfer. This sets the speed at which the transfer is sent and the fees that you have to pay. Required for transfers with category bank.

Possible values:

regular: for normal, low-value transactions.

fast: a faster way to transfer funds, but the fees are higher. Recommended for high-priority, low-value transactions.

wire: the fastest way to transfer funds, but this has the highest fees. Recommended for high-priority, high-value transactions.

instant: for instant funds transfers within the United States and in SEPA locations.

crossBorder: for high-value transfers to a recipient in a different country.

internal: for transfers to an Adyen-issued business bank account (by bank account number/IBAN).

titlestring
A short, human-readable summary of the problem type.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
500 - Internal Server Error
The server could not process the request.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
routingDetailsarray[object]
Detailed explanation of each attempt to route the transfer with the priorities from the request.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
prioritystring
The priority for the bank transfer. This sets the speed at which the transfer is sent and the fees that you have to pay. Required for transfers with category bank.

Possible values:

regular: for normal, low-value transactions.

fast: a faster way to transfer funds, but the fees are higher. Recommended for high-priority, low-value transactions.

wire: the fastest way to transfer funds, but this has the highest fees. Recommended for high-priority, high-value transactions.

instant: for instant funds transfers within the United States and in SEPA locations.

crossBorder: for high-value transfers to a recipient in a different country.

internal: for transfers to an Adyen-issued business bank account (by bank account number/IBAN).

titlestring
A short, human-readable summary of the problem type.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.

Transfer funds

HTTP Responses

200 - OK

401 - Unauthorized

403 - Forbidden

422 - Unprocessable Entity

500 - Internal Server Error