openapi: 3.1.0
info:
version: '6'
x-publicVersion: true
title: Adyen Account acceptDispute Transfers API
description: "This API is used for the classic integration. If you are just starting your implementation, refer to our [new integration guide](https://docs.adyen.com/marketplaces-and-platforms) instead.\n\nThe Account API provides endpoints for managing account-related entities on your platform. These related entities include account holders, accounts, bank accounts, shareholders, and verification-related documents. The management operations include actions such as creation, retrieval, updating, and deletion of them.\n\nFor more information, refer to our [documentation](https://docs.adyen.com/marketplaces-and-platforms/classic).\n## Authentication\nYour Adyen contact will provide your API credential and an API key. To connect to the API, add an `X-API-Key` header with the API key as the value, for example:\n\n ```\ncurl\n-H \"Content-Type: application/json\" \\\n-H \"X-API-Key: YOUR_API_KEY\" \\\n...\n```\n\nAlternatively, you can use the username and password to connect to the API using basic authentication. For example:\n\n```\ncurl\n-U \"ws@MarketPlace.YOUR_PLATFORM_ACCOUNT\":\"YOUR_WS_PASSWORD\" \\\n-H \"Content-Type: application/json\" \\\n...\n```\nWhen going live, you need to generate new web service user credentials to access the [live endpoints](https://docs.adyen.com/development-resources/live-endpoints).\n\n## Versioning\nThe Account API supports [versioning](https://docs.adyen.com/development-resources/versioning) using a version suffix in the endpoint URL. This suffix has the following format: \"vXX\", where XX is the version number.\n\nFor example:\n```\nhttps://cal-test.adyen.com/cal/services/Account/v6/createAccountHolder\n```"
x-timestamp: '2023-05-30T15:27:20Z'
termsOfService: https://www.adyen.com/legal/terms-and-conditions
contact:
name: Adyen Developer Experience team
url: https://github.com/Adyen/adyen-openapi
servers:
- url: https://cal-test.adyen.com/cal/services/Account/v6
tags:
- name: Transfers
paths:
/balanceTransfer:
post:
tags:
- Transfers
summary: Adyen Start a Balance Transfer
description: 'Starts a balance transfer request between merchant accounts. The following conditions must be met before you can successfully transfer balances:
* The source and destination merchant accounts must be under the same company account and legal entity.
* The source merchant account must have sufficient funds.
* The source and destination merchant accounts must have at least one common processing currency.
When sending multiple API requests with the same source and destination merchant accounts, send the requests sequentially and *not* in parallel. Some requests may not be processed if the requests are sent in parallel.
'
operationId: post-balanceTransfer
x-groupName: General
x-sortIndex: 0
x-methodName: balanceTransfer
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
post-balance-transfer:
$ref: '#/components/examples/post-balanceTransfer-post-balance-transfer'
schema:
$ref: '#/components/schemas/BalanceTransferRequest'
responses:
'200':
content:
application/json:
examples:
post-balance-transfer:
$ref: '#/components/examples/post-balanceTransfer-post-balance-transfer-200'
schema:
$ref: '#/components/schemas/BalanceTransferResponse'
description: OK - the request has succeeded.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/transferRoutes/calculate:
post:
tags:
- Transfers
summary: Adyen Calculate Transfer Routes
description: Returns available transfer routes based on a combination of transfer `country`, `currency`, `counterparty`, and `priorities`. Use this endpoint to find optimal transfer priorities and associated requirements before you [make a transfer](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers).
x-addedInVersion: '1'
operationId: post-transferRoutes-calculate
x-sortIndex: 1
x-methodName: calculateTransferRoutes
security:
- clientKey: []
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
transferRoutesCalculate:
$ref: '#/components/examples/post-transferRoutes-calculate-transferRoutesCalculate'
schema:
$ref: '#/components/schemas/TransferRouteRequest'
responses:
'200':
content:
application/json:
examples:
transferRoutesCalculate:
$ref: '#/components/examples/post-transferRoutes-calculate-transferRoutesCalculate-200'
schema:
$ref: '#/components/schemas/TransferRouteResponse'
description: OK - the request has succeeded.
'401':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-401'
schema:
$ref: '#/components/schemas/RestServiceError'
description: Unauthorized - authentication required.
'403':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-403'
schema:
$ref: '#/components/schemas/RestServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-422'
schema:
$ref: '#/components/schemas/RestServiceError'
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-500'
schema:
$ref: '#/components/schemas/RestServiceError'
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/transfers:
post:
tags:
- Transfers
summary: Adyen Transfer Funds
description: '>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 [balance accounts](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts), [transfer instruments](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/transferInstruments), or third-party bank accounts. 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.'
x-addedInVersion: '2'
operationId: post-transfers
x-sortIndex: 1
x-methodName: transferFunds
security:
- clientKey: []
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
payout-cross-border:
$ref: '#/components/examples/post-transfers-payout-cross-border'
payout-local-transfer-sepa:
$ref: '#/components/examples/post-transfers-payout-local-transfer-sepa'
payout-local-transfer-us:
$ref: '#/components/examples/post-transfers-payout-local-transfer-us'
payout-to-balance-account:
$ref: '#/components/examples/post-transfers-payout-to-balance-account'
payout-to-transfer-instrument:
$ref: '#/components/examples/post-transfers-payout-to-transfer-instrument'
schema:
$ref: '#/components/schemas/TransferInfo'
parameters:
- description: Header for authenticating through SCA
example: SCA realm="Transfer" auth-param1="eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNl..."
name: WWW-Authenticate
in: header
schema:
type: string
responses:
'200':
content:
application/json:
examples:
payout-cross-border:
$ref: '#/components/examples/post-transfers-payout-cross-border-200'
payout-local-transfer-sepa:
$ref: '#/components/examples/post-transfers-payout-local-transfer-sepa-200'
payout-local-transfer-us:
$ref: '#/components/examples/post-transfers-payout-local-transfer-us-200'
payout-to-balance-account:
$ref: '#/components/examples/post-transfers-payout-to-balance-account-200'
payout-to-transfer-instrument:
$ref: '#/components/examples/post-transfers-payout-to-transfer-instrument-200'
schema:
$ref: '#/components/schemas/Transfer'
description: OK - the request has succeeded.
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/Transfer'
examples:
post-transfers202Example:
summary: Default post-transfers 202 response
x-microcks-default: true
value:
accountHolder: example_value
amount: 1000
balanceAccount: example_value
category: bank
categoryData: example_value
counterparty: example_value
creationDate: '2025-03-15T14:30:00Z'
description: A sample description for this resource.
direction: incoming
id: '500123'
paymentInstrument: example_value
reason: amountLimitExceeded
reference: REF-001
referenceForBeneficiary: REF-001
status: approvalPending
description: Accepted - the request has been accepted for processing, but the processing has not been completed.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-transfers401Example:
summary: Default post-transfers 401 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
headers:
auth-param1:
$ref: '#/components/headers/auth-param1'
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
post-transfers403Example:
summary: Default post-transfers 403 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
post-transfers422Example:
summary: Default post-transfers 422 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
post-transfers500Example:
summary: Default post-transfers 500 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/transfers/{transferId}/returns:
post:
tags:
- Transfers
summary: Adyen Return a Transfer
description: Returns previously transferred funds without creating a new `transferId`.
x-addedInVersion: '3'
operationId: post-transfers-transferId-returns
x-sortIndex: 2
x-methodName: returnTransfer
security:
- clientKey: []
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ReturnTransferRequest'
parameters:
- description: The unique identifier of the transfer to be returned.
name: transferId
in: path
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ReturnTransferResponse'
examples:
post-transfers-transferId-returns200Example:
summary: Default post-transfers-transferId-returns 200 response
x-microcks-default: true
value:
id: '500123'
reference: REF-001
status: Authorised
transferId: '500123'
description: OK - the request has succeeded.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
post-transfers-transferId-returns401Example:
summary: Default post-transfers-transferId-returns 401 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
post-transfers-transferId-returns403Example:
summary: Default post-transfers-transferId-returns 403 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
post-transfers-transferId-returns422Example:
summary: Default post-transfers-transferId-returns 422 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
post-transfers-transferId-returns500Example:
summary: Default post-transfers-transferId-returns 500 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
NameLocation:
properties:
city:
description: The city where the merchant is located.
type: string
country:
description: The country where the merchant is located in [three-letter country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) format.
type: string
countryOfOrigin:
description: The home country in [three-digit country code](https://en.wikipedia.org/wiki/ISO_3166-1_numeric) format, used for government-controlled merchants such as embassies.
type: string
name:
description: The name of the merchant's shop or service.
type: string
rawData:
description: The raw data.
type: string
state:
description: The state where the merchant is located.
type: string
type: object
CALocalAccountIdentification:
additionalProperties: false
properties:
accountNumber:
description: The 5- to 12-digit bank account number, without separators or whitespace.
maxLength: 12
minLength: 5
type: string
accountType:
default: checking
description: 'The bank account type.
Possible values: **checking** or **savings**. Defaults to **checking**.'
enum:
- checking
- savings
type: string
institutionNumber:
description: The 3-digit institution number, without separators or whitespace.
maxLength: 3
minLength: 3
type: string
transitNumber:
description: The 5-digit transit number, without separators or whitespace.
maxLength: 5
minLength: 5
type: string
type:
default: caLocal
description: '**caLocal**'
enum:
- caLocal
type: string
required:
- type
- accountNumber
- institutionNumber
- transitNumber
type: object
NOLocalAccountIdentification:
additionalProperties: false
properties:
accountNumber:
description: The 11-digit bank account number, without separators or whitespace.
maxLength: 11
minLength: 11
type: string
type:
default: noLocal
description: '**noLocal**'
enum:
- noLocal
type: string
required:
- type
- accountNumber
type: object
PlatformPayment:
additionalProperties: false
properties:
modificationMerchantReference:
x-addedInVersion: '4'
description: The capture's merchant reference included in the transfer.
type: string
modificationPspReference:
x-addedInVersion: '4'
description: The capture reference included in the transfer.
type: string
paymentMerchantReference:
x-addedInVersion: '4'
description: The payment's merchant reference included in the transfer.
type: string
platformPaymentType:
x-addedInVersion: '4'
description: The type of the related split.
enum:
- AcquiringFees
- AdyenCommission
- AdyenFees
- AdyenMarkup
- BalanceAccount
- Commission
- Default
- Interchange
- PaymentFee
- Remainder
- SchemeFee
- TopUp
- VAT
type: string
pspPaymentReference:
x-addedInVersion: '4'
description: The payment reference included in the transfer.
type: string
type:
default: platformPayment
description: '**platformPayment**'
enum:
- platformPayment
type: string
type: object
BankAccountIdentificationTypeRequirement:
additionalProperties: false
properties:
bankAccountIdentificationTypes:
description: 'List of bank account identification types: eg.; [iban , numberAndBic]'
items:
enum:
- auLocal
- brLocal
- caLocal
- czLocal
- dkLocal
- hkLocal
- huLocal
- iban
- legacy
- noLocal
- numberAndBic
- nzLocal
- plLocal
- seLocal
- sgLocal
- ukLocal
- usLocal
type: string
type: array
description:
description: Specifies the bank account details for a particular route per required field in this object depending on the country of the bank account and the currency of the transfer.
type: string
type:
default: bankAccountIdentificationTypeRequirement
description: '**bankAccountIdentificationTypeRequirement**'
enum:
- bankAccountIdentificationTypeRequirement
type: string
required:
- type
type: object
TransferRouteRequest:
properties:
balanceAccountId:
description: 'The unique identifier of the source [balance account](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts__resParam_id).
Required if `counterparty` is **transferInstrumentId**.'
type: string
balancePlatform:
description: The unique identifier assigned to the balance platform associated with the account holder.
type: string
category:
description: " The type of transfer. Possible values:\n\n - **bank**: Transfer to a [transfer instrument](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/transferInstruments__resParam_id) or a bank account.\n"
enum:
- bank
type: string
counterparty:
description: The recipient of the funds transfer. A bank account or a transfer instrument.
$ref: '#/components/schemas/Counterparty'
country:
description: "The two-character ISO-3166-1 alpha-2 country code of the counterparty. For example, **US** or **NL**.\n > Either `counterparty` or `country` field must be provided in a transfer route request."
type: string
currency:
description: The three-character ISO currency code of transfer. For example, **USD** or **EUR**.
type: string
priorities:
description: 'The list of priorities for the bank transfer. Priorities set the speed at which the transfer is sent and the fees that you have to pay. Multiple values can be provided.
Possible values:
* **regular**: For normal, low-value transactions.
* **fast**: Faster way to transfer funds but has higher fees. Recommended for high-priority, low-value transactions.
* **wire**: Fastest way to transfer funds but has the highest fees. Recommended for high-priority, high-value transactions.
* **instant**: Instant way to transfer funds in [SEPA countries](https://www.ecb.europa.eu/paym/integration/retail/sepa/html/index.en.html).
* **crossBorder**: High-value transfer to a recipient in a different country.
* **internal**: Transfer to an Adyen-issued business bank account (by bank account number/IBAN).'
items:
enum:
- crossBorder
- fast
- instant
- internal
- regular
- wire
type: string
type: array
required:
- balancePlatform
- currency
- category
type: object
BRLocalAccountIdentification:
additionalProperties: false
properties:
accountNumber:
description: The bank account number, without separators or whitespace.
maxLength: 10
minLength: 1
type: string
bankCode:
description: The 3-digit bank code, with leading zeros.
maxLength: 3
minLength: 3
type: string
branchNumber:
description: The bank account branch number, without separators or whitespace.
maxLength: 4
minLength: 1
type: string
type:
default: brLocal
description: '**brLocal**'
enum:
- brLocal
type: string
required:
- type
- branchNumber
- accountNumber
- bankCode
type: object
JSONObject:
type: object
MerchantData:
properties:
acquirerId:
description: The unique identifier of the merchant's acquirer.
type: string
mcc:
description: The merchant category code.
type: string
merchantId:
description: The merchant identifier.
type: string
nameLocation:
description: Contains the merchant's name and location.
$ref: '#/components/schemas/NameLocation'
postalCode:
description: The merchant postal code.
type: string
type: object
CounterpartyV3:
properties:
balanceAccountId:
description: Unique identifier of the [balance account](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts__resParam_id).
type: string
bankAccount:
description: Contains information about the bank account.
$ref: '#/components/schemas/BankAccountV3'
merchant:
description: Contains information about the merchant.
$ref: '#/components/schemas/MerchantData'
transferInstrumentId:
description: Unique identifier of the [transfer instrument](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/transferInstruments__resParam_id).
type: string
type: object
ReturnTransferRequest:
properties:
amount:
description: Contains information about the amount to be returned.
$ref: '#/components/schemas/Amount'
reference:
description: 'Your internal reference for the return. If you don''t provide this in the request, Adyen generates a unique reference. This reference is used in all communication with you about the instruction status.
We recommend using a unique value per instruction.
If you need to provide multiple references for a transaction, separate them with hyphens ("-").
'
maxLength: 80
type: string
required:
- amount
type: object
NZLocalAccountIdentification:
additionalProperties: false
properties:
accountNumber:
description: The 15-16 digit bank account number. The first 2 digits are the bank number, the next 4 digits are the branch number, the next 7 digits are the account number, and the final 2-3 digits are the suffix.
maxLength: 16
minLength: 15
type: string
type:
default: nzLocal
description: '**nzLocal**'
enum:
- nzLocal
type: string
required:
- type
- accountNumber
type: object
NumberAndBicAccountIdentification:
additionalProperties: false
properties:
accountNumber:
description: The bank account number, without separators or whitespace. The length and format depends on the bank or country.
maxLength: 34
type: string
additionalBankIdentification:
description: Additional identification codes of the bank. Some banks may require these identifiers for cross-border transfers.
$ref: '#/components/schemas/AdditionalBankIdentification'
bic:
description: The bank's 8- or 11-character BIC or SWIFT code.
maxLength: 11
minLength: 8
type: string
type:
default: numberAndBic
description: '**numberAndBic**'
enum:
- numberAndBic
type: string
required:
- type
- accountNumber
- bic
type: object
AdditionalBankIdentification:
properties:
code:
description: The value of the additional bank identification.
type: string
type:
description: "The type of additional bank identification, depending on the country.\n\nPossible values:\n\n * **gbSortCode**: The 6-digit [UK sort code](https://en.wikipedia.org/wiki/Sort_code), without separators or spaces\n * **usRoutingNumber**: The 9-digit [routing number](https://en.wikipedia.org/wiki/ABA_routing_transit_number), without separators or spaces."
enum:
- gbSortCode
- usRoutingNumber
type: string
type: object
TransferRouteResponse:
properties:
transferRoutes:
description: List of available priorities for a transfer, along with requirements. Use this information to initiate a transfer.
items:
$ref: '#/components/schemas/TransferRoute'
type: array
type: object
CZLocalAccountIdentification:
additionalProperties: false
properties:
accountNumber:
description: 'The 2- to 16-digit bank account number (slo tu) in the following format:
- The optional prefix (pedsl).
- The required second part (zkladn st) which must be at least two non-zero digits.
Examples:
- **19-123457** (with prefix)
- **123457** (without prefix)
- **000019-0000123457** (with prefix, normalized)
- **000000-0000123457** (without prefix, normalized)'
maxLength: 17
minLength: 2
type: string
bankCode:
description: The 4-digit bank code (Kd banky), without separators or whitespace.
# --- truncated at 32 KB (91 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adyen/refs/heads/main/openapi/adyen-transfers-api-openapi.yml