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 request to transfer funds to:

Adyen sends the outcome of the transfer request through webhooks.

To use this endpoint:

Your API credential must have the TransferService Webservice Initiate role.
The account holder must have the required capabilities.

Reach out to your Adyen contact to set up these permissions.

Endpoint destination URL

https://balanceplatform-api-test.adyen.com/btl/v2/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.

The unique identifier of the source balance account.

If you want to make a transfer using a virtual bankAccount assigned to the balance account, you must specify the payment instrument ID of the virtual bankAccount. If you only specify a balance account ID, Adyen uses the default physical bankAccount payment instrument assigned to the balance account.

Contains settings for bank transfers. If you are transferring funds to bank accounts and you don't provide this object, Adyen applies default settings.

The other party involved in the funds transfer. A bank account, a balance account, or a transfer instrument is required.

Max length: 140

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

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

Supported characters for regular and fast transfers to a US counterparty: [a-z] [A-Z] [0-9] & $ % # @ ~ = + - _ ' " ! ?

The unique identifier of the source payment instrument.

If you want to make a transfer using a virtual bankAccount, you must specify the payment instrument ID of the virtual bankAccount. If you only specify a balance account ID, Adyen uses the default physical bankAccount payment instrument assigned to the balance account.

Max length: 80

Your reference for the transfer, used internally within your platform. If you don't provide this in the request, Adyen generates a unique reference.

Max length: 80

A reference that is sent to the recipient. This reference is also sent in all webhooks related to the transfer, so you can use it to track statuses for both parties involved in the funds movement.

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

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

202 - Accepted
The request has been accepted for processing, but the processing has not been completed.
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.
balanceAccountIdstring
The unique identifier of the source balance account.
bankobject
Contains settings for bank transfers. If you are transferring funds to bank accounts and you don't provide this object, Adyen applies default settings.
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. If you don't provide this in the request, Adyen sets the optimal priority.

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).

counterpartyobject
The other party in the transfer.
balanceAccountIdstring
The unique identifier of the balance account.
bankAccountobject
Contains information about the bank account.
addressobject
The address of the bank account owner.
citystring
Max length: 3000
The name of the city. Maximum length: 3000 characters.
countrystring
The two-character ISO-3166-1 alpha-2 country code. For example, US.

If you don't know the country or are not collecting the country from the shopper, provide country as ZZ.

houseNumberOrNamestring
Max length: 3000
The number or name of the house. Maximum length: 3000 characters.
postalCodestring
A maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries.
stateOrProvincestring
The two-character ISO 3166-2 state or province code. For example, CA in the US or ON in Canada.

Required for the US and Canada.

streetstring
Max length: 3000
The name of the street. Maximum length: 3000 characters.

The house number should not be included in this field; it should be separately provided via houseNumberOrName.

ibanstring
The international bank account number as defined in the ISO-13616 standard.
ownerNameobject
The name of the bank account owner.
firstNamestring
The first name.
fullNamestring
The full name.
infixstring
The infix in the name, if any.
lastNamestring
The last name.
merchantobject
Contains information about the merchant.
acquirerIdstring
The unique identifier of the merchant's acquirer.
mccstring
The merchant category code.
merchantIdstring
The unique identifier of the merchant.
nameLocationobject
Contains the name and location of the merchant.
citystring
The city where the merchant is located.
countrystring
The country where the merchant is located in three-letter country code format.
countryOfOriginstring
The home country in three-digit country code format, used for government-controlled merchants such as embassies.
namestring
The name of the merchant's shop or service.
rawDatastring
The raw data.
statestring
The state where the merchant is located.
postalCodestring
The postal code of the merchant.
transferInstrumentIdstring
The unique identifier of the transfer instrument.
descriptionstring
Your description for the transfer. It is used by most banks as the transfer description. We recommend sending a maximum of 140 characters, otherwise the description may be truncated.

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

Supported characters for regular and fast transfers to a US counterparty: [a-z] [A-Z] [0-9] & $ % # @ ~ = + - _ ' " ! ?
directionstring
The direction of the transfer.

Possible values: incoming, outgoing.
idstring
The ID of the resource.
paymentInstrumentIdstring
The unique identifier of the payment instrument used in the transfer.
reasonstring
Additional information about the status of the transfer.
referencestring
Max length: 80
Your reference for the transfer, used internally within your platform. If you don't provide this in the request, Adyen generates a unique reference.
referenceForBeneficiarystring
Max length: 80
A reference that is sent to the recipient. This reference is also sent in all webhooks related to the transfer, so you can use it to track statuses for both parties involved in the funds movement.

Supported characters: a-z, A-Z, 0-9.
statusstring
The result of the transfer.

For example:

received: an outgoing transfer request is created.

authorised: the transfer request is authorized and the funds are reserved.

booked: the funds are deducted from your user's balance account.

failed: the transfer is rejected by the counterparty's bank.

returned: the transfer is returned by the counterparty's bank.
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

202 - Accepted

401 - Unauthorized

403 - Forbidden

422 - Unprocessable Entity

500 - Internal Server Error