openapi: 3.1.0
info:
version: '6'
x-publicVersion: true
title: Adyen Account acceptDispute uploadDocument 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: uploadDocument
paths:
/uploadDocument:
post:
tags:
- uploadDocument
summary: Adyen Upload a Document
description: Uploads a document for an account holder. Adyen uses the documents during the [verification process](https://docs.adyen.com/marketplaces-and-platforms/classic/verification-process).
operationId: post-uploadDocument
x-groupName: Verification
x-sortIndex: 1
x-methodName: uploadDocument
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
basic:
$ref: '#/components/examples/post-uploadDocument-basic'
schema:
$ref: '#/components/schemas/UploadDocumentRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAccountHolderResponse'
examples:
post-uploadDocument200Example:
summary: Default post-uploadDocument 200 response
x-microcks-default: true
value:
accountHolderCode: CODE123
accountHolderDetails: example_value
accountHolderStatus: active
description: A sample description for this resource.
invalidFields:
- example_value
legalEntity: Business
primaryCurrency: USD
pspReference: REF-001
resultCode: CODE123
verification: example_value
verificationProfile: example_value
description: OK - the request has succeeded.
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAccountHolderResponse'
examples:
post-uploadDocument202Example:
summary: Default post-uploadDocument 202 response
x-microcks-default: true
value:
accountHolderCode: CODE123
accountHolderDetails: example_value
accountHolderStatus: active
description: A sample description for this resource.
invalidFields:
- example_value
legalEntity: Business
primaryCurrency: USD
pspReference: REF-001
resultCode: CODE123
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-uploadDocument401Example:
summary: Default post-uploadDocument 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-uploadDocument422Example:
summary: Default post-uploadDocument 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-uploadDocument500Example:
summary: Default post-uploadDocument 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
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
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
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
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
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
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 which the bank branch is located.
>Refer to [Required information](https://docs.adyen.com/marketplaces-and-platforms/classic/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/marketplaces-and-platforms/classic/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/marketplaces-and-platforms/classic/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/marketplaces-and-platforms/classic/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/marketplaces-and-platforms/classic/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/marketplaces-and-platforms/classic/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/marketplaces-and-platforms/classic/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/marketplaces-and-platforms/classic/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/marketplaces-and-platforms/classic/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/marketplaces-and-platforms/classic/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/marketplaces-and-platforms/classic/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/marketplaces-and-platforms/classic/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/marketplaces-and-platforms/classic/verification-process/required-informatio
# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adyen/refs/heads/main/openapi/adyen-uploaddocument-api-openapi.yml