Adyen Holders API

openapi: 3.1.0
info:
  version: '6'
  x-publicVersion: true
  title: Adyen Account acceptDispute Holders 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: Holders
paths:
  /checkAccountHolder:
    post:
      tags:
      - Holders
      summary: Adyen Trigger Verification
      description: Triggers the verification of an account holder even if the checks are not yet required for the volume that they are currently processing.
      x-addedInVersion: '5'
      operationId: post-checkAccountHolder
      x-groupName: Verification
      x-sortIndex: 3
      x-methodName: checkAccountHolder
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              basic:
                $ref: '#/components/examples/post-checkAccountHolder-basic'
            schema:
              $ref: '#/components/schemas/PerformVerificationRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
              examples:
                post-checkAccountHolder200Example:
                  summary: Default post-checkAccountHolder 200 response
                  x-microcks-default: true
                  value:
                    invalidFields:
                    - example_value
                    pspReference: REF-001
                    resultCode: CODE123
          description: OK - the request has succeeded.
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
              examples:
                post-checkAccountHolder202Example:
                  summary: Default post-checkAccountHolder 202 response
                  x-microcks-default: true
                  value:
                    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-checkAccountHolder401Example:
                  summary: Default post-checkAccountHolder 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-checkAccountHolder422Example:
                  summary: Default post-checkAccountHolder 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-checkAccountHolder500Example:
                  summary: Default post-checkAccountHolder 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
  /closeAccountHolder:
    post:
      tags:
      - Holders
      summary: Adyen Close an Account Holder
      description: Changes the [status of an account holder](https://docs.adyen.com/marketplaces-and-platforms/classic/account-holders-and-accounts#account-holder-statuses) to **Closed**. This state is final. If an account holder is closed, you can't process transactions, pay out funds, or reopen it. If payments are made to an account of an account holder with a **Closed** [`status`](https://docs.adyen.com/api-explorer/#/Account/latest/post/getAccountHolder__resParam_verification-accountHolder-checks-status), the payments are sent to your liable account.
      operationId: post-closeAccountHolder
      x-groupName: Account holders
      x-sortIndex: 7
      x-methodName: closeAccountHolder
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              basic:
                $ref: '#/components/examples/post-closeAccountHolder-basic'
            schema:
              $ref: '#/components/schemas/CloseAccountHolderRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloseAccountHolderResponse'
              examples:
                post-closeAccountHolder200Example:
                  summary: Default post-closeAccountHolder 200 response
                  x-microcks-default: true
                  value:
                    accountHolderStatus: active
                    invalidFields:
                    - example_value
                    pspReference: REF-001
                    resultCode: CODE123
          description: OK - the request has succeeded.
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloseAccountHolderResponse'
              examples:
                post-closeAccountHolder202Example:
                  summary: Default post-closeAccountHolder 202 response
                  x-microcks-default: true
                  value:
                    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-closeAccountHolder401Example:
                  summary: Default post-closeAccountHolder 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-closeAccountHolder422Example:
                  summary: Default post-closeAccountHolder 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-closeAccountHolder500Example:
                  summary: Default post-closeAccountHolder 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:
      - Holders
      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:
      - Holders
      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
  /suspendAccountHolder:
    post:
      tags:
      - Holders
      summary: Adyen Suspend an Account Holder
      description: Changes the [status of an account holder](https://docs.adyen.com/marketplaces-and-platforms/classic/account-holders-and-accounts#account-holder-statuses) to **Suspended**.
      operationId: post-suspendAccountHolder
      x-groupName: Account holders
      x-sortIndex: 5
      x-methodName: suspendAccountHolder
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              basic:
                $ref: '#/components/examples/post-suspendAccountHolder-basic'
            schema:
              $ref: '#/components/schemas/SuspendAccountHolderRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuspendAccountHolderResponse'
              examples:
                post-suspendAccountHolder200Example:
                  summary: Default post-suspendAccountHolder 200 response
                  x-microcks-default: true
                  value:
                    accountHolderStatus: active
                    invalidFields:
                    - example_value
                    pspReference: REF-001
                    resultCode: CODE123
          description: OK - the request has succeeded.
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuspendAccountHolderResponse'
              examples:
                post-suspendAccountHolder202Example:
                  summary: Default post-suspendAccountHolder 202 response
                  x-microcks-default: true
                  value:
                    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-suspendAccountHolder401Example:
                  summary: Default post-suspendAccountHolder 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-suspendAccountHolder422Example:
                  summary: Default post-suspendAccountHolder 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-suspendAccountHolder500Example:
                  summary: Default post-suspendAccountHolder 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
  /unSuspendAccountHolder:
    post:
      tags:
      - Holders
      summary: Adyen Unsuspend an Account Holder
      description: "Changes the [status of an account holder](https://docs.adyen.com/marketplaces-and-platforms/classic/account-holders-and-accounts#account-holder-statuses) from **Suspended** to **Inactive**. \nAccount holders can have a **Suspended** [`status`](https://docs.adyen.com/api-explorer/#/Account/latest/post/getAccountHolder__resParam_verification-accountHolder-checks-status) if you suspend them through the [`/suspendAccountHolder`](https://docs.adyen.com/api-explorer/#/Account/v5/post/suspendAccountHolder) endpoint or if a verification deadline expires.\n\nYou can only unsuspend account holders if they do not have verification checks with a **FAILED** [`status`](https://docs.adyen.com/api-explorer/#/Account/latest/post/getAccountHolder__resParam_verification-accountHolder-checks-status)."
      operationId: post-unSuspendAccountHolder
      x-groupName: Account holders
      x-sortIndex: 6
      x-methodName: unSuspendAccountHolder
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              basic:
                $ref: '#/components/examples/post-unSuspendAccountHolder-basic'
            schema:
              $ref: '#/components/schemas/UnSuspendAccountHolderRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnSuspendAccountHolderResponse'
              examples:
                post-unSuspendAccountHolder200Example:
                  summary: Default post-unSuspendAccountHolder 200 response
                  x-microcks-default: true
                  value:
                    accountHolderStatus: active
                    invalidFields:
                    - example_value
                    pspReference: REF-001
                    resultCode: CODE123
          description: OK - the request has succeeded.
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnSuspendAccountHolderResponse'
              examples:
                post-unSuspendAccountHolder202Example:
                  summary: Default post-unSuspendAccountHolder 202 response
                  x-microcks-default: true
                  value:
                    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-unSuspendAccountHolder401Example:
                  summary: Default post-unSuspendAccountHolder 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-unSuspendAccountHolder422Example:
                  summary: Default post-unSuspendAccountHolder 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-unSuspendAccountHolder500Example:
                  summary: Default post-unSuspendAccountHolder 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:
    

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