getpaid API (v2alpha1)

Our APIs provide programmatic access to the getpaid platform. This page contains a comprehensive reference for all of our public APIs. For walkthrough documentation please see our main docs site.

To get started, sign up at https://getpaid.io. This will give you access to the getpaid Dashboard where you can configure your account and retrieve your credentials needed to authenticate with our APIs.

To streamline integration we provide client libraries for a number of languages, otherwise you can integrate directly with the API using the HTTP tooling built-in to most modern frameworks.

The format of the files uploaded must correspond to the MIME type in the Content-Type header. See the supported file formats and the corresponding MIME types:

In order to authenticate with getpaid APIs you need to request an OAuth 2.0 Access Token using your Client ID and Secret available from the getpaid Dashboard:

curl --location --request POST 'https://auth.getpaid.io/oauth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "client_id": "{{client_id}}",
  "client_secret": "{{client_secret}}",
  "audience": "https://api.sandbox.getpaid.io",
  "grant_type": "client_credentials"
}'

Specify the appropriate audience, client_id and client_secret to switch between Sandbox and Live environments. Full details of the access token endpoint can be found here.

This will return a Bearer access token in the JSON Web Token (JWT) format which you should use in the Authorization header of any subsequent getpaid API requests:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "token_type": "bearer",
  "expires_in": 3600
}

The access token will be valid for the length of time in seconds indicated by the expires_in field. When it expires, you should request a new one. If using one of our client libraries, this will be handled automatically for you.

An account is the business that will be onboarded to getpaid. The account is the main entity that will be used to enable the different capabilities that getpaid offers.

The different relationships that accounts can have with one another. A link can define the hierarchy within the whole company and also allows the assignment of different "roles" that the current account can play in relation to each connected account.

There are several types of relationships an account can have. The possible ones are:

• can_use - Allows source account to use the resources of destination account.

A bank account authorization is a permission granted by a bank account holder, allowing another person or entity to access, manage, or perform specific transactions on their account.

Bank account authorizations have a status which indicates the current state of the consent process. The possible statuses are:

• completed - The request was completed successfully.
• next_step_required - The request requires additional action before it can be completed.
• awaiting - The request is pending and waiting for a response or action from an external party.
• rejected - The request was rejected by the user/bank.
• failed - The request failed due to technical reasons.

In a bank account authorization process, there are multiple steps that need to be followed to complete the action. These steps are defined by the next_step block, which guides the flow of the authorization process.

Possible values for next_step.type:

• configure_redirect - Redirection information needs to be collected by calling Configure Single Redirect Bank Account Authorization endpoint.
• redirect - The user needs to be redirected to the bank's website to complete a required action.
• pass_credentials - The user needs to provide their credentials (e.g., username, password) for authentication purposes by calling Pass User's Credentials Bank Account Authorization.
• select_sca_method - The user must select a Strong Customer Authentication (SCA) method, such as SMS, app-based authentication, or a hardware token by calling Select SCA Method For Bank Account Authorization.
• pass_sca_code - The user needs to enter an SCA code (e.g., a one-time password) that was generated from their chosen SCA method by calling Pass SCA Code For Bank Account Authorization.
• poll - To poll the consent status, by calling Get Bank Account Authorization, is required in order to determine whether the user has successfully authorized the request with the bank. Because the flow occurs directly between the end user and the bank without getpaid acting as an intermediary, for example, via a secondary device such as a mobile phone.

The series are used to create invoices with auto-generated codes. Invoices series can be created only for accounts with issue_invoices capability enabled.

The prefix and suffix fields are used to generate the invoice number, the padding field is used to pad the number with zeros, the valid_from and valid_to fields are used to define the period in which the series is valid. The produced invoices reference will be {prefix}{padded number}{suffix}, the length of the reference is limited to 50 characters. So the sum of the length of prefix, suffix and the padding should be less than or equal to 50.

Labels are used to categorize and organize your data. They can be used to group invoices, accounts, or any other entity in the system.

A payment instrument represents a financial entity that can be used for processing payments, invoicing, and reconciliation. It contains essential details about the funding source, such as a bank account or other financial methods, and provides metadata related to its status and capabilities.

Note that every change performed on a payment instrument (create, disable, or enable) will alter the account version and can trigger some verification checks required on any capability.

Payment instruments have a status which indicates its current state. The possible statuses are:

• active - The payment instrument is active and can be used.
• inactive - The payment instrument is inactive and cannot be used.