Adyen Pins API

openapi: 3.1.0
info:
  version: '6'
  x-publicVersion: true
  title: Adyen Account acceptDispute Pins 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: Pins
paths:
  /pins/change:
    post:
      tags:
      - Pins
      summary: Adyen Change Pin
      description: Change Pin
      x-addedInVersion: '1'
      operationId: post-pins-change
      x-sortIndex: 2
      x-methodName: changePin
      security:
      - clientKey: []
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PinChangeRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PinChangeResponse'
              examples:
                post-pins-change200Example:
                  summary: Default post-pins-change 200 response
                  x-microcks-default: true
                  value:
                    status: completed
          description: OK - the request has succeeded.
        '401':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-401'
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-403'
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-422'
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-500'
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /pins/publicKey:
    get:
      tags:
      - Pins
      summary: Adyen Get RSA PublicKey
      description: Get RSA publicKey
      x-addedInVersion: '1'
      operationId: get-pins-publicKey
      x-sortIndex: 1
      x-methodName: getRsaPublickey
      security:
      - clientKey: []
      - BasicAuth: []
      - ApiKeyAuth: []
      parameters:
      - description: Purpose of publicKey.
        name: purpose
        in: query
        required: false
        schema:
          type: string
      - description: Format of publicKey.
        name: format
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicKeyResponse'
              examples:
                get-pins-publicKey200Example:
                  summary: Default get-pins-publicKey 200 response
                  x-microcks-default: true
                  value:
                    publicKey: example_value
                    publicKeyExpiryDate: example_value
          description: OK - the request has succeeded.
        '401':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-401'
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-403'
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-422'
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-500'
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /pins/reveal:
    post:
      tags:
      - Pins
      summary: Adyen Reveal Pin
      description: Reveal Pin
      x-addedInVersion: '1'
      operationId: post-pins-reveal
      x-sortIndex: 2
      x-methodName: revealPin
      security:
      - clientKey: []
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevealPinRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevealPinResponse'
              examples:
                post-pins-reveal200Example:
                  summary: Default post-pins-reveal 200 response
                  x-microcks-default: true
                  value:
                    encryptedPinBlock: example_value
                    token: example_value
          description: OK - the request has succeeded.
        '401':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-401'
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-403'
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-422'
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-500'
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    PinChangeResponse:
      properties:
        status:
          description: The pin change status.
          enum:
          - completed
          - pending
          - unavailable
          type: string
      required:
      - status
      type: object
    PinChangeRequest:
      properties:
        encryptedKey:
          description: Symmetric session key encrypted under the public key.
          type: string
        encryptedPinBlock:
          description: The encrypted PIN block
          type: string
        paymentInstrumentId:
          description: The unique identifier of the payment instrument.
          type: string
        token:
          description: The token which is used to construct the pinblock.
          type: string
      required:
      - paymentInstrumentId
      - encryptedKey
      - token
      - encryptedPinBlock
      type: object
    RestServiceError:
      properties:
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          type: string
        errorCode:
          description: A code that identifies the problem type.
          type: string
        instance:
          description: A unique URI that identifies the specific occurrence of the problem.
          type: string
        invalidFields:
          description: Detailed explanation of each validation error, when applicable.
          items:
            $ref: '#/components/schemas/InvalidField'
          type: array
        requestId:
          description: A unique reference for the request, essentially the same as `pspReference`.
          type: string
        response:
          description: JSON response payload.
          $ref: '#/components/schemas/JSONObject'
        status:
          description: The HTTP status code.
          format: int32
          type: integer
        title:
          description: A short, human-readable summary of the problem type.
          type: string
        type:
          description: A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
          type: string
      required:
      - type
      - errorCode
      - title
      - detail
      - status
      type: object
    RevealPinRequest:
      properties:
        encryptedKey:
          description: Symmetric session key encrypted under the public key.
          type: string
        paymentInstrumentId:
          description: The unique identifier of the payment instrument.
          type: string
      required:
      - paymentInstrumentId
      - encryptedKey
      type: object
    InvalidField:
      properties:
        message:
          description: Description of the validation error.
          type: string
        name:
          description: The field that has an invalid value.
          type: string
        value:
          description: The invalid value.
          type: string
      required:
      - name
      - value
      - message
      type: object
    JSONObject:
      type: object
    PublicKeyResponse:
      properties:
        publicKey:
          description: The public key to be used for encrypting the symmetric session key.
          type: string
        publicKeyExpiryDate:
          description: The expiry date of the public key.
          type: string
      required:
      - publicKey
      - publicKeyExpiryDate
      type: object
    RevealPinResponse:
      properties:
        encryptedPinBlock:
          description: The encrypted PIN block.
          type: string
        token:
          description: The encrypted PIN block extraction token.
          type: string
      required:
      - encryptedPinBlock
      - token
      type: object
  examples:
    generic-500:
      summary: Response code - 500 Internal Server Error
      value:
        type: https://docs.adyen.com/errors/general/internal
        title: An internal error happened
        status: 500
        detail: Unrecoverable error while trying to create payment instrument
        requestId: 1WAF555PLWNTLYOQ
        errorCode: '00_500'
    generic-401:
      summary: Response code - 401 Unauthorized
      value:
        type: https://docs.adyen.com/errors/security/unauthorized
        title: Unauthorized
        status: 401
        detail: Not authorized to access this service.
        errorCode: '00_401'
    generic-403:
      summary: Response code - 403 Forbidden.
      value:
        type: https://docs.adyen.com/errors/security/unauthorized
        title: Forbidden
        status: 403
        detail: Not the right permission to access this service.
        errorCode: '00_403'
    generic-422:
      summary: Response code - 422 Unprocessable Entity.
      value:
        type: https://docs.adyen.com/errors/general/invalid-field-value
        title: Invalid Payment Instrument information provided
        status: 422
        detail: The balanceAccountId can only be changed when the status is Inactive or Requested
        requestId: 1W1UI15PLVGC9V8O
        errorCode: '30_031'
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-API-Key
      type: apiKey
    BasicAuth:
      scheme: basic
      type: http
x-groups:
- Account holders
- Accounts
- Verification