Create a transfer instrument

post/transferInstruments

API Version

Creates a transfer instrument.

A transfer instrument is a bank account that a legal entity owns. Adyen performs verification checks on the transfer instrument as required by payment industry regulations. We inform you of the verification results through webhooks or API responses.

When the transfer instrument passes the verification checks, you can start sending funds from the balance platform to the transfer instrument (such as payouts).

Endpoint destination URL

https://kyc-test.adyen.com/lem/v3/transferInstruments

Header Parameters

Required

Optional

Use a suberror code as your requested verification code. You can include one code at a time in your request header. Requested verification codes can only be used in your test environment.

Request Parameters

Required

Optional

Contains information about the legal entity's bank account.

The unique identifier of the legal entity that owns the transfer instrument.

The type of transfer instrument.

Possible value: bankAccount.

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.
bankAccountobject
Contains information about the legal entity's bank account.
accountIdentification
Identification of the bank account.
accountTypestringDeprecated in version 2
The type of bank account.
bankNamestring
The name of the banking institution where the bank account is held.
countryCodestring
The two-character ISO 3166-1 alpha-2 country code where the bank account is registered. For example, NL.
trustedSourceboolean
Identifies if the bank account was created through instant bank verification.
capabilitiesobject
List of capabilities for this transfer instrument.
allowedboolean
Indicates whether the capability is allowed for the supporting entity.

If a capability is allowed for a supporting entity but not for the parent legal entity, this means the legal entity has other supporting entities that failed verification.

You can use the allowed supporting entity regardless of the verification status of other supporting entities.
idstring
Supporting entity reference
requestedboolean
Indicates whether the supporting entity capability is requested.
verificationStatusstring
The status of the verification checks for the capability of the supporting entity.

Possible values:

pending: Adyen is running the verification.

invalid: The verification failed. Check if the errors array contains more information.

valid: The verification has been successfully completed.

rejected: Adyen has verified the information, but found reasons to not allow the capability.

documentDetailsarray[object]
List of documents uploaded for the transfer instrument.
activeboolean
Identifies whether the document is active and used for checks.
descriptionstring
Your description for the document.
fileNamestring
Document name.
idstring
The unique identifier of the resource.
modificationDatestring
The modification date of the document.
pagesarray[object]
List of document pages
pageNamestring
pageNumberinteger
typestring
typestring
Type of document, used when providing an ID number or uploading a document.
idstring
The unique identifier of the transfer instrument.
legalEntityIdstring
The unique identifier of the legal entity that owns the transfer instrument.
problemsarray[object]
The verification errors related to capabilities for this transfer instrument.
entityobject
documentsarray[string]
List of document IDs corresponding to the verification errors from capabilities.
idstring
ownerobject
documentsarray[string]
List of document IDs corresponding to the verification errors from capabilities.
idstring
typestring
typestring
verificationErrorsarray[object]
capabilitiesarray[string]
Contains key-value pairs that specify the actions that the legal entity can do in your platform. The key is a capability required for your integration. For example, issueCard for Issuing.The value is an object containing the settings for the capability.
codestring
The general error code.
messagestring
The general error message.
remediatingActionsarray[object]
An object containing possible solutions to fix a verification error.
codestring
messagestring
subErrorsarray[object]
An array containing more granular information about the cause of the verification error.
capabilitiesarray[string]
Contains key-value pairs that specify the actions that the legal entity can do in your platform. The key is a capability required for your integration. For example, issueCard for Issuing.The value is an object containing the settings for the capability.
codestring
The general error code.
messagestring
The general error message.
typestring
The type of error.

Possible values:

invalidInput

dataMissing

pendingStatus

rejected

dataReview

remediatingActionsarray[object]
An object containing possible solutions to fix a verification error.
codestring
messagestring
typestring
The type of error.

Possible values:

invalidInput

dataMissing

pendingStatus

rejected

dataReview

typestring
The type of transfer instrument.

Possible value: bankAccount.
400 - Bad Request
A problem reading or understanding the request.
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.
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.
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.
422 - Unprocessable Entity
A request validation error.
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.
500 - Internal Server Error
The server could not process the request.
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.

Create a transfer instrument

HTTP Responses

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

422 - Unprocessable Entity

500 - Internal Server Error