openapi: 3.1.0
info:
version: '6'
x-publicVersion: true
title: Adyen Account acceptDispute accountHolders 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: accountHolders
paths:
/accountHolders:
post:
tags:
- accountHolders
summary: Adyen Create an Account Holder
description: 'Creates an account holder linked to a [legal entity](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/legalEntities).
'
x-addedInVersion: '1'
operationId: post-accountHolders
x-sortIndex: 1
x-methodName: createAccountHolder
security:
- clientKey: []
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
createAccountHolder:
$ref: '#/components/examples/post-accountHolders-createAccountHolder'
schema:
$ref: '#/components/schemas/AccountHolderInfo'
responses:
'200':
content:
application/json:
examples:
createAccountHolder:
$ref: '#/components/examples/post-accountHolders-createAccountHolder-200'
schema:
$ref: '#/components/schemas/AccountHolder'
description: OK - the request has succeeded.
'400':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-400'
schema:
$ref: '#/components/schemas/RestServiceError'
description: Bad Request - a problem reading or understanding the request.
'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
/accountHolders/{id}:
get:
tags:
- accountHolders
summary: Adyen Get an Account Holder
description: Returns an account holder.
x-addedInVersion: '1'
operationId: get-accountHolders-id
x-sortIndex: 3
x-methodName: getAccountHolder
security:
- clientKey: []
- BasicAuth: []
- ApiKeyAuth: []
parameters:
- description: The unique identifier of the account holder.
name: id
in: path
required: true
schema:
type: string
responses:
'200':
content:
application/json:
examples:
success:
$ref: '#/components/examples/get-accountHolders-id-success-200'
schema:
$ref: '#/components/schemas/AccountHolder'
description: OK - the request has succeeded.
'400':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-400'
schema:
$ref: '#/components/schemas/RestServiceError'
description: Bad Request - a problem reading or understanding the request.
'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
patch:
tags:
- accountHolders
summary: Adyen Update an Account Holder
description: Updates an account holder. When updating an account holder resource, if a parameter is not provided in the request, it is left unchanged.
x-addedInVersion: '1'
operationId: patch-accountHolders-id
x-sortIndex: 2
x-methodName: updateAccountHolder
security:
- clientKey: []
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
requestAccountHolderCapability:
$ref: '#/components/examples/patch-accountHolders-id-requestAccountHolderCapability'
updateAccountHolderStatus:
$ref: '#/components/examples/patch-accountHolders-id-updateAccountHolderStatus'
schema:
$ref: '#/components/schemas/AccountHolderUpdateRequest'
parameters:
- description: The unique identifier of the account holder.
name: id
in: path
required: true
schema:
type: string
responses:
'200':
content:
application/json:
examples:
requestAccountHolderCapability:
$ref: '#/components/examples/patch-accountHolders-id-requestAccountHolderCapability-200'
updateAccountHolderStatus:
$ref: '#/components/examples/patch-accountHolders-id-updateAccountHolderStatus-200'
schema:
$ref: '#/components/schemas/AccountHolder'
description: OK - the request has succeeded.
'400':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-400'
schema:
$ref: '#/components/schemas/RestServiceError'
description: Bad Request - a problem reading or understanding the request.
'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
/accountHolders/{id}/balanceAccounts:
get:
tags:
- accountHolders
summary: Adyen Get All Balance Accounts of an Account Holder
description: "Returns a paginated list of the balance accounts associated with an account holder. To fetch multiple pages, use the query parameters. \n\nFor example, to limit the page to 5 balance accounts and skip the first 10, use `/accountHolders/{id}/balanceAccounts?limit=5&offset=10`."
x-addedInVersion: '1'
operationId: get-accountHolders-id-balanceAccounts
x-sortIndex: 4
x-methodName: getAllBalanceAccountsOfAccountHolder
security:
- clientKey: []
- BasicAuth: []
- ApiKeyAuth: []
parameters:
- description: The unique identifier of the account holder.
name: id
in: path
required: true
schema:
type: string
- description: The number of items that you want to skip.
name: offset
in: query
required: false
schema:
format: int32
type: integer
- description: The number of items returned per page, maximum 100 items. By default, the response returns 10 items per page.
name: limit
in: query
required: false
schema:
format: int32
type: integer
responses:
'200':
content:
application/json:
examples:
success:
$ref: '#/components/examples/get-accountHolders-id-balanceAccounts-success-200'
schema:
$ref: '#/components/schemas/PaginatedBalanceAccountsResponse'
description: OK - the request has succeeded.
'400':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-400'
schema:
$ref: '#/components/schemas/RestServiceError'
description: Bad Request - a problem reading or understanding the request.
'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
/accountHolders/{id}/taxForms:
get:
tags:
- accountHolders
summary: Adyen Get a Tax Form
description: Generates a tax form for account holders operating in the US. For more information, refer to [Providing tax forms](https://docs.adyen.com/marketplaces-and-platforms/us-tax-forms/).
x-addedInVersion: '2'
operationId: get-accountHolders-id-taxForms
x-sortIndex: 5
x-methodName: getTaxForm
security:
- clientKey: []
- BasicAuth: []
- ApiKeyAuth: []
parameters:
- description: The unique identifier of the account holder.
name: id
in: path
required: true
schema:
type: string
- description: The type of tax form you want to retrieve. Accepted values are **US1099k** and **US1099nec**
name: formType
in: query
required: true
schema:
x-enum:
- value: US1099k
- value: US1099nec
enum:
- US1099k
- US1099nec
type: string
- description: The tax year in YYYY format for the tax form you want to retrieve
name: year
in: query
required: true
schema:
format: int32
type: integer
responses:
'200':
content:
application/json:
examples:
success:
$ref: '#/components/examples/get-accountHolders-id-taxForms-success-200'
schema:
$ref: '#/components/schemas/GetTaxFormResponse'
description: OK - the request has succeeded.
'400':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-400'
schema:
$ref: '#/components/schemas/RestServiceError'
description: Bad Request - a problem reading or understanding the request.
'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
components:
schemas:
AccountSupportingEntityCapability:
properties:
allowed:
description: Indicates whether the supporting entity capability is allowed. Adyen sets this to **true** if the verification is successful and the account holder is permitted to use the capability.
readOnly: true
type: boolean
allowedLevel:
description: 'The capability level that is allowed for the account holder.
Possible values: **notApplicable**, **low**, **medium**, **high**.'
enum:
- high
- low
- medium
- notApplicable
readOnly: true
type: string
enabled:
description: Indicates whether the capability is enabled. If **false**, the capability is temporarily disabled for the account holder.
type: boolean
id:
description: The ID of the supporting entity.
readOnly: true
type: string
requested:
description: Indicates whether the capability is requested. To check whether the account holder is permitted to use the capability, refer to the `allowed` field.
type: boolean
requestedLevel:
description: 'The requested level of the capability. Some capabilities, such as those used in [card issuing](https://docs.adyen.com/issuing/add-capabilities#capability-levels), have different levels. Levels increase the capability, but also require additional checks and increased monitoring.
Possible values: **notApplicable**, **low**, **medium**, **high**.'
enum:
- high
- low
- medium
- notApplicable
type: string
verificationStatus:
description: 'The status of the verification checks for the supporting entity capability.
Possible values:
* **pending**: Adyen is running the verification.
* **invalid**: The verification failed. Check if the `errors` array contains more information.
* **valid**: The verification has been successfully completed.
* **rejected**: Adyen has verified the information, but found reasons to not allow the capability.
'
enum:
- invalid
- pending
- rejected
- valid
readOnly: true
type: string
type: object
GetTaxFormResponse:
properties:
content:
description: The content of the tax form in Base64 format.
format: byte
type: string
contentType:
description: 'The content type of the tax form.
Possible values:
* **application/pdf**
'
enum:
- application/pdf
type: string
required:
- content
type: object
Phone:
properties:
number:
description: "The full phone number provided as a single string. \nFor example, **\"0031 6 11 22 33 44\"**, **\"+316/1122-3344\"**, \n\n or **\"(0031) 611223344\"**."
type: string
type:
description: "Type of phone number.\nPossible values: \n**Landline**, **Mobile**.\n"
enum:
- landline
- mobile
type: string
required:
- number
- type
type: object
AccountHolder:
properties:
balancePlatform:
description: The unique identifier of the [balance platform](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/balancePlatforms/{id}__queryParam_id) to which the account holder belongs. Required in the request if your API credentials can be used for multiple balance platforms.
type: string
capabilities:
additionalProperties:
$ref: '#/components/schemas/AccountHolderCapability'
description: Contains key-value pairs that specify the actions that an account holder can do in your platform. The key is a capability required for your integration. For example, **issueCard** for Issuing. The value is an object containing the settings for the capability.
type: object
contactDetails:
deprecated: true
description: Contact details of the account holder.
$ref: '#/components/schemas/ContactDetails'
description:
description: Your description for the account holder, maximum 300 characters.
maxLength: 300
type: string
id:
description: The unique identifier of the account holder.
readOnly: true
type: string
legalEntityId:
description: The unique identifier of the [legal entity](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id) associated with the account holder. Adyen performs a verification process against the legal entity of the account holder.
type: string
metadata:
additionalProperties:
type: string
description: 'A set of key and value pairs for general use.
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
migratedAccountHolderCode:
description: The unique identifier of the migrated account holder in the classic integration.
readOnly: true
type: string
primaryBalanceAccount:
description: The ID of the account holder's primary balance account. By default, this is set to the first balance account that you create for the account holder. To assign a different balance account, send a PATCH request.
type: string
reference:
description: Your reference for the account holder, maximum 150 characters.
maxLength: 150
type: string
status:
description: "The status of the account holder.\n\nPossible values: \n\n * **active**: The account holder is active. This is the default status when creating an account holder. \n\n * **inactive (Deprecated)**: The account holder is temporarily inactive due to missing KYC details. You can set the account back to active by providing the missing KYC details. \n\n * **suspended**: The account holder is permanently deactivated by Adyen. This action cannot be undone. \n\n* **closed**: The account holder is permanently deactivated by you. This action cannot be undone."
enum:
- active
- closed
- inactive
- suspended
type: string
timeZone:
description: 'The time zone of the account holder. For example, **Europe/Amsterdam**.
Defaults to the time zone of the balance platform if no time zone is set. For possible values, see the [list of time zone codes](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).'
type: string
verificationDeadlines:
description: List of verification deadlines and the capabilities that will be disallowed if verification errors are not resolved.
items:
$ref: '#/components/schemas/VerificationDeadline'
readOnly: true
type: array
required:
- legalEntityId
- id
type: object
VerificationDeadline:
properties:
capabilities:
description: The names of the capabilities to be disallowed.
items:
enum:
- acceptExternalFunding
- acceptPspFunding
- acceptTransactionInRestrictedCountries
- acceptTransactionInRestrictedCountriesCommercial
- acceptTransactionInRestrictedCountriesConsumer
- acceptTransactionInRestrictedIndustries
- acceptTransactionInRestrictedIndustriesCommercial
- acceptTransactionInRestrictedIndustriesConsumer
- acquiring
- atmWithdrawal
- atmWithdrawalCommercial
- atmWithdrawalConsumer
- atmWithdrawalInRestrictedCountries
- atmWithdrawalInRestrictedCountriesCommercial
- atmWithdrawalInRestrictedCountriesConsumer
- authorisedPaymentInstrumentUser
- getGrantOffers
- issueBankAccount
- issueCard
- issueCardCommercial
- issueCardConsumer
- localAcceptance
- payout
- payoutToTransferInstrument
- processing
- receiveFromBalanceAccount
- receiveFromPlatformPayments
- receiveFromThirdParty
- receiveFromTransferInstrument
- receiveGrants
- receivePayments
- sendToBalanceAccount
- sendToThirdParty
- sendToTransferInstrument
- thirdPartyFunding
- useCard
- useCardCommercial
- useCardConsumer
- useCardInRestrictedCountries
- useCardInRestrictedCountriesCommercial
- useCardInRestrictedCountriesConsumer
- useCardInRestrictedIndustries
- useCardInRestrictedIndustriesCommercial
- useCardInRestrictedIndustriesConsumer
- withdrawFromAtm
- withdrawFromAtmCommercial
- withdrawFromAtmConsumer
- withdrawFromAtmInRestrictedCountries
- withdrawFromAtmInRestrictedCountriesCommercial
- withdrawFromAtmInRestrictedCountriesConsumer
type: string
readOnly: true
type: array
entityIds:
description: The unique identifiers of the bank account(s) that the deadline applies to
items:
type: string
readOnly: true
type: array
expiresAt:
description: The date that verification is due by before capabilities are disallowed.
format: date-time
readOnly: true
type: string
required:
- expiresAt
- capabilities
type: object
JSONObject:
type: object
PaginatedBalanceAccountsResponse:
properties:
balanceAccounts:
description: List of balance accounts.
items:
$ref: '#/components/schemas/BalanceAccountBase'
type: array
hasNext:
description: Indicates whether there are more items on the next page.
type: boolean
hasPrevious:
description: Indicates whether there are more items on the previous page.
type: boolean
required:
- balanceAccounts
- hasPrevious
- hasNext
type: object
CapabilitySettings:
properties:
amountPerIndustry:
additionalProperties:
$ref: '#/components/schemas/Amount'
description: ''
type: object
authorizedCardUsers:
description: ''
type: boolean
fundingSource:
description: ''
items:
enum:
- credit
- debit
- prepaid
type: string
type: array
interval:
description: ''
enum:
- daily
- monthly
- weekly
type: string
maxAmount:
description: ''
$ref: '#/components/schemas/Amount'
type: object
ContactDetails:
properties:
address:
description: The address of the account holder.
$ref: '#/components/schemas/Address'
email:
description: The email address of the account holder.
type: string
phone:
description: The phone number of the account holder.
$ref: '#/components/schemas/Phone'
webAddress:
description: The URL of the account holder's website.
type: string
required:
- email
- phone
- address
type: object
CapabilityProblemEntity-recursive:
properties:
documents:
description: List of document IDs to which the verification errors related to the capabilities correspond to.
items:
type: string
type: array
id:
description: The ID of the entity.
type: string
type:
description: "Type of entity. \n\nPossible values: **LegalEntity**, **BankAccount**, **Document**."
enum:
- BankAccount
- Document
- LegalEntity
type: string
required: []
type: object
RestServiceError:
properties:
detail:
description: A human-readable explanation specific to this occurrence of the problem.
type: string
errorCode:
description: A code that identifies the problem type.
type: string
instance:
description: A unique URI that identifies the specific occurrence of the problem.
type: string
invalidFields:
description: Detailed explanation of each validation error, when applicable.
items:
$ref: '#/components/schemas/InvalidField'
type: array
requestId:
description: A unique reference for the request, essentially the same as `pspReference`.
type: string
response:
description: JSON response payload.
$ref: '#/components/schemas/JSONObject'
status:
description: The HTTP status code.
format: int32
type: integer
title:
description: A short, human-readable summary of the problem type.
type: string
type:
description: A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
type: string
required:
- type
- errorCode
- title
- detail
- status
type: object
AccountHolderInfo:
properties:
balancePlatform:
description: The unique identifier of the [balance platform](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/balancePlatforms/{id}__queryParam_id) to which the account holder belongs. Required in the request if your API credentials can be used for multiple balance platforms.
type: string
capabilities:
additionalProperties:
$ref: '#/components/schemas/AccountHolderCapability'
description: Contains key-value pairs that specify the actions that an account holder can do in your platform. The key is a capability required for your integration. For example, **issueCard** for Issuing. The value is an object containing the settings for the capability.
# --- truncated at 32 KB (61 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adyen/refs/heads/main/openapi/adyen-accountholders-api-openapi.yml