GetPaid Authentication API

openapi: 3.1.0
info:
  title: Getpaid Accounts Authentication API
  version: v2
  contact:
    email: support@getpaid.io
  description: '# Getting started


    Our APIs provide programmatic access to the Getpaid solution. This page contains a comprehensive reference for all

    resources of the Getpaid public API. For walkthrough documentation please see [Getpaid guides](/) for step by step usage

    of the Getpaid platform including the API and [Getpaid API integration](/integration/api) for the technical aspects of

    this Getpaid API.


    To get started, book a demo and sign up at <https://getpaid.io>. This will give you access to the [Getpaid

    dashboard](https://dashboard.getpaid.io) where you can configure your account and retrieve your credentials needed to

    authenticate with Getpaid API.


    ## Postman


    Getpaid provides a Postman collection to test the API features in sandbox. You can [download the Postman collection and

    the environments](/integration/api/postman) to start testing the Getpaid API.


    ## Fields formats


    | Type | Format |

    | :- | :- |

    | `amount-minor` | Amount in the minor currency unit (e.g. 100 cents for 1 EUR). |

    | `country` | The country code fields follow the [ISO 3166-1 alpha-2 standard](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) in uppercase. Examples: `DE`, `US`. |

    | `currency` | The currency code fields follow the [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217) in uppercase. Examples: `EUR`, `USD`. |

    | `date` | Dates are formatted using the complete date format according to the [ISO 8601 standard](https://www.w3.org/TR/NOTE-datetime): `YYYY-MM-DD`. Example: `2023-09-30`.                                        |

    | `date-time` | Date-time fields are formatted using the [ISO 8601 standard](https://www.w3.org/TR/NOTE-datetime) for the combined date and time in UTC with 3 seconds fractional digits: `YYYY-MM-DDThh:mm:ss.SSSZ`. Example: `2015-09-01T23:59:59.479Z`. |

    | `date-time-offset` | Date-time fields with time-zone are formatted [ISO 8601 standard](https://www.w3.org/TR/NOTE-datetime) for the combined date and time with the time-zone and no second fractional digits: `YYYY-MM-DDThh:mm:ssTZD`. Example: `2015-09-01T23:59:59+01:00`. |

    | `email` | Email fields should follow the [RFC 5322](https://tools.ietf.org/html/rfc5322) standard. Example: `jon.smith@acme.com` |

    | `hex-color` | Colors are represented as a string starting with `#` followed by six hexadecimal digits. Each pair of digits represents the intensity of red, green, and blue components respectively. Examples: `#FFFFFF`, `#000000`, `#FF5733`. |

    | `id` | Identifiers are formatted as a string of 3 alphabetic characters (which represents the type of the identified object), one underscore and 26 alphanumeric characters. Every identifier generated in our system is globally unique. Examples: `acc_44678r08jtm8zbt227tzhc4nw5`, `doc_473cr1y0ghbyc3m1yfbwvn3nxx`. |

    | `ip-address` | IP fields are formatted using the [Internet Protocol version 4 (IPv4)](https://en.wikipedia.org/wiki/Internet_Protocol_version_4) standard: `x.x.x.x` where `x` must be a decimal value between `0` and `255`. Example: `192.158.1.38`. |

    | `version` | A resource version. For resources that can evolved over time, a unique reference of the snapshot used in other resource. For example, the account information used for a payment, the information used for the statement descriptor or the processing configuration are tighted to the version of the account. |

    '
servers:
- url: https://api.getpaid.io
  description: Live
- url: https://api.sandbox.getpaid.io
  description: Sandbox
tags:
- name: Authentication
  description: '<!-- markdownlint-disable link-fragments -->

    In order to authenticate with Getpaid API you need to request an OAuth 2.0 access token using your client ID and secret

    by calling the [Request access token endpoint](#tag/Authentication/operation/request_access_token).

    <!-- markdownlint-enable link-fragments -->


    Check full details on [how API authentication and authorization works](/integration/api/authentication/) and [how to get

    your client credentials](/integration/api/authentication/client-credentials).


    <!-- ReDoc-Inject: <security-definitions> -->

    '
paths:
  /oauth/token:
    post:
      tags:
      - Authentication
      summary: Request access token
      description: Obtain an OAuth 2.0 access token to authenticate API requests
      operationId: request_access_token
      servers:
      - url: https://auth.getpaid.io
        description: OAuth server
      security: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestAccessTokenRequest'
            examples:
              LiveAccessToken:
                $ref: '#/components/examples/LiveAccessToken'
              SandboxAccessToken:
                $ref: '#/components/examples/SandboxAccessToken'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestAccessTokenResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetailsBase'
components:
  examples:
    LiveAccessToken:
      summary: Live access token
      value:
        client_id: g6gWu46zeP0HH4jkW3i22yJ2shDrNxJ8
        client_secret: VJG133mOfuHhSfkIS6gozTXzr7FBm-0HS42OZ0cmxJkcHyGrVZMLGJtyruTA4CQv
        audience: https://api.getpaid.io
        grant_type: client_credentials
    SandboxAccessToken:
      summary: Sandbox access token
      value:
        client_id: 0UvlOgIPIKqAzd0yi7Xnk8NroSsRLOaj
        client_secret: S6gozTXzrS42OZ0cmxVJG133mOfuHhSfkIJkcH7FBm-0HyGrVZMLGJtyruTA4CQv
        audience: https://api.sandbox.getpaid.io
        grant_type: client_credentials
  schemas:
    RequestAccessTokenResponse:
      type: object
      required:
      - access_token
      - scope
      - expires_in
      - token_type
      properties:
        access_token:
          description: The OAuth access token (JWT) used to authenticate to Getpaid API.
          type: string
          example: eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
        scope:
          description: The API scopes granted to the access token.
          type: string
          example: accounts:read documents:read_write payments:read
        expires_in:
          description: The duration (in seconds) until the access token expires.
          type: integer
          example: 86400
        token_type:
          description: The type of token returned.
          type: string
          enum:
          - Bearer
    ProblemDetailsBase:
      type: object
      description: The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)].
      required:
      - type
      - title
      - status
      properties:
        type:
          type: string
          description: A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that identifies the problem type. It should provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about:blank".
          format: uri
          example: https://docs.getpaid.io/ref/error-types#problem
        title:
          type: string
          description: A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
          example: Invalid Request
        status:
          type: integer
          description: The HTTP status code.
          minimum: 400
          maximum: 599
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
          example: The request body was invalid
    RequestAccessTokenRequest:
      type: object
      required:
      - client_id
      - client_secret
      - audience
      - grant_type
      properties:
        client_id:
          description: Your OAuth client ID for the environment, live or sandbox, you are requesting the token for.
          type: string
          example: g6gWu46zeP0HH4jkW3i22yJ2shDrNxJ8
        client_secret:
          description: Your OAuth client Secret for the environment, live or sandbox, you are requesting the token for.
          type: string
          example: S6gozTXzrS42OZ0cmxVJG133mOfuHhSfkIJkcH7FBm-0HyGrVZMLGJtyruTA4CQv
        audience:
          description: The API you wish to integrate with. Use this to switch between sandbox and live environment.
          type: string
          format: uri
          enum:
          - https://api.sandbox.getpaid.io
          - https://api.getpaid.io
        grant_type:
          description: The OAuth grant type.
          type: string
          const: client_credentials
  securitySchemes:
    OAuth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.getpaid.io/oauth/token
          scopes:
            accounts:read: Allows to read accounts and onboarding applications.
            accounts:read_write: Allows to read, create and/or operate accounts and onboarding applications.
            payments:read: Allows to read payments and checkouts.
            payments:read_write: Allows to read, create and/or operate payments and checkouts.
x-tagGroups:
- name: General
  tags:
  - Authentication
  - Documents
- name: Accept payments
  tags:
  - Checkouts
  - Payments
  - Accept payments webhooks
- name: Onboard sellers
  tags:
  - Accounts
  - Applications
  - Onboard sellers webhooks
- name: Operate
  tags:
  - Queries
  - Exports
  - Analytics
  - Operate webhooks