Adyen Account API

openapi: 3.1.0
info:
  version: '6'
  x-publicVersion: true
  title: Adyen acceptDispute Account 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: Account
paths:
  /createAccount:
    post:
      tags:
      - Account
      summary: Adyen Create an Account
      description: Creates an account under an account holder. An account holder can have [multiple accounts](https://docs.adyen.com/marketplaces-and-platforms/classic/account-holders-and-accounts#create-additional-accounts).
      operationId: post-createAccount
      x-groupName: Accounts
      x-sortIndex: 1
      x-methodName: createAccount
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              basic:
                $ref: '#/components/examples/post-createAccount-basic'
            schema:
              $ref: '#/components/schemas/CreateAccountRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAccountResponse'
              examples:
                post-createAccount200Example:
                  summary: Default post-createAccount 200 response
                  x-microcks-default: true
                  value:
                    accountCode: CODE123
                    accountHolderCode: CODE123
                    bankAccountUUID: '500123'
                    description: A sample description for this resource.
                    invalidFields:
                    - example_value
                    metadata: {}
                    payoutMethodCode: CODE123
                    payoutSchedule: example_value
                    payoutSpeed: INSTANT
                    pspReference: REF-001
                    resultCode: CODE123
                    status: Active
          description: OK - the request has succeeded.
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAccountResponse'
              examples:
                post-createAccount202Example:
                  summary: Default post-createAccount 202 response
                  x-microcks-default: true
                  value:
                    accountCode: CODE123
                    accountHolderCode: CODE123
                    bankAccountUUID: '500123'
                    description: A sample description for this resource.
                    invalidFields:
                    - example_value
                    metadata: {}
                    payoutMethodCode: CODE123
                    payoutSchedule: example_value
                    payoutSpeed: INSTANT
                    pspReference: REF-001
                    resultCode: CODE123
                    status: Active
          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-createAccount401Example:
                  summary: Default post-createAccount 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-createAccount422Example:
                  summary: Default post-createAccount 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-createAccount500Example:
                  summary: Default post-createAccount 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
  /createAccountHolder:
    post:
      tags:
      - Account
      summary: Adyen Create an Account Holder
      description: Creates an account holder that [represents the sub-merchant's entity](https://docs.adyen.com/marketplaces-and-platforms/classic/account-structure#your-platform) in your platform. The details that you need to provide in the request depend on the sub-merchant's legal entity type. For more information, refer to [Account holder and accounts](https://docs.adyen.com/marketplaces-and-platforms/classic/account-holders-and-accounts#legal-entity-types).
      operationId: post-createAccountHolder
      x-groupName: Account holders
      x-sortIndex: 1
      x-methodName: createAccountHolder
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              business:
                $ref: '#/components/examples/post-createAccountHolder-business'
              individual:
                $ref: '#/components/examples/post-createAccountHolder-individual'
            schema:
              $ref: '#/components/schemas/CreateAccountHolderRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAccountHolderResponse'
              examples:
                post-createAccountHolder200Example:
                  summary: Default post-createAccountHolder 200 response
                  x-microcks-default: true
                  value:
                    accountCode: CODE123
                    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.
        '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-createAccountHolder401Example:
                  summary: Default post-createAccountHolder 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-createAccountHolder422Example:
                  summary: Default post-createAccountHolder 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-createAccountHolder500Example:
                  summary: Default post-createAccountHolder 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
  /getAccountHolder:
    post:
      tags:
      - Account
      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
  /updateAccount:
    post:
      tags:
      - Account
      summary: Adyen Update an Account
      description: Updates the description or payout schedule of an account.
      operationId: post-updateAccount
      x-groupName: Accounts
      x-sortIndex: 2
      x-methodName: updateAccount
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              basic:
                $ref: '#/components/examples/post-updateAccount-basic'
            schema:
              $ref: '#/components/schemas/UpdateAccountRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateAccountResponse'
              examples:
                post-updateAccount200Example:
                  summary: Default post-updateAccount 200 response
                  x-microcks-default: true
                  value:
                    accountCode: CODE123
                    bankAccountUUID: '500123'
                    description: A sample description for this resource.
                    invalidFields:
                    - example_value
                    metadata: {}
                    payoutMethodCode: CODE123
                    payoutSchedule: example_value
                    payoutSpeed: INSTANT
                    pspReference: REF-001
                    resultCode: CODE123
          description: OK - the request has succeeded.
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateAccountResponse'
              examples:
                post-updateAccount202Example:
                  summary: Default post-updateAccount 202 response
                  x-microcks-default: true
                  value:
                    accountCode: CODE123
                    bankAccountUUID: '500123'
                    description: A sample description for this resource.
                    invalidFields:
                    - example_value
                    metadata: {}
                    payoutMethodCode: CODE123
                    payoutSchedule: example_value
                    payoutSpeed: INSTANT
                    pspReference: REF-001
                    resultCode: CODE123
          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-updateAccount401Example:
                  summary: Default post-updateAccount 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-updateAccount422Example:
                  summary: Default post-updateAccount 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-updateAccount500Example:
                  summary: Default post-updateAccount 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
  /updateAccountHolder:
    post:
      tags:
      - Account
      summary: Adyen Update an Account Holder
      description: "Updates the `accountHolderDetails` and `processingTier` of an account holder, and adds bank accounts and shareholders.\n\nWhen updating `accountHolderDetails`, parameters that are not included in the request are left unchanged except for the following object:\n\n* `metadata`: Updating the metadata replaces the entire object. This means that to update an existing key-value pair, you must provide the changes, as well as other existing key-value pairs.\n\nWhen updating any field in the following objects, you must submit all the fields required for validation:\n\n * `address`\n\n* `fullPhoneNumber`\n\n* `bankAccountDetails.BankAccountDetail`\n\n* `businessDetails.shareholders.ShareholderContact`\n\n For example, to update the `address.postalCode`, you must also submit the `address.country`, `.city`, `.street`, `.postalCode`, and possibly `.stateOrProvince` so that the address can be validated.\n\nTo add a bank account or shareholder, provide the bank account or shareholder details without a `bankAccountUUID` or a `shareholderCode`.\n\n"
      operationId: post-updateAccountHolder
      x-groupName: Account holders
      x-sortIndex: 3
      x-methodName: updateAccountHolder
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              addShareholders:
                $ref: '#/components/examples/post-updateAccountHolder-addShareholders'
              bankAccountDetails:
                $ref: '#/components/examples/post-updateAccountHolder-bankAccountDetails'
              businessDetails:
                $ref: '#/components/examples/post-updateAccountHolder-businessDetails'
              general:
                $ref: '#/components/examples/post-updateAccountHolder-general'
            schema:
              $ref: '#/components/schemas/UpdateAccountHolderRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateAccountHolderResponse'
              examples:
                post-updateAccountHolder200Example:
                  summary: Default post-updateAccountHolder 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-updateAccountHolder202Example:
                  summary: Default post-updateAccountHolder 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-updateAccountHolder401Example:
                  summary: Default post-updateAccountHolder 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-updateAccountHolder422Example:
                  summary: Default post-updateAccountHolder 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-updateAccountHolder500Example:
                  summary: Default post-updateAccountHolder 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
  /updateAccountHolderState:
    post:
      tags:
      - Account
      summary: Adyen Update Payout or Processing State
      description: Disables or enables the processing or payout state of an account holder.
      operationId: post-updateAccountHolderState
      x-groupName: Account holders
      x-sortIndex: 4
      x-methodName: updateAccountHolderState
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              basic:
                $ref: '#/components/examples/post-updateAccountHolderState-basic'
            schema:
              $ref: '#/components/schemas/UpdateAccountHolderStateRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAccountHolderStatusResponse'
              examples:
                post-updateAccountHolderState200Example:
                  summary: Default post-updateAccountHolderState 200 response
                  x-microcks-default: true
                  value:
                    accountHolderCode: CODE123
                    accountHolderStatus: active
                    invalidFields:
                    - example_value
                    pspReference: REF-001
                    resultCode: CODE123
          description: OK - the request has succeeded.
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAccountHolderStatusResponse'
              examples:
                post-updateAccountHolderState202Example:
                  summary: Default post-updateAccountHolderState 202 response
                  x-microcks-default: true
                  value:
                    accountHolderCode: CODE123
                    accountHolderStatus: active
                    invalidFields:
                    - example_value
                    pspReference: REF-001
                    resultCode: CODE123
          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-updateAccountHolderState401Example:
                  summary: Default pos

# --- truncated at 32 KB (155 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adyen/refs/heads/main/openapi/adyen-account-api-openapi.yml