Skip to main content
API docs by Redocly

Getpaid API (v2)

Download OpenAPI specification:Download

E-mail: support@getpaid.io

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.

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 Getpaid API.

Fields format

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 in uppercase. Examples: DE, US.
currency The currency code fields follow the ISO 4217 standard in uppercase. Examples: EUR, USD.
date Dates are formatted using the complete date format according to the ISO 8601 standard: YYYY-MM-DD. Example: 2023-09-30.
date-time Date-time fields are formatted using the ISO 8601 standard 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 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 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) 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.

Files MIME types

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:

Extensions Kind of document MIME Type
.csv Comma-separated values (CSV) text/csv
.doc Microsoft Word application/msword
.docx Microsoft Word (OpenXML) application/vnd.openxmlformats-officedocument.wordprocessingml.document
.jpeg, .jpg JPEG images image/jpeg
.md Markdown text/markdown
.pdf Adobe Portable Document Format (PDF) application/pdf
.png Portable Network Graphics image/png
.svg Scalable Vector Graphics (SVG) image/svg+xml
.tsv Tab-separated values (TSV) text/tab-separated-values
.txt Text (generally ASCII or ISO 8859-n) text/plain
.xls Microsoft Excel application/vnd.ms-excel
.xlsx Microsoft Excel (OpenXML) application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Authentication

In order to authenticate with Getpaid API 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 client_id, client_secret, and audience to switch between sandbox and live environments.

Check the full details of the Request access token endpoint.

The response will return a Bearer access token in the JSON Web Token (JWT) format in the access_token field which you should use in the Authorization header of any subsequent Getpaid API requests:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "scope": "payments:read_write",
  "expires_in": 3600,
  "token_type": "Bearer"
}

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.

OAuth

Security Scheme Type: OAuth2
Flow type: clientCredentials
Token URL: https://auth.getpaid.io/oauth/token
Scopes:
  • payments:read -

    Allows to read payments and checkouts.

  • payments:read_write -

    Allows to read, create and/or operate payments and checkouts.

Request access token

Obtain an OAuth 2.0 access token to authenticate API requests

Request Body schema: application/json
required
client_id
required
string

Your OAuth client ID for the environment, live or sandbox, you are requesting the token for.

client_secret
required
string

Your OAuth client Secret for the environment, live or sandbox, you are requesting the token for.

audience
required
string <uri>
Enum: "https://api.sandbox.getpaid.io" "https://api.getpaid.io"

The API you wish to integrate with. Use this to switch between sandbox and live environment.

grant_type
required
string

The OAuth grant type.

Value: "client_credentials"

Responses

Request samples

Content type
application/json
Example
{
  • "client_id": "g6gWu46zeP0HH4jkW3i22yJ2shDrNxJ8",
  • "client_secret": "VJG133mOfuHhSfkIS6gozTXzr7FBm-0HS42OZ0cmxJkcHyGrVZMLGJtyruTA4CQv",
  • "audience": "https://api.getpaid.io",
  • "grant_type": "client_credentials"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  • "scope": "accounts:read documents:read_write payments:read",
  • "expires_in": 86400,
  • "token_type": "Bearer"
}

Checkouts

Payment checkout sessions for one-time payments that the buyer can complete using Getpaid hosted checkout.

Create a checkout

Create a payment checkout session.

Webhooks related:

  • checkout_completed: sent when the checkout process is completed with a successful payment.
  • checkout_expired: sent when the checkout life time is reached without a successful payment independent of whether payments were attempted or not.
  • For each payment attempt:
    • payment_captured: sent when the payment funds are captured and secured.
    • payment_failed: sent when a payment fails due to business (decline) or technical issues.
Authorizations:
OAuth
header Parameters
Getpaid-Idempotency-Key
required
string [ 10 .. 100 ] characters ^[a-zA-Z0-9_-]{10,100}$
Example: 5c255194-30ec-11ed-a261-0242ac120002

A unique idempotency key to allow safe retrying. See Getpaid API idempotency for more details.

Request Body schema: application/json
required
reference
required
string [ 1 .. 50 ] characters

An identifier in your system. It is recommended to make it unique but the uniqueness is not enforced by the solution.

amount
required
integer <amount-minor>

The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR).

currency
required
string <currency> = 3 characters

The processing currency code according to the ISO-4217 standard

description
required
string [ 1 .. 250 ] characters

A description of the checkout session. This will be visible to the buyer in the payment page but not in the bank or card statement.

statement_descriptor
string [ 1 .. 22 ] characters ^[a-zA-Z0-9 *\._-]{1,22}$

The statement descriptor that will appear on the buyer's bank or card statement. It will be preceded by the standard prefix GP*.

expires_in
string = 5 characters ^\d{2}:\d{2}$

The span in hours and minutes of time after which the checkout will expire.

any

Specify the payment methods available in the checkout instead of using the default methods. The payment methods must be configured in the seller account to be available.

  • explicit: a list of payment methods to display in the checkout overriding the default methods.
required
object

The list of payment splits for the accounts involved in the funds flow.

object

Buyer details to pre-fill during checkout.

object

Terms for a new standing instruction to gather the consent in the initial payment in a series of recurring payments.

required
object

Configuration for the redirect behavior after the payment is completed.

object

Configuration for webhooks to receive payment status updates.

Responses

Request samples

Content type
application/json
Example
{
  • "reference": "ORD-202510-0232",
  • "amount": 10000,
  • "currency": "EUR",
  • "description": "Order #202510-0232",
  • "splits": {
    },
  • "redirect": {},
  • "webhooks": {}
}

Response samples

Content type
application/json
{
  • "id": "cko_44678r08jtm8zbt227tzhc4nw5",
  • "status": "initiated",
  • "reference": "ORD-202510-0232",
  • "created_at": "2025-10-24T14:45:22.993Z",
  • "updated_at": "2025-10-24T14:45:22.993Z",
  • "expires_at": "2025-10-24T14:15:22.993Z",
  • "flow": {},
  • "payment_methods": {
    },
  • "splits": {
    }
}

Get a checkout

Retrieve a payment checkout session.

Authorizations:
OAuthOAuth
path Parameters
checkout_id
required
string <id> [ 30 .. 50 ] characters
Example: cko_4kf9v6xp00hzc99rdwr5m97wce

The unique identifier of the checkout.

Responses

Response samples

Content type
application/json
Example
{
  • "id": "cko_44678r08jtm8zbt227tzhc4nw5",
  • "status": "completed",
  • "reference": "ORD-202510-0232",
  • "created_at": "2025-10-10T06:43:39.355Z",
  • "updated_at": "2025-10-10T06:44:34.843Z",
  • "expires_at": "2025-10-10T07:13:39.355Z",
  • "amount": 1000,
  • "currency": "EUR",
  • "description": "Order 202510-0232",
  • "payment_methods": {
    },
  • "splits": {
    },
  • "payments": [
    ],
  • "theme": {
    }
}

Payments

Create and manage payments initiated by the platform on behalf of the buyer.

For recurring and unscheduled payments based on a previous standing instruction.

Create a payment

Create a payment initiated by the platform on behalf of a buyer.

Webhooks related:

  • payment_captured: sent when the payment funds are captured and secured.
  • payment_failed: sent when a payment fails due to business (decline) or technical issues.
Authorizations:
OAuth
header Parameters
Getpaid-Idempotency-Key
required
string [ 10 .. 100 ] characters ^[a-zA-Z0-9_-]{10,100}$
Example: 5c255194-30ec-11ed-a261-0242ac120002

A unique idempotency key to allow safe retrying. See Getpaid API idempotency for more details.

Request Body schema: application/json
required
reference
required
string [ 1 .. 50 ] characters

An identifier in your system. It is recommended to make it unique but the uniqueness is not enforced by the solution.

amount
required
integer <amount-minor>

The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR).

currency
required
string <currency> = 3 characters

The processing currency code according to the ISO-4217 standard

statement_descriptor
string [ 1 .. 22 ] characters ^[a-zA-Z0-9 *\._-]{1,22}$

The statement descriptor that will appear on the buyer's bank or card statement. It will be preceded by the standard prefix GP*.

required
object

The list of payment splits for the accounts involved in the funds flow.

required
object

Standing instruction for recurring payments.

object

Configuration for webhooks to receive payment status updates.

Responses

Request samples

Content type
application/json
{
  • "reference": "ORD-202510-0232",
  • "amount": 10000,
  • "currency": "EUR",
  • "splits": {
    },
  • "standing_instruction": {
    },
  • "webhooks": {}
}

Response samples

Content type
application/json
{
  • "id": "pay_4tbftjwzxja1h71nzas1g0g1xm",
  • "status": "captured",
  • "reference": "ORD-202510-0232",
  • "statement_descriptor": "GP*TITAN*202510-0232",
  • "created_at": "2025-10-24T14:45:22.993Z",
  • "updated_at": "2025-10-24T14:45:22.993Z",
  • "method": {
    },
  • "splits": {
    },
  • "totals": {
    }
}

Get a payment

Retrieve a payment.

Authorizations:
OAuthOAuth
path Parameters
payment_id
required
string <id> [ 30 .. 50 ] characters
Example: pay_4a4m2pjycdb1jbj68h1rvk9kcz

The unique identifier of the payment.

Responses

Response samples

Content type
application/json
{
  • "id": "pay_4a4m2pjycdb1jbj68h1rvk9kcz",
  • "status": "refunded",
  • "reference": "ORD-202510-0232",
  • "created_at": "2025-09-01T22:05:48.479Z",
  • "updated_at": "2025-10-12T09:06:11.773Z",
  • "amount": 1000,
  • "currency": "EUR",
  • "statement_descriptor": "TITAN*202510-0232",
  • "origin": {
    },
  • "method": {
    },
  • "splits": {
    },
  • "authentication": {
    },
  • "refunds": [
    ],
  • "standing_instruction": {
    },
  • "totals": {
    }
}

Refund a payment

Refund a captured payment fully or partially.

Webhooks related:

Authorizations:
OAuth
path Parameters
payment_id
required
string <id> [ 30 .. 50 ] characters
Example: pay_4a4m2pjycdb1jbj68h1rvk9kcz

The ID of the payment to refund.

header Parameters
Getpaid-Idempotency-Key
required
string [ 10 .. 100 ] characters ^[a-zA-Z0-9_-]{10,100}$
Example: 5c255194-30ec-11ed-a261-0242ac120002

A unique idempotency key to allow safe retrying. See Getpaid API idempotency for more details.

Request Body schema: application/json
required
type
required
string

The type of refund to be processed.

reference
required
string [ 1 .. 50 ] characters

An identifier in your system. It is recommended to make it unique but the uniqueness is not enforced by the solution.

object

Configuration for webhooks to receive refund status updates.

Responses

Request samples

Content type
application/json
Example
{}

Response samples

Content type
application/json
Example
{
  • "id": "rfd_4a4m2pjycdb1jbj68h1rvk9kcz",
  • "type": "full",
  • "status": "initiated",
  • "reference": "RFD-202510-0002",
  • "created_at": "2025-10-25T07:11:57.761Z",
  • "updated_at": "2025-10-25T07:11:57.761Z",
  • "amount": 1000,
  • "splits": {
    }
}

Accept payments webhooks

Webhooks related to accepting payment events.

checkout_completed Webhook

The checkout_completed webhook is sent when the checkout process is completed with a successful payment.

header Parameters
Getpaid-Trace-Id
required
string
Example: 96ce50247f87f540bb2d86771b3728b8

The trace identifier for the request. It is a good idea to log this and provide it with any support requests

Request Body schema: application/json
id
required
string <id> [ 30 .. 50 ] characters

The unique identifier of the event.

type
required
string

The type of event.

Value: "checkout_completed"
version
required
string

The version of the event type.

Value: "v2"
occurred_at
required
string <date-time> = 24 characters

The UTC date and time at which the event occurred.

required
object

The event data specific to each event type and version.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_4a4m2pjycdb1jbj68h1rvk9kcz",
  • "type": "checkout_completed",
  • "version": "v2",
  • "occurred_at": "2025-09-01T22:05:48.479Z",
  • "data": {
    }
}

checkout_failed Webhook

The checkout_failed webhook is sent when the checkout lifetime is reached without a successful payment attempt, and at least one payment was attempted but none were successful.

It can be received days after the checkout is created depending on the payment method selected.

header Parameters
Getpaid-Trace-Id
required
string
Example: 96ce50247f87f540bb2d86771b3728b8

The trace identifier for the request. It is a good idea to log this and provide it with any support requests

Request Body schema: application/json
id
required
string <id> [ 30 .. 50 ] characters

The unique identifier of the event.

type
required
string

The type of event.

Value: "checkout_failed"
version
required
string

The version of the event type.

Value: "v2"
occurred_at
required
string <date-time> = 24 characters

The UTC date and time at which the event occurred.

required
object

The event data specific to each event type and version.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_4a4m2pjycdb1jbj68h1rvk9kcz",
  • "type": "checkout_failed",
  • "version": "v2",
  • "occurred_at": "2025-09-01T22:05:48.479Z",
  • "data": {
    }
}

checkout_in_progress Webhook

The checkout_in_progress webhook is sent when the checkout lifetime reaches its expiration, but a payment attempt is still in progress.

Banking payment methods are typical examples where this webhook can be sent, as the payment processing can take several days depending on the bank processing times.

header Parameters
Getpaid-Trace-Id
required
string
Example: 96ce50247f87f540bb2d86771b3728b8

The trace identifier for the request. It is a good idea to log this and provide it with any support requests

Request Body schema: application/json
id
required
string <id> [ 30 .. 50 ] characters

The unique identifier of the event.

type
required
string

The type of event.

Value: "checkout_in_progress"
version
required
string

The version of the event type.

Value: "v2"
occurred_at
required
string <date-time> = 24 characters

The UTC date and time at which the event occurred.

required
object

The event data specific to each event type and version.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_4a4m2pjycdb1jbj68h1rvk9kcz",
  • "type": "checkout_in_progress",
  • "version": "v2",
  • "occurred_at": "2025-09-01T22:05:48.479Z",
  • "data": {
    }
}

checkout_unattempted Webhook

The checkout_unattempted webhook is sent when the checkout life time is reached without a payment.

header Parameters
Getpaid-Trace-Id
required
string
Example: 96ce50247f87f540bb2d86771b3728b8

The trace identifier for the request. It is a good idea to log this and provide it with any support requests

Request Body schema: application/json
id
required
string <id> [ 30 .. 50 ] characters

The unique identifier of the event.

type
required
string

The type of event.

Value: "checkout_unattempted"
version
required
string

The version of the event type.

Value: "v2"
occurred_at
required
string <date-time> = 24 characters

The UTC date and time at which the event occurred.

required
object

The event data specific to each event type and version.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_4a4m2pjycdb1jbj68h1rvk9kcz",
  • "type": "checkout_unattempted",
  • "version": "v2",
  • "occurred_at": "2025-09-01T22:05:48.479Z",
  • "data": {
    }
}

payment_captured Webhook

The payment_captured webhook is sent when a payment is successfully captured and the funds are secured for the seller.

header Parameters
Getpaid-Trace-Id
required
string
Example: 96ce50247f87f540bb2d86771b3728b8

The trace identifier for the request. It is a good idea to log this and provide it with any support requests

Request Body schema: application/json
id
required
string <id> [ 30 .. 50 ] characters

The unique identifier of the event.

type
required
string

The type of event.

Value: "payment_captured"
version
required
string

The version of the event type.

Value: "v2"
occurred_at
required
string <date-time> = 24 characters

The UTC date and time at which the event occurred.

required
object

The event data specific to each event type and version.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_4a4m2pjycdb1jbj68h1rvk9kcz",
  • "type": "payment_captured",
  • "version": "v2",
  • "occurred_at": "2025-09-01T22:05:48.479Z",
  • "data": {
    }
}

payment_failed Webhook

The payment_failed webhook is sent when a payment fails due to business (decline) or technical issues.

header Parameters
Getpaid-Trace-Id
required
string
Example: 96ce50247f87f540bb2d86771b3728b8

The trace identifier for the request. It is a good idea to log this and provide it with any support requests

Request Body schema: application/json
id
required
string <id> [ 30 .. 50 ] characters

The unique identifier of the event.

type
required
string

The type of event.

Value: "payment_failed"
version
required
string

The version of the event type.

Value: "v2"
occurred_at
required
string <date-time> = 24 characters

The UTC date and time at which the event occurred.

required
object

The event data specific to each event type and version.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_4a4m2pjycdb1jbj68h1rvk9kcz",
  • "type": "payment_failed",
  • "version": "v2",
  • "occurred_at": "2025-09-01T22:05:48.479Z",
  • "data": {
    }
}

payment_refunded Webhook

The payment_refunded webhook is sent when a refund is successfully completed and the funds have been returned to the buyer.

header Parameters
Getpaid-Trace-Id
required
string
Example: 96ce50247f87f540bb2d86771b3728b8

The trace identifier for the request. It is a good idea to log this and provide it with any support requests

Request Body schema: application/json
id
required
string <id> [ 30 .. 50 ] characters

The unique identifier of the event.

type
required
string

The type of event.

Value: "payment_refunded"
version
required
string

The version of the event type.

Value: "v2"
occurred_at
required
string <date-time> = 24 characters

The UTC date and time at which the event occurred.

required
object

The event data specific to each event type and version.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_4a4m2pjycdb1jbj68h1rvk9kcz",
  • "type": "payment_refunded",
  • "version": "v2",
  • "occurred_at": "2025-09-01T22:05:48.479Z",
  • "data": {
    }
}

payment_refund_failed Webhook

The payment_refund_failed webhook is sent when a refund has failed.

header Parameters
Getpaid-Trace-Id
required
string
Example: 96ce50247f87f540bb2d86771b3728b8

The trace identifier for the request. It is a good idea to log this and provide it with any support requests

Request Body schema: application/json
id
required
string <id> [ 30 .. 50 ] characters

The unique identifier of the event.

type
required
string

The type of event.

Value: "payment_refund_failed"
version
required
string

The version of the event type.

Value: "v2"
occurred_at
required
string <date-time> = 24 characters

The UTC date and time at which the event occurred.

required
object

The event data specific to each event type and version.

Responses

Request samples

Content type
application/json
{
  • "id": "evt_4a4m2pjycdb1jbj68h1rvk9kcz",
  • "type": "payment_refund_failed",
  • "version": "v2",
  • "occurred_at": "2025-09-01T22:05:48.479Z",
  • "data": {
    }
}

Queries

List resources filtering and sorting them as needed.

Query resources

Query Getpaid solution resources obtaining specific data by filtering.

Authorizations:
OAuth
path Parameters
resource_type
required
string
Value: "payments"

The type of the resources to query.

Request Body schema: application/json
required
type
string

The type of the Getpaid solution resources to query.

It is not needed to set this property, as it is inferred from the request path {resource_type} used. In case this field is set, it will be validated against the value from the request path.

first
integer [ 1 .. 100 ]
Default: 20

Pagination. The number of elements that will be retrieved.

after
string <= 250 characters

Pagination. The cursor from next page will be retrieved.

object

Filters to reduce the data set to query. If not set, all resources available of the given type will be exported.

Array of objects non-empty unique

Fields to sort the data by. If not set, the data will be sorted by the creation date descending.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "payments",
  • "filters": {
    }
}

Response samples

Content type
application/json
{
  • "type": "payments",
  • "cursor": "Q3VyaW9zaXR5IEtpbGxlZCB0aGUgQ2F0Cg==",
  • "data": [
    ]
}