Files
adyen-openapi/yaml/FundService-v6.yaml
Adyen Automation 8e528c4487 spec release
2024-09-16 13:58:33 +02:00

1908 lines
69 KiB
YAML

openapi: 3.1.0
servers:
- url: https://cal-test.adyen.com/cal/services/Fund/v6
info:
version: '6'
x-publicVersion: true
title: Fund 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/adyen-for-platforms-model)\
\ instead.\n\nThe Fund API provides endpoints for managing the funds in the accounts\
\ on your platform. These management operations include, for example, the transfer\
\ of funds from one account to another, the payout of funds to an account holder,\
\ and the retrieval of balances in an account.\n\nFor more information, refer\
\ to our [documentation](https://docs.adyen.com/classic-platforms).\n## Authentication\n\
Your 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```\n\
When 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 Fund 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/Fund/v6/accountHolderBalance\n\
```"
termsOfService: https://www.adyen.com/legal/terms-and-conditions
contact:
name: Adyen Developer Experience team
url: https://github.com/Adyen/adyen-openapi
tags:
- name: General
- name: Migration
paths:
/accountHolderBalance:
post:
tags:
- General
summary: Get the balances of an account holder
description: 'Returns the account balances of an account holder. An account''s
balances are organized according by currencies. This mean that an account
may have multiple balances: one for each currency.'
operationId: post-accountHolderBalance
x-sortIndex: 1
x-methodName: accountHolderBalance
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
basic:
$ref: '#/components/examples/post-accountHolderBalance-basic'
schema:
$ref: '#/components/schemas/AccountHolderBalanceRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AccountHolderBalanceResponse'
description: OK - the request has succeeded.
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/AccountHolderBalanceResponse'
description: Accepted - the request has been accepted for processing, but
the processing has not been completed.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
/accountHolderTransactionList:
post:
tags:
- General
summary: Get a list of transactions
description: Returns a list of transactions for an account holder's accounts.
You can specify the accounts and transaction statuses to be included on the
list. The call returns a maximum of 50 transactions for each account. To retrieve
all transactions, you must make another call with the 'page' value incremented.
Transactions are listed in chronological order, with the most recent transaction
first.
operationId: post-accountHolderTransactionList
x-sortIndex: 2
x-methodName: accountHolderTransactionList
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
basic:
$ref: '#/components/examples/post-accountHolderTransactionList-basic'
specific:
$ref: '#/components/examples/post-accountHolderTransactionList-specific'
schema:
$ref: '#/components/schemas/AccountHolderTransactionListRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AccountHolderTransactionListResponse'
description: OK - the request has succeeded.
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/AccountHolderTransactionListResponse'
description: Accepted - the request has been accepted for processing, but
the processing has not been completed.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
/debitAccountHolder:
post:
tags:
- General
summary: Send a direct debit request
description: "Sends a direct debit request to an account holder's bank account.\
\ If the direct debit is successful, the funds are settled in the accounts\
\ specified in the split instructions. Adyen sends the result of the direct\
\ debit in a [`DIRECT_DEBIT_INITIATED`](https://docs.adyen.com/api-explorer/#/NotificationService/latest/post/DIRECT_DEBIT_INITIATED)\
\ notification webhook.\n\n To learn more about direct debits, see [Top up\
\ accounts](https://docs.adyen.com/classic-platforms/top-up-accounts)."
operationId: post-debitAccountHolder
x-sortIndex: 8
x-methodName: debitAccountHolder
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
debit-account-holder:
$ref: '#/components/examples/post-debitAccountHolder-debit-account-holder'
schema:
$ref: '#/components/schemas/DebitAccountHolderRequest'
responses:
'200':
content:
application/json:
examples:
debit-account-holder:
$ref: '#/components/examples/post-debitAccountHolder-debit-account-holder-200'
schema:
$ref: '#/components/schemas/DebitAccountHolderResponse'
description: OK - the request has succeeded.
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/DebitAccountHolderResponse'
description: Accepted - the request has been accepted for processing, but
the processing has not been completed.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
/payoutAccountHolder:
post:
tags:
- General
summary: Pay out from an account to the account holder
description: Pays out a specified amount from an account to the bank account
of account holder.
operationId: post-payoutAccountHolder
x-sortIndex: 3
x-methodName: payoutAccountHolder
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
oneOff:
$ref: '#/components/examples/post-payoutAccountHolder-oneOff'
schema:
$ref: '#/components/schemas/PayoutAccountHolderRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutAccountHolderResponse'
description: OK - the request has succeeded.
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutAccountHolderResponse'
description: Accepted - the request has been accepted for processing, but
the processing has not been completed.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
/refundFundsTransfer:
post:
tags:
- General
summary: Refund a funds transfer
description: 'Refunds funds transferred from one account to another. Both accounts
must be in the same platform, but can have different account holders. '
operationId: post-refundFundsTransfer
x-sortIndex: 5
x-methodName: refundFundsTransfer
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
basic:
$ref: '#/components/examples/post-refundFundsTransfer-basic'
schema:
$ref: '#/components/schemas/RefundFundsTransferRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RefundFundsTransferResponse'
description: OK - the request has succeeded.
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/RefundFundsTransferResponse'
description: Accepted - the request has been accepted for processing, but
the processing has not been completed.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
/refundNotPaidOutTransfers:
post:
tags:
- General
summary: Refund all transactions of an account since the most recent payout
description: Refunds all the transactions of an account that have taken place
since the most recent payout. This request is on a account basis (as opposed
to a payment basis), so only the portion of the payment that was made to the
specified account is refunded. The commissions, fees, and payments to other
accounts remain in the accounts to which they were sent as designated by the
original payment's split details.
operationId: post-refundNotPaidOutTransfers
x-sortIndex: 7
x-methodName: refundNotPaidOutTransfers
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
basic:
$ref: '#/components/examples/post-refundNotPaidOutTransfers-basic'
schema:
$ref: '#/components/schemas/RefundNotPaidOutTransfersRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RefundNotPaidOutTransfersResponse'
description: OK - the request has succeeded.
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/RefundNotPaidOutTransfersResponse'
description: Accepted - the request has been accepted for processing, but
the processing has not been completed.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
/setupBeneficiary:
post:
tags:
- General
summary: Designate a beneficiary account and transfer the benefactor's current
balance
description: Defines a benefactor and a beneficiary relationship between two
accounts. At the time of benefactor/beneficiary setup, the funds in the benefactor
account are transferred to the beneficiary account, and any further payments
to the benefactor account are automatically sent to the beneficiary account.
A series of benefactor/beneficiaries may not exceed four beneficiaries and
may not have a cycle in it.
operationId: post-setupBeneficiary
x-sortIndex: 6
x-methodName: setupBeneficiary
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
basic:
$ref: '#/components/examples/post-setupBeneficiary-basic'
schema:
$ref: '#/components/schemas/SetupBeneficiaryRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SetupBeneficiaryResponse'
description: OK - the request has succeeded.
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/SetupBeneficiaryResponse'
description: Accepted - the request has been accepted for processing, but
the processing has not been completed.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
/transferFunds:
post:
tags:
- General
summary: Transfer funds between platform accounts
description: Transfers funds from one account to another account. Both accounts
must be in the same platform, but can have different account holders. The
transfer must include a transfer code, which should be determined by the platform,
in compliance with local regulations.
operationId: post-transferFunds
x-sortIndex: 4
x-methodName: transferFunds
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
basic:
$ref: '#/components/examples/post-transferFunds-basic'
schema:
$ref: '#/components/schemas/TransferFundsRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TransferFundsResponse'
description: OK - the request has succeeded.
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/TransferFundsResponse'
description: Accepted - the request has been accepted for processing, but
the processing has not been completed.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
components:
schemas:
AccountDetailBalance:
additionalProperties: false
properties:
accountCode:
description: The code of the account that holds the balance.
type: string
detailBalance:
description: Details of the balance held by the account.
$ref: '#/components/schemas/DetailBalance'
type: object
AccountHolderBalanceRequest:
additionalProperties: false
properties:
accountHolderCode:
description: The code of the Account Holder of which to retrieve the balance.
type: string
required:
- accountHolderCode
type: object
AccountHolderBalanceResponse:
additionalProperties: false
properties:
balancePerAccount:
description: A list of each account and their balances.
items:
$ref: '#/components/schemas/AccountDetailBalance'
type: array
invalidFields:
x-addedInVersion: '5'
description: Contains field validation errors that would prevent requests
from being processed.
items:
$ref: '#/components/schemas/ErrorFieldType'
type: array
pspReference:
description: The reference of a request. Can be used to uniquely identify
the request.
type: string
resultCode:
description: The result code.
type: string
totalBalance:
description: The total balance of the account holder.
$ref: '#/components/schemas/DetailBalance'
type: object
AccountHolderTransactionListRequest:
additionalProperties: false
properties:
accountHolderCode:
description: The code of the account holder that owns the account(s) of
which retrieve the transaction list.
type: string
transactionListsPerAccount:
description: A list of accounts to include in the transaction list. If left
blank, the last fifty (50) transactions for all accounts of the account
holder will be included.
items:
$ref: '#/components/schemas/TransactionListForAccount'
type: array
transactionStatuses:
description: 'A list of statuses to include in the transaction list. If
left blank, all transactions will be included.
>Permitted values:
>* `PendingCredit` - a pending balance credit.
>* `CreditFailed` - a pending credit failure; the balance will not be
credited.
>* `Credited` - a credited balance.
>* `PendingDebit` - a pending balance debit (e.g., a refund).
>* `CreditClosed` - a pending credit closed; the balance will not be credited.
>* `CreditSuspended` - a pending credit closed; the balance will not be
credited.
>* `DebitFailed` - a pending debit failure; the balance will not be debited.
>* `Debited` - a debited balance (e.g., a refund).
>* `DebitReversedReceived` - a pending refund reversal.
>* `DebitedReversed` - a reversed refund.
>* `ChargebackReceived` - a received chargeback request.
>* `Chargeback` - a processed chargeback.
>* `ChargebackReversedReceived` - a pending chargeback reversal.
>* `ChargebackReversed` - a reversed chargeback.
>* `Converted` - converted.
>* `ManualCorrected` - manual booking/adjustment by Adyen.
>* `Payout` - a payout.
>* `PayoutReversed` - a reversed payout.
>* `PendingFundTransfer` - a pending transfer of funds from one account
to another.
>* `FundTransfer` - a transfer of funds from one account to another.'
items:
enum:
- BalanceNotPaidOutTransfer
- BalancePlatformFundTransfer
- BalancePlatformSweep
- BalancePlatformSweepReturned
- Chargeback
- ChargebackCorrection
- ChargebackCorrectionReceived
- ChargebackReceived
- ChargebackReversed
- ChargebackReversedCorrection
- ChargebackReversedCorrectionReceived
- ChargebackReversedReceived
- Converted
- CreditClosed
- CreditFailed
- CreditReversed
- CreditReversedReceived
- CreditSuspended
- Credited
- DebitFailed
- DebitReversedReceived
- Debited
- DebitedReversed
- DepositCorrectionCredited
- DepositCorrectionDebited
- DepositCorrectionReceived
- Fee
- FeeReceived
- FundTransfer
- FundTransferReversed
- InvoiceDeductionCredited
- InvoiceDeductionDebited
- InvoiceDeductionReceived
- ManualCorrected
- ManualCorrectionCredited
- ManualCorrectionDebited
- MerchantPayin
- MerchantPayinReceived
- MerchantPayinReversed
- Payout
- PayoutReversed
- PendingCredit
- PendingDebit
- PendingFundTransfer
- ReCredited
- ReCreditedReceived
- SecondChargeback
- SecondChargebackCorrection
- SecondChargebackCorrectionReceived
- SecondChargebackReceived
type: string
type: array
required:
- accountHolderCode
type: object
AccountHolderTransactionListResponse:
additionalProperties: false
properties:
accountTransactionLists:
description: A list of the transactions.
items:
$ref: '#/components/schemas/AccountTransactionList'
type: array
invalidFields:
x-addedInVersion: '5'
description: Contains field validation errors that would prevent requests
from being processed.
items:
$ref: '#/components/schemas/ErrorFieldType'
type: array
pspReference:
description: The reference of a request. Can be used to uniquely identify
the request.
type: string
resultCode:
description: The result code.
type: string
type: object
AccountTransactionList:
additionalProperties: false
properties:
accountCode:
description: The code of the account.
type: string
hasNextPage:
description: Indicates whether there is a next page of transactions available.
type: boolean
transactions:
description: The list of transactions.
items:
$ref: '#/components/schemas/Transaction'
type: array
type: object
Amount:
additionalProperties: false
properties:
currency:
description: The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes).
maxLength: 3
minLength: 3
type: string
value:
description: The amount of the transaction, in [minor units](https://docs.adyen.com/development-resources/currency-codes).
format: int64
type: integer
required:
- value
- currency
type: object
BankAccountDetail:
additionalProperties: false
properties:
accountNumber:
description: 'The bank account number (without separators).
>Refer to [Required information](https://docs.adyen.com/classic-platforms/verification-process/required-information)
for details on field requirements.'
type: string
accountType:
description: 'The type of bank account.
Only applicable to bank accounts held in the USA.
The permitted values are: `checking`, `savings`.
>Refer to [Required information](https://docs.adyen.com/classic-platforms/verification-process/required-information)
for details on field requirements.'
type: string
bankAccountName:
description: The name of the bank account.
type: string
bankAccountReference:
x-addedInVersion: '5'
description: Merchant reference to the bank account.
type: string
bankAccountUUID:
description: 'The unique identifier (UUID) of the Bank Account.
>If, during an account holder create or update request, this field is
left blank (but other fields provided), a new Bank Account will be created
with a procedurally-generated UUID.
>If, during an account holder create request, a UUID is provided, the
creation of the Bank Account will fail while the creation of the account
holder will continue.
>If, during an account holder update request, a UUID that is not correlated
with an existing Bank Account is provided, the update of the account holder
will fail.
>If, during an account holder update request, a UUID that is correlated
with an existing Bank Account is provided, the existing Bank Account will
be updated.
'
type: string
bankBicSwift:
description: 'The bank identifier code.
>Refer to [Required information](https://docs.adyen.com/classic-platforms/verification-process/required-information)
for details on field requirements.'
type: string
bankCity:
description: 'The city in which the bank branch is located.
>Refer to [Required information](https://docs.adyen.com/classic-platforms/verification-process/required-information)
for details on field requirements.'
type: string
bankCode:
description: 'The bank code of the banking institution with which the bank
account is registered.
>Refer to [Required information](https://docs.adyen.com/classic-platforms/verification-process/required-information)
for details on field requirements.'
type: string
bankName:
description: 'The name of the banking institution with which the bank account
is held.
>Refer to [Required information](https://docs.adyen.com/classic-platforms/verification-process/required-information)
for details on field requirements.'
type: string
branchCode:
description: 'The branch code of the branch under which the bank account
is registered. The value to be specified in this parameter depends on
the country of the bank account:
* United States - Routing number
* United Kingdom - Sort code
* Germany - Bankleitzahl
>Refer to [Required information](https://docs.adyen.com/classic-platforms/verification-process/required-information)
for details on field requirements.'
type: string
checkCode:
description: 'The check code of the bank account.
>Refer to [Required information](https://docs.adyen.com/classic-platforms/verification-process/required-information)
for details on field requirements.'
type: string
countryCode:
description: 'The two-letter country code in which the bank account is registered.
>The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. ''NL'').
>Refer to [Required information](https://docs.adyen.com/classic-platforms/verification-process/required-information)
for details on field requirements.'
type: string
currencyCode:
description: 'The currency in which the bank account deals.
>The permitted currency codes are defined in ISO-4217 (e.g. ''EUR'').
'
type: string
iban:
description: 'The international bank account number.
>The IBAN standard is defined in ISO-13616.
>Refer to [Required information](https://docs.adyen.com/classic-platforms/verification-process/required-information)
for details on field requirements.'
type: string
ownerCity:
description: 'The city of residence of the bank account owner.
>Refer to [Required information](https://docs.adyen.com/classic-platforms/verification-process/required-information)
for details on field requirements.'
type: string
ownerCountryCode:
description: 'The country code of the country of residence of the bank account
owner.
>The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. ''NL'').
>Refer to [Required information](https://docs.adyen.com/classic-platforms/verification-process/required-information)
for details on field requirements.'
type: string
ownerDateOfBirth:
deprecated: true
description: 'The date of birth of the bank account owner.
The date should be in ISO-8601 format yyyy-mm-dd (e.g. 2000-01-31).'
type: string
ownerHouseNumberOrName:
description: 'The house name or number of the residence of the bank account
owner.
>Refer to [Required information](https://docs.adyen.com/classic-platforms/verification-process/required-information)
for details on field requirements.'
type: string
ownerName:
description: 'The name of the bank account owner.
>Refer to [Required information](https://docs.adyen.com/classic-platforms/verification-process/required-information)
for details on field requirements.'
type: string
ownerNationality:
description: 'The country code of the country of nationality of the bank
account owner.
>The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. ''NL'').
>Refer to [Required information](https://docs.adyen.com/classic-platforms/verification-process/required-information)
for details on field requirements.'
type: string
ownerPostalCode:
description: 'The postal code of the residence of the bank account owner.
>Refer to [Required information](https://docs.adyen.com/classic-platforms/verification-process/required-information)
for details on field requirements.'
type: string
ownerState:
description: 'The state of residence of the bank account owner.
>Refer to [Required information](https://docs.adyen.com/classic-platforms/verification-process/required-information)
for details on field requirements.'
type: string
ownerStreet:
description: 'The street name of the residence of the bank account owner.
>Refer to [Required information](https://docs.adyen.com/classic-platforms/verification-process/required-information)
for details on field requirements.'
type: string
primaryAccount:
description: If set to true, the bank account is a primary account.
type: boolean
taxId:
description: 'The tax ID number.
>Refer to [Required information](https://docs.adyen.com/classic-platforms/verification-process/required-information)
for details on field requirements.'
type: string
urlForVerification:
description: 'The URL to be used for bank account verification.
This may be generated on bank account creation.
>Refer to [Required information](https://docs.adyen.com/classic-platforms/verification-process/required-information)
for details on field requirements.'
type: string
type: object
DebitAccountHolderRequest:
additionalProperties: false
properties:
accountHolderCode:
description: The code of the account holder.
type: string
amount:
description: The amount to be debited from the account holder's bank account.
$ref: '#/components/schemas/Amount'
bankAccountUUID:
description: The Adyen-generated unique alphanumeric identifier (UUID) of
the account holder's bank account.
type: string
description:
description: 'A description of the direct debit. Maximum length: 35 characters.
Allowed characters: **a-z**, **A-Z**, **0-9**, and special characters
**/?:().,''+ ";**.'
maxLength: 35
type: string
merchantAccount:
description: Your merchant account.
type: string
splits:
description: Contains instructions on how to split the funds between the
accounts in your platform. The request must have at least one split item.
items:
$ref: '#/components/schemas/Split'
type: array
required:
- accountHolderCode
- bankAccountUUID
- amount
- splits
- merchantAccount
type: object
DebitAccountHolderResponse:
additionalProperties: false
properties:
accountHolderCode:
description: The code of the account holder.
type: string
bankAccountUUID:
description: The Adyen-generated unique alphanumeric identifier (UUID) of
the account holder's bank account.
type: string
invalidFields:
x-addedInVersion: '5'
description: Contains field validation errors that would prevent requests
from being processed.
items:
$ref: '#/components/schemas/ErrorFieldType'
type: array
merchantReferences:
description: List of the `reference` values from the `split` array in the
request.
items:
type: string
type: array
pspReference:
description: The reference of a request. Can be used to uniquely identify
the request.
type: string
resultCode:
description: The result code.
type: string
type: object
DetailBalance:
additionalProperties: false
properties:
balance:
description: The list of balances held by the account.
items:
$ref: '#/components/schemas/Amount'
type: array
onHoldBalance:
x-addedInVersion: '5'
description: The list of on hold balances held by the account.
items:
$ref: '#/components/schemas/Amount'
type: array
pendingBalance:
description: The list of pending balances held by the account.
items:
$ref: '#/components/schemas/Amount'
type: array
type: object
ErrorFieldType:
additionalProperties: false
properties:
errorCode:
description: The validation error code.
format: int32
type: integer
errorDescription:
description: A description of the validation error.
type: string
fieldType:
description: The type of error field.
$ref: '#/components/schemas/FieldType'
type: object
FieldType:
additionalProperties: false
properties:
field:
description: The full name of the property.
type: string
fieldName:
description: The type of the field.
enum:
- accountCode
- accountHolderCode
- accountHolderDetails
- accountNumber
- accountStateType
- accountStatus
- accountType
- address
- balanceAccount
- balanceAccountActive
- balanceAccountCode
- balanceAccountId
- bankAccount
- bankAccountCode
- bankAccountName
- bankAccountUUID
- bankBicSwift
- bankCity
- bankCode
- bankName
- bankStatement
- branchCode
- businessContact
- cardToken
- checkCode
- city
- companyRegistration
- constitutionalDocument
- controller
- country
- countryCode
- currency
- currencyCode
- dateOfBirth
- description
- destinationAccountCode
- document
- documentContent
- documentExpirationDate
- documentIssuerCountry
- documentIssuerState
- documentName
- documentNumber
- documentType
- doingBusinessAs
- drivingLicence
- drivingLicenceBack
- drivingLicenceFront
- drivingLicense
- email
- firstName
- formType
- fullPhoneNumber
- gender
- hopWebserviceUser
- houseNumberOrName
- iban
- idCard
- idCardBack
- idCardFront
- idNumber
- identityDocument
- individualDetails
- infix
- jobTitle
- lastName
- lastReviewDate
- legalArrangement
- legalArrangementCode
- legalArrangementEntity
- legalArrangementEntityCode
- legalArrangementLegalForm
- legalArrangementMember
- legalArrangementMembers
- legalArrangementName
- legalArrangementReference
- legalArrangementRegistrationNumber
- legalArrangementTaxNumber
- legalArrangementType
- legalBusinessName
- legalEntity
- legalEntityType
- linkedViasVirtualAccount
- logo
- merchantAccount
- merchantCategoryCode
- merchantHouseNumber
- merchantReference
- microDeposit
- name
- nationality
- originalReference
- ownerCity
- ownerCountryCode
- ownerDateOfBirth
- ownerHouseNumberOrName
- ownerName
- ownerPostalCode
- ownerState
- ownerStreet
- passport
- passportNumber
- payoutMethod
- payoutMethodCode
- payoutSchedule
- pciSelfAssessment
- personalData
- phoneCountryCode
- phoneNumber
- postalCode
- primaryCurrency
- reason
- registrationNumber
- returnUrl
- schedule
- shareholder
- shareholderCode
- shareholderCodeAndSignatoryCode
- shareholderCodeOrSignatoryCode
- shareholderType
- shareholderTypes
- shopperInteraction
- signatory
- signatoryCode
- socialSecurityNumber
- sourceAccountCode
- splitAccount
- splitConfigurationUUID
- splitCurrency
- splitValue
- splits
- stateOrProvince
- status
- stockExchange
- stockNumber
- stockTicker
- store
- storeDetail
- storeName
- storeReference
- street
- taxId
- tier
- tierNumber
- transferCode
- ultimateParentCompany
- ultimateParentCompanyAddressDetails
- ultimateParentCompanyAddressDetailsCountry
- ultimateParentCompanyBusinessDetails
- ultimateParentCompanyBusinessDetailsLegalBusinessName
- ultimateParentCompanyBusinessDetailsRegistrationNumber
- ultimateParentCompanyCode
- ultimateParentCompanyStockExchange
- ultimateParentCompanyStockNumber
- ultimateParentCompanyStockNumberOrStockTicker
- ultimateParentCompanyStockTicker
- unknown
- value
- verificationType
- virtualAccount
- visaNumber
- webAddress
- year
type: string
shareholderCode:
description: The code of the shareholder that the field belongs to. If empty,
the field belongs to an account holder.
type: string
type: object
PayoutAccountHolderRequest:
additionalProperties: false
properties:
accountCode:
description: The code of the account from which the payout is to be made.
type: string
accountHolderCode:
description: 'The code of the Account Holder who owns the account from which
the payout is to be made.
The Account Holder is the party to which the payout will be made.'
type: string
amount:
description: 'An object containing the currency and value of the payout.
If the account has multiple currencies, specify the currency to be used.
If the `bankAccountUUID` is provided in the request, the currency supported
by the bank is used.
If the `payoutMethodCode` is provided in the request, the specified payout
method is selected.'
$ref: '#/components/schemas/Amount'
bankAccountUUID:
description: 'The unique ID of the Bank Account held by the Account Holder
to which the payout is to be made.
If left blank, a bank account is automatically selected.'
type: string
description:
description: 'A description of the payout. Maximum 200 characters.
Allowed: **abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789/?:().,''+
";**'
maxLength: 200
type: string
merchantReference:
x-addedInVersion: '2'
description: A value that can be supplied at the discretion of the executing
user in order to link multiple transactions to one another.
type: string
payoutMethodCode:
x-addedInVersion: '5'
description: 'The unique ID of the payout method held by the Account Holder
to which the payout is to be made.
If left blank, a payout instrument is automatically selected.'
type: string
payoutSpeed:
x-addedInVersion: '5'
default: STANDARD
description: 'Speed with which payouts for this account are processed. Permitted
values: `STANDARD`, `SAME_DAY`.'
enum:
- INSTANT
- SAME_DAY
- STANDARD
type: string
required:
- accountHolderCode
- accountCode
type: object
PayoutAccountHolderResponse:
additionalProperties: false
properties:
bankAccountUUID:
description: The unique ID of the Bank Account to which the payout was made.
type: string
invalidFields:
x-addedInVersion: '5'
description: Contains field validation errors that would prevent requests
from being processed.
items:
$ref: '#/components/schemas/ErrorFieldType'
type: array
merchantReference:
x-addedInVersion: '2'
description: The value supplied by the executing user when initiating the
transfer; may be used to link multiple transactions.
type: string
payoutSpeed:
x-addedInVersion: '5'
default: STANDARD
description: 'Speed with which payouts for this account are processed. Permitted
values: `STANDARD`, `SAME_DAY`.'
enum:
- INSTANT
- SAME_DAY
- STANDARD
type: string
pspReference:
description: The reference of a request. Can be used to uniquely identify
the request.
type: string
resultCode:
description: The result code.
type: string
type: object
RefundFundsTransferRequest:
additionalProperties: false
properties:
amount:
description: The amount to be transferred.
$ref: '#/components/schemas/Amount'
merchantReference:
description: A value that can be supplied at the discretion of the executing
user in order to link multiple transactions to one another.
type: string
originalReference:
description: A PSP reference of the original fund transfer.
type: string
required:
- originalReference
- amount
type: object
RefundFundsTransferResponse:
additionalProperties: false
properties:
invalidFields:
x-addedInVersion: '5'
description: Contains field validation errors that would prevent requests
from being processed.
items:
$ref: '#/components/schemas/ErrorFieldType'
type: array
merchantReference:
description: The value supplied by the executing user when initiating the
transfer refund; may be used to link multiple transactions.
type: string
message:
description: The message of the response.
type: string
originalReference:
description: A PSP reference of the original fund transfer.
type: string
pspReference:
description: The reference of a request. Can be used to uniquely identify
the request.
type: string
resultCode:
description: The result code.
type: string
type: object
RefundNotPaidOutTransfersRequest:
additionalProperties: false
properties:
accountCode:
description: The code of the account from which to perform the refund(s).
type: string
accountHolderCode:
description: The code of the Account Holder which owns the account from
which to perform the refund(s).
type: string
required:
- accountHolderCode
- accountCode
type: object
RefundNotPaidOutTransfersResponse:
additionalProperties: false
properties:
invalidFields:
x-addedInVersion: '5'
description: Contains field validation errors that would prevent requests
from being processed.
items:
$ref: '#/components/schemas/ErrorFieldType'
type: array
pspReference:
description: The reference of a request. Can be used to uniquely identify
the request.
type: string
resultCode:
description: The result code.
type: string
type: object
ServiceError:
additionalProperties: false
properties:
errorCode:
description: The error code mapped to the error message.
type: string
errorType:
description: The category of the error.
type: string
message:
description: A short explanation of the issue.
type: string
pspReference:
description: The PSP reference of the payment.
type: string
status:
description: The HTTP response status.
format: int32
type: integer
type: object
SetupBeneficiaryRequest:
additionalProperties: false
properties:
destinationAccountCode:
description: The destination account code.
type: string
merchantReference:
description: A value that can be supplied at the discretion of the executing
user.
type: string
sourceAccountCode:
description: The benefactor account.
type: string
required:
- sourceAccountCode
- destinationAccountCode
type: object
SetupBeneficiaryResponse:
additionalProperties: false
properties:
invalidFields:
x-addedInVersion: '5'
description: Contains field validation errors that would prevent requests
from being processed.
items:
$ref: '#/components/schemas/ErrorFieldType'
type: array
pspReference:
description: The reference of a request. Can be used to uniquely identify
the request.
type: string
resultCode:
description: The result code.
type: string
type: object
Split:
additionalProperties: false
properties:
account:
description: 'The unique identifier of the account to which the split amount
is booked. Required if `type` is **MarketPlace** or **BalanceAccount**.
* [Classic Platforms integration](https://docs.adyen.com/classic-platforms):
The [`accountCode`](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccount#request-accountCode)
of the account to which the split amount is booked.
* [Balance Platform](https://docs.adyen.com/adyen-for-platforms-model):
The [`balanceAccountId`](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balanceAccounts/_id_#path-id)
of the account to which the split amount is booked.'
type: string
amount:
description: 'The amount of the split item.
* Required for all split types in the [Classic Platforms integration](https://docs.adyen.com/classic-platforms).
* Required if `type` is **BalanceAccount**, **Commission**, **Default**,
or **VAT** in your [Balance Platform](https://docs.adyen.com/adyen-for-platforms-model)
integration.'
$ref: '#/components/schemas/SplitAmount'
description:
description: Your description for the split item.
type: string
reference:
description: 'Your unique reference for the part of the payment booked to
the specified `account`.
This is required if `type` is **MarketPlace** ([Classic Platforms integration](https://docs.adyen.com/classic-platforms))
or **BalanceAccount** ([Balance Platform](https://docs.adyen.com/adyen-for-platforms-model)).
For the other types, we also recommend providing a **unique** reference
so you can reconcile the split and the associated payment in the transaction
overview and in the reports.'
type: string
type:
description: "The part of the payment you want to book to the specified\
\ `account`.\n\nPossible values for the [Balance Platform](https://docs.adyen.com/adyen-for-platforms-model):\n\
* **BalanceAccount**: books part of the payment (specified in `amount`)\
\ to the specified `account`.\n* Transaction fees types that you can book\
\ to the specified `account`:\n * **AcquiringFees**: the aggregated\
\ amount of the interchange and scheme fees.\n * **PaymentFee**: the\
\ aggregated amount of all transaction fees.\n * **AdyenFees**: the\
\ aggregated amount of Adyen's commission and markup fees.\n * **AdyenCommission**:\
\ the transaction fees due to Adyen under [blended rates](https://www.adyen.com/knowledge-hub/interchange-fees-explained).\n\
\ * **AdyenMarkup**: the transaction fees due to Adyen under [Interchange\
\ ++ pricing](https://www.adyen.com/knowledge-hub/interchange-fees-explained).\n\
\ * **Interchange**: the fees paid to the issuer for each payment made\
\ with the card network.\n * **SchemeFee**: the fees paid to the card\
\ scheme for using their network. \n* **Commission**: your platform's\
\ commission on the payment (specified in `amount`), booked to your liable\
\ balance account.\n* **Remainder**: the amount left over after a currency\
\ conversion, booked to the specified `account`.\n* **TopUp**: allows\
\ you and your users to top up balance accounts using direct debit, card\
\ payments, or other payment methods.\n* **VAT**: the value-added tax\
\ charged on the payment, booked to your platforms liable balance account.\n\
* **Commission**: your platform's commission (specified in `amount`) on\
\ the payment, booked to your liable balance account.\n* **Default**:\
\ in very specific use cases, allows you to book the specified `amount`\
\ to the specified `account`. For more information, contact Adyen support.\n\
\nPossible values for the [Classic Platforms integration](https://docs.adyen.com/classic-platforms):\
\ **Commission**, **Default**, **Marketplace**, **PaymentFee**, **VAT**."
enum:
- AcquiringFees
- AdyenCommission
- AdyenFees
- AdyenMarkup
- BalanceAccount
- Commission
- Default
- Interchange
- MarketPlace
- PaymentFee
- Remainder
- SchemeFee
- Surcharge
- Tip
- VAT
type: string
required:
- type
type: object
SplitAmount:
additionalProperties: false
properties:
currency:
description: The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes).
By default, this is the original payment currency.
maxLength: 3
minLength: 3
type: string
value:
description: The value of the split amount, in [minor units](https://docs.adyen.com/development-resources/currency-codes).
format: int64
type: integer
required:
- value
type: object
Transaction:
additionalProperties: false
properties:
amount:
description: The amount of the transaction.
$ref: '#/components/schemas/Amount'
bankAccountDetail:
description: The details of the bank account to where a payout was made.
$ref: '#/components/schemas/BankAccountDetail'
captureMerchantReference:
description: The merchant reference of a related capture.
type: string
capturePspReference:
description: The psp reference of a related capture.
type: string
creationDate:
description: The date on which the transaction was performed.
format: date-time
type: string
description:
description: A description of the transaction.
type: string
destinationAccountCode:
description: The code of the account to which funds were credited during
an outgoing fund transfer.
type: string
disputePspReference:
description: The psp reference of the related dispute.
type: string
disputeReasonCode:
description: The reason code of a dispute.
type: string
merchantReference:
description: The merchant reference of a transaction.
type: string
paymentPspReference:
x-addedInVersion: '3'
description: The psp reference of the related authorisation or transfer.
type: string
payoutPspReference:
x-addedInVersion: '3'
description: The psp reference of the related payout.
type: string
pspReference:
description: The psp reference of a transaction.
type: string
sourceAccountCode:
description: The code of the account from which funds were debited during
an incoming fund transfer.
type: string
transactionStatus:
description: 'The status of the transaction.
>Permitted values: `PendingCredit`, `CreditFailed`, `CreditClosed`, `CreditSuspended`,
`Credited`, `Converted`, `PendingDebit`, `DebitFailed`, `Debited`, `DebitReversedReceived`,
`DebitedReversed`, `ChargebackReceived`, `Chargeback`, `ChargebackReversedReceived`,
`ChargebackReversed`, `Payout`, `PayoutReversed`, `FundTransfer`, `PendingFundTransfer`,
`ManualCorrected`.'
enum:
- BalanceNotPaidOutTransfer
- BalancePlatformFundTransfer
- BalancePlatformSweep
- BalancePlatformSweepReturned
- Chargeback
- ChargebackCorrection
- ChargebackCorrectionReceived
- ChargebackReceived
- ChargebackReversed
- ChargebackReversedCorrection
- ChargebackReversedCorrectionReceived
- ChargebackReversedReceived
- Converted
- CreditClosed
- CreditFailed
- CreditReversed
- CreditReversedReceived
- CreditSuspended
- Credited
- DebitFailed
- DebitReversedReceived
- Debited
- DebitedReversed
- DepositCorrectionCredited
- DepositCorrectionDebited
- DepositCorrectionReceived
- Fee
- FeeReceived
- FundTransfer
- FundTransferReversed
- InvoiceDeductionCredited
- InvoiceDeductionDebited
- InvoiceDeductionReceived
- ManualCorrected
- ManualCorrectionCredited
- ManualCorrectionDebited
- MerchantPayin
- MerchantPayinReceived
- MerchantPayinReversed
- Payout
- PayoutReversed
- PendingCredit
- PendingDebit
- PendingFundTransfer
- ReCredited
- ReCreditedReceived
- SecondChargeback
- SecondChargebackCorrection
- SecondChargebackCorrectionReceived
- SecondChargebackReceived
type: string
transferCode:
description: The transfer code of the transaction.
type: string
type: object
TransactionListForAccount:
additionalProperties: false
properties:
accountCode:
description: The account for which to retrieve the transactions.
type: string
page:
description: 'The page of transactions to retrieve.
Each page lists fifty (50) transactions. The most recent transactions
are included on page 1.'
format: int32
type: integer
required:
- accountCode
- page
type: object
TransferFundsRequest:
additionalProperties: false
properties:
amount:
description: The amount to be transferred.
$ref: '#/components/schemas/Amount'
destinationAccountCode:
description: 'The code of the account to which the funds are to be credited.
>The state of the Account Holder of this account must be Active.'
type: string
merchantReference:
x-addedInVersion: '2'
description: A value that can be supplied at the discretion of the executing
user in order to link multiple transactions to one another.
type: string
sourceAccountCode:
description: 'The code of the account from which the funds are to be debited.
>The state of the Account Holder of this account must be Active and allow
payouts.'
type: string
transferCode:
description: 'The code related to the type of transfer being performed.
>The permitted codes differ for each platform account and are defined
in their service level agreement.'
type: string
required:
- sourceAccountCode
- destinationAccountCode
- transferCode
- amount
type: object
TransferFundsResponse:
additionalProperties: false
properties:
invalidFields:
x-addedInVersion: '5'
description: Contains field validation errors that would prevent requests
from being processed.
items:
$ref: '#/components/schemas/ErrorFieldType'
type: array
merchantReference:
x-addedInVersion: '2'
description: The value supplied by the executing user when initiating the
transfer; may be used to link multiple transactions.
type: string
pspReference:
description: The reference of a request. Can be used to uniquely identify
the request.
type: string
resultCode:
description: The result code.
type: string
type: object
securitySchemes:
ApiKeyAuth:
in: header
name: X-API-Key
type: apiKey
BasicAuth:
scheme: basic
type: http
examples:
post-accountHolderBalance-basic:
summary: Review the account holder balance
value:
accountHolderCode: CODE_OF_ACCOUNT_HOLDER
post-accountHolderTransactionList-basic:
summary: Retrieve transactions page by page
value:
accountHolderCode: CODE_OF_ACCOUNT_HOLDER
transactionListsPerAccount:
- accountCode: '195752115'
page: 1
post-accountHolderTransactionList-specific:
summary: Retrieve transactions with specific statuses.
value:
accountHolderCode: CODE_OF_ACCOUNT_HOLDER
transactionStatuses:
- PendingCredit
- Credited
- Debited
transactionListsPerAccount:
- accountCode: 2e64b396-1200-4474-b848-0cb06b52b3c7
page: 2
post-debitAccountHolder-debit-account-holder:
summary: Send a bank account direct debit
description: Example request to send a direct debit from a bank account
value:
accountHolderCode: ACCOUNT_HOLDER_CODE
description: YOUR_DESCRIPTION
bankAccountUUID: 000b81aa-ae7e-4492-aa7e-72b2129dce0c
amount:
value: 6200
currency: USD
merchantAccount: YOUR_MERCHANT_ACCOUNT
splits:
- amount:
value: 6000
type: MarketPlace
account: '8535516988037431'
reference: YOUR_SPLIT_REFERENCE_1
- amount:
value: 200
type: Commission
reference: YOUR_SPLIT_REFERENCE_2
post-debitAccountHolder-debit-account-holder-200:
summary: Direct debit request sent
description: Example response for requesting a direct debit from a bank account
value:
pspReference: '8816480354727275'
submittedAsync: 'false'
post-payoutAccountHolder-oneOff:
summary: One-off payout
value:
accountCode: '118731451'
amount:
currency: EUR
value: 99792
accountHolderCode: CODE_OF_ACCOUNT_HOLDER
description: "12345 \u2013 Test"
bankAccountUUID: 000b81aa-ae7e-4492-aa7e-72b2129dce0c
post-refundFundsTransfer-basic:
summary: Refund the fund transfer
value:
originalReference: PSP_REFERENCE_OF_TRANSFER_TO_REFUND
amount:
currency: EUR
value: 1000
merchantReference: YOUR_REFERENCE_ID
post-refundNotPaidOutTransfers-basic:
summary: Refund last transactions
value:
accountHolderCode: CODE_OF_ACCOUNT_HOLDER
accountCode: '189184578'
post-setupBeneficiary-basic:
summary: Set up a beneficiary
value:
destinationAccountCode: '128952522'
merchantReference: YOUR_REFERENCE_ID
sourceAccountCode: '134498192'
post-transferFunds-basic:
summary: Transfer funds from one account to another
value:
sourceAccountCode: '100000000'
destinationAccountCode: '190324759'
amount:
currency: EUR
value: 2000
transferCode: TransferCode_1