Adyen Documents API

openapi: 3.1.0
info:
  version: '6'
  x-publicVersion: true
  title: Adyen Account acceptDispute Documents 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: Documents
paths:
  /getUploadedDocuments:
    post:
      tags:
      - Documents
      summary: Adyen Get Documents
      description: 'Returns documents that were previously uploaded for an account holder. Adyen uses the documents during the [verification process](https://docs.adyen.com/marketplaces-and-platforms/classic/verification-process).

        '
      operationId: post-getUploadedDocuments
      x-groupName: Verification
      x-sortIndex: 2
      x-methodName: getUploadedDocuments
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              basic:
                $ref: '#/components/examples/post-getUploadedDocuments-basic'
            schema:
              $ref: '#/components/schemas/GetUploadedDocumentsRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetUploadedDocumentsResponse'
              examples:
                post-getUploadedDocuments200Example:
                  summary: Default post-getUploadedDocuments 200 response
                  x-microcks-default: true
                  value:
                    documentDetails:
                    - example_value
                    invalidFields:
                    - example_value
                    pspReference: REF-001
                    resultCode: CODE123
          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-getUploadedDocuments401Example:
                  summary: Default post-getUploadedDocuments 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-getUploadedDocuments422Example:
                  summary: Default post-getUploadedDocuments 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-getUploadedDocuments500Example:
                  summary: Default post-getUploadedDocuments 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
  /uploadDocument:
    post:
      tags:
      - Documents
      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
  /documents:
    post:
      tags:
      - Documents
      summary: Adyen Upload a Document for Verification Checks
      description: "Uploads a document for verification checks.\n\n Adyen uses the information from the [legal entity](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/legalEntities) to run automated verification checks. If these checks fail, you will be notified to provide additional documents.\n\n You should only upload documents when Adyen requests additional information for the legal entity.\n\n >You can upload a maximum of 15 pages for photo IDs."
      x-addedInVersion: '1'
      operationId: post-documents
      x-sortIndex: 4
      x-methodName: uploadDocumentForVerificationChecks
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              uploadDocument:
                $ref: '#/components/examples/post-documents-uploadDocument'
            schema:
              $ref: '#/components/schemas/Document'
      parameters:
      - description: Use a suberror code as your requested verification code. You can include one code at a time in your request header. Requested verification codes can only be used in your test environment.
        example: '1_3008'
        name: x-requested-verification-code
        in: header
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                uploadDocument:
                  $ref: '#/components/examples/post-documents-uploadDocument-200'
              schema:
                $ref: '#/components/schemas/Document'
          description: OK - the request has succeeded.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-documents400Example:
                  summary: Default post-documents 400 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-documents401Example:
                  summary: Default post-documents 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:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-documents403Example:
                  summary: Default post-documents 403 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-documents422Example:
                  summary: Default post-documents 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-documents500Example:
                  summary: Default post-documents 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
  /documents/{id}:
    delete:
      tags:
      - Documents
      summary: Adyen Delete a Document
      description: Deletes a document.
      x-addedInVersion: '1'
      operationId: delete-documents-id
      x-sortIndex: 7
      x-methodName: deleteDocument
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      parameters:
      - description: The unique identifier of the document to be deleted.
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: 'No Content - look at the actual response code for the status of the request. '
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                delete-documents-id400Example:
                  summary: Default delete-documents-id 400 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                delete-documents-id401Example:
                  summary: Default delete-documents-id 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:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                delete-documents-id403Example:
                  summary: Default delete-documents-id 403 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                delete-documents-id422Example:
                  summary: Default delete-documents-id 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:
                delete-documents-id500Example:
                  summary: Default delete-documents-id 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
    get:
      tags:
      - Documents
      summary: Adyen Get a Document
      description: Returns a document.
      x-addedInVersion: '1'
      operationId: get-documents-id
      x-sortIndex: 5
      x-methodName: getDocument
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      parameters:
      - description: The unique identifier of the document.
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                success:
                  $ref: '#/components/examples/get-documents-id-success-200'
              schema:
                $ref: '#/components/schemas/Document'
          description: OK - the request has succeeded.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                get-documents-id400Example:
                  summary: Default get-documents-id 400 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                get-documents-id401Example:
                  summary: Default get-documents-id 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:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                get-documents-id403Example:
                  summary: Default get-documents-id 403 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                get-documents-id422Example:
                  summary: Default get-documents-id 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:
                get-documents-id500Example:
                  summary: Default get-documents-id 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
    patch:
      tags:
      - Documents
      summary: Adyen Update a Document
      description: "Updates a document.\n\n >You can upload a maximum of 15 pages for photo IDs."
      x-addedInVersion: '1'
      operationId: patch-documents-id
      x-sortIndex: 6
      x-methodName: updateDocument
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              updateDocument:
                $ref: '#/components/examples/patch-documents-id-updateDocument'
            schema:
              $ref: '#/components/schemas/Document'
      parameters:
      - description: The unique identifier of the document to be updated.
        name: id
        in: path
        required: true
        schema:
          type: string
      - description: Use the requested verification code 0_0001 to resolve any suberrors associated with the document. Requested verification codes can only be used in your test environment.
        example: '0_0001'
        name: x-requested-verification-code
        in: header
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                updateDocument:
                  $ref: '#/components/examples/patch-documents-id-updateDocument-200'
              schema:
                $ref: '#/components/schemas/Document'
          description: OK - the request has succeeded.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                patch-documents-id400Example:
                  summary: Default patch-documents-id 400 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                patch-documents-id401Example:
                  summary: Default patch-documents-id 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:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                patch-documents-id403Example:
                  summary: Default patch-documents-id 403 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                patch-documents-id422Example:
                  summary: Default patch-documents-id 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:
                patch-documents-id500Example:
                  summary: Default patch-documents-id 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
    GetUploadedDocumentsResponse:
      properties:
        documentDetails:
          description: A list of the documents and their details.
          items:
            $ref: '#/components/schemas/DocumentDetail'
          type: array
        invalidFields:
          x-addedInVersion: '5'
          description: Contains field validation errors that would prevent requests from being processed.
          items:
            $ref: '#/components/schemas/ErrorFieldType'
          type: array
        pspReference:
          description: The reference of a request. Can be used to uniquely identify the request.
          type: string
        resultCode:
          description: The result code.
          type: string
      type: object
    StoreDetail:
      properties:
        address:
          description: The address of the physical store where the account holder will process p

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