Skip to main content

Getting Started

Sandbox and Live Endpoints

getpaid provides two environments with different base URLs :

tip

When testing your integration you should connect to the Sandbox environment and specify the appropriate audience when obtaining an Access Token.

Authentication & Authorization​

To communicate with the getpaid API, you should obtain an OAuth 2.0 Access Tokens using the set of credentials provided to you during onboarding. You will be given a different set of credentials for Sandbox and Live environments.

  1. Make a POST request to https://auth.getpaid.io/oauth/token providing the appropriate credentials and audience:
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.getpaid.io",
  "grant_type": "client_credentials"
}'
  1. 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
}
  1. 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.

How to Handle Response Codes And Error Codes​

getpaid uses HTTP error codes to indicate success or failure of an API call:

  • 2xx range indicates success.
  • 4xx range indicates an error caused by the information provided in the call such as missing fields or invalid parameters.
  • 5xx range indicates an error in the getpaid's servers (this is going to happen rarely).

Errors in the 4xx range can include more details to help handle the error programmatically or report the error back to the user, such as missing required fields or validation problem (an email field that doesn't contain a valid email value). The type field is a link that points to the documentation for the error.

404 - Not Found​

This error happens when the entity you are requesting does not exist or it has been deleted.

{
  "type": "https://docs.getpaid.io/overview/getting-started#404---not-found",
  "title": "Not Found",
  "trace_id": "96ce50247f87f540bb2d86771b3728b8",
  "status": 404
}

409 - Conflict​

When the request cannot be completed due to the current state of the target resource, then the API will return an error with 409.

{
  "type": "https://docs.getpaid.io/overview/getting-started#409---conflict",
  "title": "Conflict",
  "trace_id": "96ce50247f87f540bb2d86771b3728b8",
  "status": 409,
  "detail": "Request cannot be completed due to the current state of the server",
}

422 - Invalid parameters​

When a request contains an invalid value the API will return an error with 422 status code and a body as:

{
  "type": "https://docs.getpaid.io/overview/getting-started#422---invalid-parameters",
  "title": "Invalid Parameters",
  "trace_id": "96ce50247f87f540bb2d86771b3728b8",
  "status": 422,
  "detail": "The request body was invalid",
  "errors": {
    "field": ["'field' is not valid."]
  }
}

You will need to change the provided values in order to make the request succeed.