Adyen Merchants API

openapi: 3.1.0
info:
  version: '6'
  x-publicVersion: true
  title: Adyen Account acceptDispute Merchants 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: Merchants
paths:
  /merchants:
    get:
      tags:
      - Merchants
      summary: Adyen Get a List of Merchant Accounts
      description: "Returns the list of merchant accounts that your API credential has access to. The list is grouped into pages as defined by the query parameters. \n\nTo make this request, your API credential must have the following [roles](https://docs.adyen.com/development-resources/api-credentials#api-permissions):\n* Management API—Account read"
      operationId: get-merchants
      x-sortIndex: 4
      x-methodName: listMerchantAccounts
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      parameters:
      - description: The number of the page to fetch.
        name: pageNumber
        in: query
        required: false
        schema:
          format: int32
          type: integer
      - description: The number of items to have on a page, maximum 100. The default is 10 items on a page.
        name: pageSize
        in: query
        required: false
        schema:
          format: int32
          type: integer
      responses:
        '200':
          content:
            application/json:
              examples:
                success:
                  $ref: '#/components/examples/get-merchants-success-200'
              schema:
                $ref: '#/components/schemas/ListMerchantResponse'
          description: OK - the request has succeeded.
        '204':
          description: No Content - the request has been successfully processed, but there is no additional content.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-merchants400Example:
                  summary: Default get-merchants 400 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-merchants401Example:
                  summary: Default get-merchants 401 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-merchants403Example:
                  summary: Default get-merchants 403 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-merchants422Example:
                  summary: Default get-merchants 422 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-merchants500Example:
                  summary: Default get-merchants 500 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Merchants
      summary: Adyen Create a Merchant Account
      description: 'Creates a merchant account for the company account specified in the request.


        Use this endpoint if your integration requires it, such as Adyen for Platforms Manage. Your Adyen contact will set up your access.


        To make this request, your API credential must have the following [roles](https://docs.adyen.com/development-resources/api-credentials#api-permissions):

        * Management API—Accounts read and write'
      operationId: post-merchants
      x-sortIndex: 1
      x-methodName: createMerchantAccount
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              post-merchants:
                $ref: '#/components/examples/post-merchants-post-merchants'
            schema:
              $ref: '#/components/schemas/CreateMerchantRequest'
      responses:
        '200':
          content:
            application/json:
              examples:
                post-merchants:
                  $ref: '#/components/examples/post-merchants-post-merchants-200'
              schema:
                $ref: '#/components/schemas/CreateMerchantResponse'
          description: OK - the request has succeeded.
        '204':
          description: No Content - the request has been successfully processed, but there is no additional content.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-merchants400Example:
                  summary: Default post-merchants 400 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-merchants401Example:
                  summary: Default post-merchants 401 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-merchants403Example:
                  summary: Default post-merchants 403 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-merchants422Example:
                  summary: Default post-merchants 422 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-merchants500Example:
                  summary: Default post-merchants 500 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /merchants/{merchantId}:
    get:
      tags:
      - Merchants
      summary: Adyen Get a Merchant Account
      description: 'Returns the merchant account specified in the path. Your API credential must have access to the merchant account.


        To make this request, your API credential must have the following [roles](https://docs.adyen.com/development-resources/api-credentials#api-permissions):

        * Management API—Account read'
      operationId: get-merchants-merchantId
      x-sortIndex: 3
      x-methodName: getMerchantAccount
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      parameters:
      - description: The unique identifier of the merchant account.
        name: merchantId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                success:
                  $ref: '#/components/examples/get-merchants-merchantId-success-200'
              schema:
                $ref: '#/components/schemas/Merchant'
          description: OK - the request has succeeded.
        '204':
          description: No Content - the request has been successfully processed, but there is no additional content.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-merchants-merchantId400Example:
                  summary: Default get-merchants-merchantId 400 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-merchants-merchantId401Example:
                  summary: Default get-merchants-merchantId 401 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-merchants-merchantId403Example:
                  summary: Default get-merchants-merchantId 403 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-merchants-merchantId422Example:
                  summary: Default get-merchants-merchantId 422 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-merchants-merchantId500Example:
                  summary: Default get-merchants-merchantId 500 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /merchants/{merchantId}/activate:
    post:
      tags:
      - Merchants
      summary: Adyen Request to Activate a Merchant Account
      description: 'Sends a request to activate the merchant account identified in the path.


        You get the result of the activation asynchronously through a [`merchant.updated`](https://docs.adyen.com/api-explorer/ManagementNotification/latest/post/merchant.updated) webhook. Once the merchant account is activated, you can start using it to accept payments and payouts.


        Use this endpoint if your integration requires it, such as Adyen for Platforms Manage. Your Adyen contact will set up your access.


        To make this request, your API credential must have the following [roles](https://docs.adyen.com/development-resources/api-credentials#api-permissions):

        * Management API—Accounts read and write'
      operationId: post-merchants-merchantId-activate
      x-sortIndex: 2
      x-methodName: requestToActivateMerchantAccount
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      parameters:
      - description: The unique identifier of the merchant account.
        name: merchantId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestActivationResponse'
              examples:
                post-merchants-merchantId-activate200Example:
                  summary: Default post-merchants-merchantId-activate 200 response
                  x-microcks-default: true
                  value:
                    companyId: '500123'
                    merchantId: '500123'
          description: OK - the request has succeeded.
        '204':
          description: No Content - the request has been successfully processed, but there is no additional content.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-merchants-merchantId-activate400Example:
                  summary: Default post-merchants-merchantId-activate 400 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-merchants-merchantId-activate401Example:
                  summary: Default post-merchants-merchantId-activate 401 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-merchants-merchantId-activate403Example:
                  summary: Default post-merchants-merchantId-activate 403 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-merchants-merchantId-activate422Example:
                  summary: Default post-merchants-merchantId-activate 422 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-merchants-merchantId-activate500Example:
                  summary: Default post-merchants-merchantId-activate 500 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /merchants/{merchantId}/apiCredentials:
    get:
      tags:
      - Merchants
      summary: Adyen Get a List of API Credentials
      description: 'Returns the list of [API credentials](https://docs.adyen.com/development-resources/api-credentials) for the merchant account. The list is grouped into pages as defined by the query parameters.


        To make this request, your API credential must have the following [roles](https://docs.adyen.com/development-resources/api-credentials#api-permissions):

        * Management API—API credentials read and write'
      operationId: get-merchants-merchantId-apiCredentials
      x-sortIndex: 0
      x-methodName: listApiCredentials
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      parameters:
      - description: The unique identifier of the merchant account.
        name: merchantId
        in: path
        required: true
        schema:
          type: string
      - description: The number of the page to fetch.
        name: pageNumber
        in: query
        required: false
        schema:
          format: int32
          type: integer
      - description: The number of items to have on a page, maximum 100. The default is 10 items on a page.
        name: pageSize
        in: query
        required: false
        schema:
          format: int32
          type: integer
      responses:
        '200':
          content:
            application/json:
              examples:
                success:
                  $ref: '#/components/examples/get-merchants-merchantId-apiCredentials-success-200'
              schema:
                $ref: '#/components/schemas/ListMerchantApiCredentialsResponse'
          description: OK - the request has succeeded.
        '204':
          description: No Content - the request has been successfully processed, but there is no additional content.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-merchants-merchantId-apiCredentials400Example:
                  summary: Default get-merchants-merchantId-apiCredentials 400 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-merchants-merchantId-apiCredentials401Example:
                  summary: Default get-merchants-merchantId-apiCredentials 401 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-merchants-merchantId-apiCredentials403Example:
                  summary: Default get-merchants-merchantId-apiCredentials 403 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-merchants-merchantId-apiCredentials422Example:
                  summary: Default get-merchants-merchantId-apiCredentials 422 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-merchants-merchantId-apiCredentials500Example:
                  summary: Default get-merchants-merchantId-apiCredentials 500 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Merchants
      summary: Adyen Create an API Credential
      description: 'Creates an [API credential](https://docs.adyen.com/development-resources/api-credentials) for the company account identified in the path. In the request, you can specify the roles and allowed origins for the new API credential.


        The response includes the:

        * [API key](https://docs.adyen.com/development-resources/api-authentication#api-key-authentication): used for API request authentication.

        * [Client key](https://docs.adyen.com/development-resources/client-side-authentication#how-it-works): public key used for client-side authentication.

        * [Username and password](https://docs.adyen.com/development-resources/api-authentication#using-basic-authentication): used for basic authentication.


        > Make sure you store the API key securely in your system. You won''t be able to retrieve it later.


        If your API key is lost or compromised, you need to [generate a new API key](https://docs.adyen.com/api-explorer/#/ManagementService/v1/post/merchants/{merchantId}/apiCredentials/{apiCredentialId}/generateApiKey).


        To make this request, your API credential must have the following [roles](https://docs.adyen.com/development-resources/api-credentials#api-permissions):

        * Management API—API cred

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