openapi: 3.0.3
info:
  title: api-onboarding Account Usage Payers API
  version: v1
  description: View information relating to the 'payer' for a payment that has been initiated through the platform.
servers:
- url: /onboarding
  description: Relative URL
- url: https://api.currencycloud.com/onboarding
  description: Production server (uses live data)
- url: https://devapi.currencycloud.com/onboarding
  description: Dev server (uses test data)
tags:
- name: Payers
  description: View information relating to the 'payer' for a payment that has been initiated through the platform.
paths:
  /payers/{id}:
    get:
      tags:
      - Payers
      x-api-group: pay
      summary: Get Payer
      description: Get a payer record.
      operationId: GetPayer
      produces:
      - application/json
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        type: string
        description: Authentication token
        minLength: 32
      - name: id
        in: path
        required: true
        type: string
        description: Payer UUID.
        format: uuid
      - name: on_behalf_of
        in: query
        required: false
        type: string
        description: A contact UUID for the sub-account you're acting on behalf of.
        format: uuid
      responses:
        '200':
          description: Success.
          schema:
            $ref: '#/definitions/Payer'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '400':
          description: Client error.
          x-errors:
          - code: payer_not_found
            category: id
            message: Payer was not found for this id
            params: ''
          - code: contact_not_found
            category: on_behalf_of
            message: Contact was not found for this id
            params: ''
          - code: id_is_not_valid_uuid
            category: id
            message: id should be in UUID format
            params: ''
          - code: on_behalf_of_self
            category: on_behalf_of
            message: You cannot act on behalf of your own Contact
            params: ''
          schema:
            $ref: '#/definitions/GetPayerError'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '401':
          description: Unauthorized.
          x-errors:
          - code: invalid_supplied_credentials
            category: username
            message: Authentication failed with the supplied credentials
            params: ''
          schema:
            $ref: '#/definitions/UnauthorizedError'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '404':
          description: Resource not found.
          schema:
            $ref: '#/definitions/NotFoundError'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '429':
          description: Too many requests.
          x-errors:
          - code: too_many_requests
            category: base
            message: Too many requests have been made to the api. Please refer to the Developer Center for more information
            params: ''
          schema:
            $ref: '#/definitions/RateLimitError'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '500':
          description: Internal server error
          x-errors:
          - code: internal_server_error
            category: base
            message: Internal server error
            params: ''
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '503':
          description: Service is temporary unavailable
          x-errors:
          - code: service_unavailable
            category: base
            message: Service is temporarily unavailable
            params: ''
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        default:
          description: Unexpected error.
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
components:
  securitySchemes:
    AuthToken:
      type: apiKey
      in: header
      name: X-Auth-Token
definitions:
  RateLimitError:
    type: object
    description: Too many requests.
    required:
    - error_code
    - error_messages
    properties:
      error_code:
        type: string
        description: A high-level error code for the whole request.
      error_messages:
        type: object
        description: Detailed error information for individual input parameters that failed validation. Object keys are the names of the invalid input parameters. Each parameter may have one or more reasons why it failed.
        additionalProperties:
          type: array
          items:
            type: object
            description: An object that represents one of the reasons why the input parameter failed.
            required:
            - code
            - message
            properties:
              code:
                type: string
                description: A unique code that identifies this validation/error.
              message:
                type: string
                description: An explanation of the error in English.
              params:
                type: object
                default: {}
                description: Relevant validation rules that failed. This can be used for translations.
                example:
                  minlength: 1
                  maxlength: 255
  UnauthorizedError:
    type: object
    description: Authorization error.
    required:
    - error_code
    - error_messages
    properties:
      error_code:
        type: string
        description: A high-level error code for the whole request.
        enum:
        - auth_failed
      error_messages:
        type: object
        description: Detailed error information for individual input parameters that failed validation. Object keys are the names of the invalid input parameters. Each parameter may have one or more reasons why it failed.
        additionalProperties:
          type: array
          items:
            type: object
            description: An object that represents one of the reasons why the input parameter failed.
            required:
            - code
            - message
            properties:
              code:
                type: string
                description: A unique code that identifies this error. It can be used for translations.
              message:
                type: string
                description: An explanation of the error in English.
              params:
                type: object
                default: {}
                description: Relevant validation rules that failed. This can be used for translations.
                example:
                  minlength: 1
                  maxlength: 255
    example:
      error_code: auth_failed
      error_messages:
        api_key:
        - code: invalid_supplied_credentials
          message: Authentication failed with the supplied credentials
          params: {}
  NotFoundError:
    type: object
    description: Resource not found.
    required:
    - error_code
    - error_messages
    properties:
      error_code:
        type: string
        description: A high-level error code for the whole request.
      error_messages:
        type: object
        additionalProperties:
          type: array
          items:
            type: object
            description: An object that represents one of the reasons why the input parameter failed.
            required:
            - code
            - message
            properties:
              code:
                type: string
                description: A unique code that identifies this error. It can be used for translations.
              message:
                type: string
                description: An explanation of the error in English.
              params:
                type: object
                default: {}
                description: Relevant validation rules that failed. This can be used for translations.
                example:
                  minlength: 1
                  maxlength: 255
  Payer:
    type: object
    description: Payer
    properties:
      id:
        type: string
        description: Unique UUID for the payer.
      legal_entity_type:
        type: string
        description: Payer's entity type - company or individual.
        enum:
        - company
        - individual
      company_name:
        type: string
        description: The name of the company (if the payer is a company).
      first_name:
        type: string
        description: Payer's first name.
      last_name:
        type: string
        description: Payer's last name.
      address:
        type: array
        items:
          type: string
          description: Line of address.
      city:
        type: string
      state_or_province:
        type: string
      country:
        type: string
        description: Two-letter ISO country code.
      identification_type:
        type: string
        description: The legal document used to verify the identity of the payer (e.g. passport).
      identification_value:
        type: string
        description: A unique reference code for the identification document, such as a passport number.
      postcode:
        type: string
      date_of_birth:
        type: string
      created_at:
        type: string
      updated_at:
        type: string
    example:
      id: 543477161-91de-012f-e284-1e0030c7f3123
      legal_entity_type: company
      company_name: Acme Corporation
      first_name: ''
      last_name: ''
      address:
      - 164 Bishopsgate
      - London
      city: London
      state_or_province: ''
      country: GB
      identification_type: incorporation_number
      identification_value: 123123
      postcode: EC2M 4LX
      date_of_birth: '2023-12-31T23:59:59.000Z'
      created_at: '2023-12-31T23:59:59.000Z'
      updated_at: '2023-12-31T23:59:59.000Z'
  GetPayerError:
    type: object
    description: 'Client error information for the Get Payer endpoint.

      '
    required:
    - error_code
    - error_messages
    properties:
      error_code:
        type: string
        description: A high-level error code for the whole request.
      error_messages:
        type: object
        description: Detailed error information for individual input parameters that failed validation. Object keys are the names of the invalid input parameters. Each parameter may have one or more reasons why it failed.
        additionalProperties:
          type: array
          items:
            type: object
            description: An object that represents one of the reasons why the input parameter failed.
            required:
            - code
            - message
            properties:
              code:
                type: string
                description: A unique code that identifies this error. It can be used for translations.
              message:
                type: string
                description: An explanation of the error in English.
              params:
                type: object
                default: {}
                description: Relevant validation rules that failed. This can be used for translations.
                example:
                  minlength: 1
                  maxlength: 255