openapi: 3.1.0
info:
version: '6'
x-publicVersion: true
title: Adyen Account acceptDispute getAccountHolder 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: getAccountHolder
paths:
/getAccountHolder:
post:
tags:
- getAccountHolder
summary: Adyen Get an Account Holder
description: Returns the details of an account holder.
operationId: post-getAccountHolder
x-groupName: Account holders
x-sortIndex: 2
x-methodName: getAccountHolder
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
accountCode:
$ref: '#/components/examples/post-getAccountHolder-accountCode'
accountHolderCode:
$ref: '#/components/examples/post-getAccountHolder-accountHolderCode'
schema:
$ref: '#/components/schemas/GetAccountHolderRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetAccountHolderResponse'
examples:
post-getAccountHolder200Example:
summary: Default post-getAccountHolder 200 response
x-microcks-default: true
value:
accountHolderCode: CODE123
accountHolderDetails: example_value
accountHolderStatus: active
accounts:
- example_value
description: A sample description for this resource.
invalidFields:
- example_value
legalEntity: Business
migrationData: example_value
primaryCurrency: USD
pspReference: REF-001
resultCode: CODE123
systemUpToDateTime: '2025-03-15T14:30:00Z'
verification: example_value
verificationProfile: example_value
description: OK - the request has succeeded.
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/GetAccountHolderResponse'
examples:
post-getAccountHolder202Example:
summary: Default post-getAccountHolder 202 response
x-microcks-default: true
value:
accountHolderCode: CODE123
accountHolderDetails: example_value
accountHolderStatus: active
accounts:
- example_value
description: A sample description for this resource.
invalidFields:
- example_value
legalEntity: Business
migrationData: example_value
primaryCurrency: USD
pspReference: REF-001
resultCode: CODE123
systemUpToDateTime: '2025-03-15T14:30:00Z'
verification: example_value
verificationProfile: example_value
description: Accepted - the request has been accepted for processing, but the processing has not been completed.
'400':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-400'
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-getAccountHolder401Example:
summary: Default post-getAccountHolder 401 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-403'
schema:
$ref: '#/components/schemas/ServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-getAccountHolder422Example:
summary: Default post-getAccountHolder 422 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-getAccountHolder500Example:
summary: Default post-getAccountHolder 500 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
LegalArrangementEntityDetail:
properties:
address:
description: The address of the entity.
$ref: '#/components/schemas/ViasAddress'
businessDetails:
description: Required when creating an entity with `legalEntityType` **Business**, **NonProfit**, **PublicCompany**, or **Partnership**.
$ref: '#/components/schemas/BusinessDetails'
email:
description: The e-mail address of the entity.
type: string
fullPhoneNumber:
description: 'The phone number of the contact provided as a single string. It will be handled as a landline phone.
**Examples:** "0031 6 11 22 33 44", "+316/1122-3344", "(0031) 611223344"'
type: string
individualDetails:
description: Required when creating an entity with `legalEntityType` **Individual**.
$ref: '#/components/schemas/IndividualDetails'
legalArrangementEntityCode:
description: 'Adyen-generated unique alphanumeric identifier (UUID) for the entry, returned in the response when you create a legal arrangement entity.
Use only when updating an account holder. If you include this field when creating an account holder, the request will fail.'
type: string
legalArrangementEntityReference:
description: Your reference for the legal arrangement entity.
type: string
legalArrangementMembers:
description: 'An array containing the roles of the entity in the legal arrangement.
The possible values depend on the legal arrangement `type`.
- For `type` **Association**: **ControllingPerson** and **Shareholder**.
- For `type` **Partnership**: **Partner** and **Shareholder**.
- For `type` **Trust**: **Trustee**, **Settlor**, **Protector**, **Beneficiary**, and **Shareholder**.
'
items:
enum:
- Beneficiary
- ControllingPerson
- Partner
- Protector
- Settlor
- Shareholder
- Trustee
type: string
type: array
legalEntityType:
description: 'The legal entity type.
Possible values: **Business**, **Individual**, **NonProfit**, **PublicCompany**, or **Partnership**. '
enum:
- Business
- Individual
- NonProfit
- Partnership
- PublicCompany
type: string
phoneNumber:
description: The phone number of the entity.
$ref: '#/components/schemas/ViasPhoneNumber'
webAddress:
description: The URL of the website of the contact.
type: string
type: object
AccountPayoutState:
properties:
allowPayout:
description: Indicates whether payouts are allowed. This field is the overarching payout status, and is the aggregate of multiple conditions (e.g., KYC status, disabled flag, etc). If this field is false, no payouts will be permitted for any of the account holder's accounts. If this field is true, payouts will be permitted for any of the account holder's accounts.
type: boolean
disableReason:
description: The reason why payouts (to all of the account holder's accounts) have been disabled (by the platform). If the `disabled` field is true, this field can be used to explain why.
type: string
disabled:
description: Indicates whether payouts have been disabled (by the platform) for all of the account holder's accounts. A platform may enable and disable this field at their discretion. If this field is true, `allowPayout` will be false and no payouts will be permitted for any of the account holder's accounts. If this field is false, `allowPayout` may or may not be enabled, depending on other factors.
type: boolean
notAllowedReason:
x-addedInVersion: '5'
description: The reason why payouts (to all of the account holder's accounts) have been disabled (by Adyen). If payouts have been disabled by Adyen, this field will explain why. If this field is blank, payouts have not been disabled by Adyen.
type: string
payoutLimit:
description: The maximum amount that payouts are limited to. Only applies if payouts are allowed but limited.
$ref: '#/components/schemas/Amount'
tierNumber:
x-addedInVersion: '3'
description: The payout tier that the account holder occupies.
format: int32
type: integer
type: object
StoreDetail:
properties:
address:
description: The address of the physical store where the account holder will process payments from.
$ref: '#/components/schemas/ViasAddress'
fullPhoneNumber:
description: 'The phone number of the store provided as a single string. It will be handled as a landline phone.
Examples: "0031 6 11 22 33 44", "+316/1122-3344", "(0031) 611223344"'
type: string
logo:
x-addedInVersion: '5'
description: Store logo for payment method setup.
type: string
merchantAccount:
description: The merchant account to which the store belongs.
type: string
merchantCategoryCode:
description: The merchant category code (MCC) that classifies the business of the account holder.
type: string
merchantHouseNumber:
x-addedInVersion: '5'
description: Merchant house number for payment method setup.
type: string
phoneNumber:
description: The phone number of the store.
$ref: '#/components/schemas/ViasPhoneNumber'
shopperInteraction:
x-addedInVersion: '5'
description: 'The sales channel. Possible values: **Ecommerce**, **POS**.'
enum:
- Ecommerce
- POS
type: string
splitConfigurationUUID:
x-addedInVersion: '5'
description: The unique reference for the split configuration, returned when you configure splits in your Customer Area. When this is provided, the `virtualAccount` is also required. Adyen uses the configuration and the `virtualAccount` to split funds between accounts in your platform.
type: string
status:
description: 'The status of the store. Possible values: **Pending**, **Active**, **Inactive**, **InactiveWithModifications**, **Closed**.'
enum:
- Active
- Closed
- Inactive
- InactiveWithModifications
- Pending
type: string
store:
description: Adyen-generated unique alphanumeric identifier (UUID) for the store, returned in the response when you create a store. Required when updating an existing store in an `/updateAccountHolder` request.
type: string
storeName:
description: "The name of the account holder's store. This value is shown in shopper statements.\n\n* Length: Between 3 to 22 characters \n\n* The following characters are *not* supported: **:;}{$#@!|<>%^*+=\\\\**"
type: string
storeReference:
description: "Your unique identifier for the store. The Customer Area also uses this value for the store description.\n\n * Length: Between 3 to 128 characters\n\n* The following characters are *not* supported: **:;}{$#@!|<>%^*+=\\\\**"
type: string
virtualAccount:
x-addedInVersion: '5'
description: The account holder's `accountCode` where the split amount will be sent. Required when you provide the `splitConfigurationUUID`.
type: string
webAddress:
x-addedInVersion: '5'
description: URL of the ecommerce store.
type: string
required:
- merchantCategoryCode
- address
- merchantAccount
type: object
MigratedAccounts:
properties:
balanceAccountId:
description: The unique identifier of the account of the migrated account holder in the balance platform.
type: string
virtualAccountCode:
description: The unique identifier of the account of the migrated account holder in the classic integration.
type: string
type: object
KYCLegalArrangementCheckResult:
properties:
checks:
description: A list of the checks and their statuses.
items:
$ref: '#/components/schemas/KYCCheckStatusData'
type: array
legalArrangementCode:
description: The unique ID of the legal arrangement to which the check applies.
type: string
type: object
PersonalDocumentData:
properties:
expirationDate:
description: "The expiry date of the document, \n in ISO-8601 YYYY-MM-DD format. For example, **2000-01-31**."
type: string
issuerCountry:
description: "The country where the document was issued, in the two-character \n[ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. For example, **NL**."
maxLength: 2
minLength: 2
type: string
issuerState:
description: The state where the document was issued (if applicable).
type: string
number:
description: The number in the document.
type: string
type:
description: 'The type of the document. Possible values: **ID**, **DRIVINGLICENSE**, **PASSPORT**, **SOCIALSECURITY**, **VISA**.
To delete an existing entry for a document `type`, send only the `type` field in your request. '
enum:
- DRIVINGLICENSE
- ID
- PASSPORT
- SOCIALSECURITY
- VISA
type: string
required:
- type
type: object
KYCUltimateParentCompanyCheckResult:
properties:
checks:
description: A list of the checks and their statuses.
items:
$ref: '#/components/schemas/KYCCheckStatusData'
type: array
ultimateParentCompanyCode:
x-addedInVersion: '6'
description: The code of the Ultimate Parent Company to which the check applies.
type: string
type: object
Account:
properties:
accountCode:
description: The code of the account.
type: string
bankAccountUUID:
x-addedInVersion: '5'
description: The bankAccountUUID of the bank account held by the account holder to couple the account with. Scheduled payouts in currencies matching the currency of this bank account will be sent to this bank account. Payouts in different currencies will be sent to a matching bank account of the account holder.
type: string
beneficiaryAccount:
description: The beneficiary of the account.
type: string
beneficiaryMerchantReference:
description: The reason that a beneficiary has been set up for this account. This may have been supplied during the setup of a beneficiary at the discretion of the executing user.
type: string
description:
x-addedInVersion: '4'
description: A description of the account.
type: string
metadata:
x-addedInVersion: '5'
additionalProperties:
type: string
description: 'A set of key and value pairs for general use by the merchant.
The keys do not have specific names and may be used for storing miscellaneous data as desired.
> Note that during an update of metadata, the omission of existing key-value pairs will result in the deletion of those key-value pairs.'
type: object
payoutMethodCode:
x-addedInVersion: '5'
description: The payout method code held by the account holder to couple the account with. Scheduled card payouts will be sent using this payout method code.
type: string
payoutSchedule:
description: The account's payout schedule.
$ref: '#/components/schemas/PayoutScheduleResponse'
payoutSpeed:
x-addedInVersion: '5'
description: 'Speed with which payouts for this account are processed. Permitted values: `STANDARD`, `SAME_DAY`.'
enum:
- INSTANT
- SAME_DAY
- STANDARD
type: string
status:
x-addedInVersion: '4'
description: 'The status of the account. Possible values: `Active`, `Inactive`, `Suspended`, `Closed`.'
type: string
type: object
ShareholderContact:
properties:
address:
description: The address of the person.
$ref: '#/components/schemas/ViasAddress'
email:
description: The e-mail address of the person.
type: string
fullPhoneNumber:
description: 'The phone number of the person provided as a single string. It will be handled as a landline phone.
Examples: "0031 6 11 22 33 44", "+316/1122-3344", "(0031) 611223344"'
type: string
jobTitle:
description: 'Job title of the person. Required when the `shareholderType` is **Controller**.
Example values: **Chief Executive Officer**, **Chief Financial Officer**, **Chief Operating Officer**, **President**, **Vice President**, **Executive President**, **Managing Member**, **Partner**, **Treasurer**, **Director**, or **Other**.'
type: string
name:
description: The name of the person.
$ref: '#/components/schemas/ViasName'
personalData:
description: Contains information about the person.
$ref: '#/components/schemas/ViasPersonalData'
phoneNumber:
description: The phone number of the person.
$ref: '#/components/schemas/ViasPhoneNumber'
shareholderCode:
description: 'The unique identifier (UUID) of the shareholder entry.
>**If, during an Account Holder create or update request, this field is left blank (but other fields provided), a new Shareholder will be created with a procedurally-generated UUID.**
>**If, during an Account Holder create request, a UUID is provided, the creation of Account Holder will fail with a validation Error..**
>**If, during an Account Holder update request, a UUID that is not correlated with an existing Shareholder is provided, the update of the Shareholder will fail.**
>**If, during an Account Holder update request, a UUID that is correlated with an existing Shareholder is provided, the existing Shareholder will be updated.**
'
type: string
shareholderReference:
x-addedInVersion: '5'
description: Your reference for the shareholder entry.
type: string
shareholderType:
description: "Specifies how the person is associated with the account holder. \n\nPossible values: \n\n* **Owner**: Individuals who directly or indirectly own 25% or more of a company.\n\n* **Controller**: Individuals who are members of senior management staff responsible for managing a company or organization."
enum:
- Controller
- Owner
- Signatory
type: string
webAddress:
description: The URL of the person's website.
type: string
type: object
KYCVerificationResult:
properties:
accountHolder:
description: The results of the checks on the account holder.
$ref: '#/components/schemas/KYCCheckResult'
legalArrangements:
x-addedInVersion: '6'
description: The results of the checks on the legal arrangements.
items:
$ref: '#/components/schemas/KYCLegalArrangementCheckResult'
type: array
legalArrangementsEntities:
x-addedInVersion: '6'
description: The results of the checks on the legal arrangement entities.
items:
$ref: '#/components/schemas/KYCLegalArrangementEntityCheckResult'
type: array
payoutMethods:
x-addedInVersion: '6'
description: The results of the checks on the payout methods.
items:
$ref: '#/components/schemas/KYCPayoutMethodCheckResult'
type: array
shareholders:
description: The results of the checks on the shareholders.
items:
$ref: '#/components/schemas/KYCShareholderCheckResult'
type: array
signatories:
description: The results of the checks on the signatories.
items:
$ref: '#/components/schemas/KYCSignatoryCheckResult'
type: array
ultimateParentCompany:
x-addedInVersion: '6'
description: The result of the check on the Ultimate Parent Company.
items:
$ref: '#/components/schemas/KYCUltimateParentCompanyCheckResult'
type: array
type: object
ViasPhoneNumber:
properties:
phoneCountryCode:
description: 'The two-character country code of the phone number.
>The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. ''NL'').'
type: string
phoneNumber:
description: 'The phone number.
>The inclusion of the phone number country code is not necessary.'
type: string
phoneType:
description: 'The type of the phone number.
>The following values are permitted: `Landline`, `Mobile`, `SIP`, `Fax`.'
enum:
- Fax
- Landline
- Mobile
- SIP
type: string
type: object
MigratedShareholders:
properties:
legalEntityCode:
description: The unique identifier of the legal entity of that shareholder in the balance platform.
type: string
shareholderCode:
description: The unique identifier of the account of the migrated shareholder in the classic integration.
type: string
type: object
ErrorFieldType:
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
UltimateParentCompany:
properties:
address:
description: Address of the ultimate parent company.
$ref: '#/components/schemas/ViasAddress'
businessDetails:
description: Details about the ultimate parent company's business.
$ref: '#/components/schemas/UltimateParentCompanyBusinessDetails'
ultimateParentCompanyCode:
description: Adyen-generated unique alphanumeric identifier (UUID) for the entry, returned in the response when you create an ultimate parent company. Required when updating an existing entry in an `/updateAccountHolder` request.
type: string
type: object
PayoutMethod:
properties:
merchantAccount:
description: The [`merchantAccount`](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments__reqParam_merchantAccount) you used in the `/payments` request when you [saved the account holder's card details](https://docs.adyen.com/marketplaces-and-platforms/classic/payouts/manual-payout/payout-to-cards#check-and-store).
type: string
payoutMethodCode:
description: Adyen-generated unique alphanumeric identifier (UUID) for the payout method, returned in the response when you create a payout method. Required when updating an existing payout method in an `/updateAccountHolder` request.
type: string
payoutMethodReference:
description: Your reference for the payout method.
type: string
recurringDetailReference:
description: The [`recurringDetailReference`](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments__resParam_additionalData-ResponseAdditionalDataCommon-recurring-recurringDetailReference) returned in the `/payments` response when you [saved the account holder's card details](https://docs.adyen.com/marketplaces-and-platforms/classic/payouts/manual-payout/payout-to-cards#check-and-store).
type: string
shopperReference:
description: The [`shopperReference`](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments__reqParam_shopperReference) you sent in the `/payments` request when you [saved the account holder's card details](https://docs.adyen.com/marketplaces-and-platforms/classic/payouts/manual-payout/payout-to-cards#check-and-store).
type: string
required:
- merchantAccount
- shopperReference
- recurringDetailReference
type: object
MigrationData:
properties:
accountHolderId:
description: The unique identifier of the account holder in the balance platform.
type: string
balancePlatform:
description: The unique identifier of the balance platfrom to which the account holder was migrated.
type: string
migrated:
description: Set to **true** if the account holder has been migrated.
type: boolean
migratedAccounts:
description: Contains the mapping of virtual account codes (classic integration) to the balance account codes (balance platform) associated with the migrated account holder.
items:
$ref: '#/components/schemas/MigratedAccounts'
type: array
migratedShareholders:
description: Contains the mapping of shareholders associated with the migrated legal entities.
items:
$ref: '#/components/schemas/MigratedShareholders'
type: array
migratedStores:
description: Contains the mapping of business lines and stores associated with the migrated account holder.
items:
$ref: '#/components/schemas/MigratedStores'
type: array
migrationDate:
description: The date when account holder was migrated.
format: date-time
type: string
type: object
BankAccountDetail:
properties:
accountNumber:
description: 'The bank account number (without separators).
>Refer to [Required information](https://docs.adyen.com/marketplaces-and-platforms/classic/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/marketplaces-and-platforms/classic/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/marketplaces-and-platforms/classic/verification-process/required-information) for details on field requirements.'
type: string
bankCity:
description: 'The city in whic
# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adyen/refs/heads/main/openapi/adyen-getaccountholder-api-openapi.yml