Sign in

v50

latestOpenAPI 3.1.0raw.githubusercontent.com2026-07-061066160.9 KB
Transfers

Transfer funds

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.

post/transfers

Headers

Idempotency-Keystring

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

WWW-Authenticatestring

Header for authenticating through SCA

Request body

balanceAccountIdstring

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.

category'bank' | 'card' | 'internal' | 'issuedCard' | 'platformPayment' | 'topUp' required

The category of the transfer.

Possible values:

  • bank: A transfer involving a transfer instrument or a bank account.

  • card: A transfer involving a third-party card.

  • internal: A transfer between balance accounts within your platform.

  • issuedCard: A transfer initiated by an Adyen-issued card.

  • platformPayment: Funds movements related to payments that are acquired for your users.

  • topUp: An incoming transfer initiated by your user to top up their balance account.

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] & $ % # @ ~ = + - _ ' " ! ?

paymentInstrumentIdstring

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.

priority'crossBorder' | 'fast' | 'instant' | 'internal' | 'regular' | 'wire'

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

referencestring

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

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. The maximum length depends on the category.

  • internal: 80 characters

  • bank: 35 characters when transferring to an IBAN, 15 characters for others.

type'bankTransfer' | 'internalTransfer' | 'internalDirectDebit'

The type of transfer.

Possible values:

  • bankTransfer: for push transfers to a transfer instrument or a bank account. The category must be bank.
  • internalTransfer: for push transfers between balance accounts. The category must be internal.
  • internalDirectDebit: for pull transfers (direct debits) between balance accounts. The category must be internal.

Response

OK - The request has been accepted for processing, but has not been completed.

balanceAccountIdstring

The unique identifier of the source balance account.

category'bank' | 'card' | 'internal' | 'issuedCard' | 'platformPayment' | 'topUp' required

The category of the transfer.

Possible values:

  • bank: A transfer involving a transfer instrument or a bank account.

  • card: A transfer involving a third-party card.

  • internal: A transfer between balance accounts within your platform.

  • issuedCard: A transfer initiated by an Adyen-issued card.

  • platformPayment: Funds movements related to payments that are acquired for your users.

  • topUp: An incoming transfer initiated by your user to top up their balance account.

createdAtstring date-time

The date and time when the transfer was created, in ISO 8601 extended format. For example, 2020-12-18T10:15:30+01:00.

creationDatestring date-time

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

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] & $ % # @ ~ = + - _ ' " ! ?

direction'incoming' | 'outgoing'

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.

priority'crossBorder' | 'fast' | 'instant' | 'internal' | 'regular' | 'wire'

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). This will be removed in v4 and replaced with a new field.

reason'accountHierarchyNotActive' | 'amountLimitExceeded' | 'approvalExpired' | 'approved' | 'avsDeclined' | 'balanceAccountTemporarilyBlockedByTransactionRule' | 'blockCard' | 'callReferral' | 'cancelled' | 'captureCard' | 'cardExpired' | 'cardholderAuthenticationRequired' | 'cashbackAmountExceedsLimit' | 'cavvDeclined' | 'contactlessFallback' | 'contactlessLimitReached' | 'counterpartyAccountBlocked' | 'counterpartyAccountClosed' | 'counterpartyAccountNotFound' | 'counterpartyAddressRequired' | 'counterpartyBankTimedOut' | 'counterpartyBankUnavailable' | 'cryptographicFailure' | 'cvcDeclined' | 'declined' | 'declinedByBapValidation' | 'declinedByTransactionRule' | 'declinedNonGeneric' | 'directDebitNotSupported' | 'doNotHonor' | 'domesticDebitTransactionNotAllowed' | 'duplicateTransmissionDetected' | 'error' | 'formatError' | 'fraud' | 'fraudCancelled' | 'honorWithId' | 'internalTimeout' | 'invalidAccount' | 'invalidAmount' | 'invalidAuthorizationLifeCycle' | 'invalidCard' | 'invalidExpiryDate' | 'invalidFromAccount' | 'invalidIssuer' | 'invalidMerchant' | 'invalidPin' | 'invalidToAccount' | 'invalidTransaction' | 'issuerSuspectedFraud' | 'lostCard' | 'mobilePinRequired' | 'noCheckingAccount' | 'noSavingsAccount' | 'not3dAuthenticated' | 'notEnoughBalance' | 'notSubmitted' | 'notSupported' | 'partiallyApproved' | 'pending' | 'pendingApproval' | 'pendingExecution' | 'pinNotChanged' | 'pinRequired' | 'pinTriesExceeded' | 'pinValidationNotPossible' | 'purchaseAmountOnlyNoCashBack' | 'refusedByCounterpartyBank' | 'refusedByCustomer' | 'restrictedCard' | 'revocationOfAuth' | 'routeNotFound' | 'scaAuthenticationRequired' | 'scaFailed' | 'schemeAdvice' | 'securityViolation' | 'shopperCancelled' | 'stolenCard' | 'threedsDynamicLinkingMismatch' | 'transactionNotPermitted' | 'transferInstrumentDoesNotExist' | 'unableToRouteTransaction' | 'unknown' | 'withdrawalAmountExceeded' | 'withdrawalCountExceeded'

Additional information about the status of the transfer.

referencestring

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

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 the source and recipient of funds.

Supported characters: a-z, A-Z, 0-9.The maximum length depends on the category.

  • internal: 80 characters

  • bank: 35 characters when transferring to an IBAN, 15 characters for others.

status'approvalPending' | 'atmWithdrawal' | 'atmWithdrawalReversalPending' | 'atmWithdrawalReversed' | 'authAdjustmentAuthorised' | 'authAdjustmentError' | 'authAdjustmentRefused' | 'authorised' | 'bankTransfer' | 'bankTransferPending' | 'booked' | 'bookingPending' | 'cancelled' | 'capturePending' | 'captureReversalPending' | 'captureReversed' | 'captured' | 'capturedExternally' | 'chargeback' | 'chargebackExternally' | 'chargebackPending' | 'chargebackReversalPending' | 'chargebackReversed' | 'credited' | 'depositCorrection' | 'depositCorrectionPending' | 'dispute' | 'disputeClosed' | 'disputeExpired' | 'disputeNeedsReview' | 'error' | 'expired' | 'failed' | 'fee' | 'feePending' | 'interchangeAdjusted' | 'internalTransfer' | 'internalTransferPending' | 'invoiceDeduction' | 'invoiceDeductionPending' | 'manualCorrectionPending' | 'manuallyCorrected' | 'matchedStatement' | 'matchedStatementPending' | 'merchantPayin' | 'merchantPayinPending' | 'merchantPayinReversed' | 'merchantPayinReversedPending' | 'miscCost' | 'miscCostPending' | 'paymentCost' | 'paymentCostPending' | 'pending' | 'pendingApproval' | 'pendingExecution' | 'received' | 'refundPending' | 'refundReversalPending' | 'refundReversed' | 'refunded' | 'refundedExternally' | 'refused' | 'rejected' | 'reserveAdjustment' | 'reserveAdjustmentPending' | 'returned' | 'reversed' | 'secondChargeback' | 'secondChargebackPending' | 'undefined' required

The result of the transfer.

For example:

  • received: an outgoing transfer request is created.
  • refused: the transfer request is rejected by Adyen for one of the following reasons:
    • Transfer limit exceeded.
    • Transaction rule requirements violated.
  • 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.
type'payment' | 'capture' | 'captureReversal' | 'refund' | 'refundReversal' | 'chargeback' | 'chargebackCorrection' | 'chargebackReversal' | 'chargebackReversalCorrection' | 'secondChargeback' | 'secondChargebackCorrection' | 'atmWithdrawal' | 'atmWithdrawalReversal' | 'internalTransfer' | 'internalDirectDebit' | 'manualCorrection' | 'invoiceDeduction' | 'depositCorrection' | 'reserveAdjustment' | 'bankTransfer' | 'bankDirectDebit' | 'cardTransfer' | 'miscCost' | 'paymentCost' | 'fee' | 'leftover' | 'grant' | 'capitalFundsCollection' | 'cashOutInstruction' | 'cashoutFee' | 'cashoutRepayment' | 'cashoutFunding' | 'repayment' | 'installment' | 'installmentReversal' | 'balanceAdjustment' | 'balanceRollover' | 'balanceMigration'

The type of transfer or transaction. For example, refund, payment, internalTransfer, bankTransfer.