GetPaid Queries API
List resources filtering and sorting them as needed.
OpenAPI Specification
openapi: 3.1.0
info:
title: Getpaid Accounts Queries 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: Queries
description: List resources filtering and sorting them as needed.
paths:
/v2/{resource_type}/query:
post:
tags:
- Queries
summary: Query resources
description: 'Query Getpaid solution resources obtaining specific data by filtering and retrieving each resource type:
- `checkouts` - [Query checkouts](#tag/Checkouts/operation/query_checkouts)
- `payments` - [Query payments](#tag/Payments/operation/query_payments)
'
operationId: query_resources
security:
- OAuth:
- payments:read
parameters:
- name: resource_type
in: path
description: The type of the resources to query.
required: true
schema:
$ref: '#/components/schemas/QueriesResourceType'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResourcesRequest'
examples:
QueryCheckouts:
$ref: '#/components/examples/QueryCheckouts'
QueryPayments:
$ref: '#/components/examples/QueryPayments'
QueryNext20Payments:
$ref: '#/components/examples/QueryNext20Payments'
required: true
responses:
'200':
description: OK
headers:
Getpaid-Trace-Id:
$ref: '#/components/headers/GetpaidTraceId'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResourcesResponse'
examples:
FilteredPayments:
$ref: '#/components/examples/FilteredPayments'
FilteredCheckouts:
$ref: '#/components/examples/FilteredCheckouts'
'400':
$ref: '#/components/responses/400BadRequest'
'401':
$ref: '#/components/responses/401Unauthorized'
'422':
$ref: '#/components/responses/422InvalidParameters'
'429':
$ref: '#/components/responses/429TooManyRequests'
'500':
$ref: '#/components/responses/500InternalServerError'
components:
responses:
422InvalidParameters:
description: Invalid Parameters
headers:
Getpaid-Trace-Id:
$ref: '#/components/headers/GetpaidTraceId'
content:
application/problem+json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetailsBase'
- type: object
required:
- errors
properties:
errors:
type: object
description: The JSON path of any request body fields or header names that are invalid with a description of the error
additionalProperties:
type: array
items:
type: string
example:
currency:
- invalid_option
type:
example: https://docs.getpaid.io/integration/api/responses#422---invalid-parameters
title:
example: Invalid Parameters
status:
example: 422
500InternalServerError:
description: Internal Server Error
headers:
Getpaid-Trace-Id:
$ref: '#/components/headers/GetpaidTraceId'
429TooManyRequests:
description: Too Many Requests
headers:
Getpaid-Trace-Id:
$ref: '#/components/headers/GetpaidTraceId'
401Unauthorized:
description: Unauthorized
headers:
Getpaid-Trace-Id:
$ref: '#/components/headers/GetpaidTraceId'
400BadRequest:
description: Bad Request
headers:
Getpaid-Trace-Id:
$ref: '#/components/headers/GetpaidTraceId'
schemas:
PaymentId:
allOf:
- $ref: '#/components/schemas/Id'
- description: The unique identifier of the payment.
example: pay_4a4m2pjycdb1jbj68h1rvk9kcz
PaymentMethodBase:
type: object
required:
- type
properties:
type:
$ref: '#/components/schemas/PaymentMethodType'
QueryPaymentsResponse:
allOf:
- required:
- type
properties:
type:
type: string
enum:
- payments
cursor:
type: string
data:
items:
required:
- id
- reference
- status
- amount
- currency
- created_at
- updated_at
- method
- seller
- parties
properties:
id:
$ref: '#/components/schemas/PaymentId'
reference:
$ref: '#/components/schemas/Reference'
status:
$ref: '#/components/schemas/PaymentStatus'
amount:
$ref: '#/components/schemas/AmountMinor'
currency:
$ref: '#/components/schemas/Currency'
created_at:
$ref: '#/components/schemas/CreatedAt'
updated_at:
$ref: '#/components/schemas/UpdatedAt'
method:
$ref: '#/components/schemas/PaymentMethodHint'
seller:
$ref: '#/components/schemas/SellerRef'
parties:
description: The list of parties involved in the transaction.
type: array
minItems: 1
items:
$ref: '#/components/schemas/PartyRef'
- $ref: '#/components/schemas/PaginatedResponse'
BasePaymentMethodHint:
allOf:
- $ref: '#/components/schemas/PaymentMethodBase'
- required:
- display_hint
properties:
display_hint:
$ref: '#/components/schemas/PaymentMethodDisplayHint'
Reference:
allOf:
- $ref: '#/components/schemas/ShortString'
- description: An identifier in your system. It is recommended to make it unique but the uniqueness is not enforced by the solution.
example: ORD-202510-0232
QueryPaymentMethodHint:
description: The payment method used in a checkout.
type: object
required:
- type
properties:
type:
description: The type of payment method.
type: string
enum:
- card
- sepa_direct_debit
scheme:
description: The scheme of the payment method (e.g., visa, mastercard).
type: string
PaginationData:
description: The list of queried elements.
type: array
items:
type: object
AccountId:
allOf:
- $ref: '#/components/schemas/Id'
- description: The unique identifier of the account.
example: acc_44678r08jtm8zbt227tzhc4nw5
QueriesResourceType:
description: 'The type of the Getpaid solution resources to get analytics from:
- `checkouts`
- `payments`
'
type: string
enum:
- checkouts
- payments
QueryResourcesResponse:
oneOf:
- $ref: '#/components/schemas/QueryCheckoutsResponse'
- $ref: '#/components/schemas/QueryPaymentsResponse'
discriminator:
propertyName: type
mapping:
checkouts: '#/components/schemas/QueryCheckoutsResponse'
payments: '#/components/schemas/QueryPaymentsResponse'
Currency:
type: string
format: currency
minLength: 3
maxLength: 3
description: The processing currency code according to the [ISO-4217 standard](https://en.wikipedia.org/wiki/ISO_4217)
example: EUR
PaymentMethodDisplayHint:
allOf:
- description: A hint of the payment method used.
- $ref: '#/components/schemas/ShortString'
MediumString:
type: string
minLength: 1
maxLength: 250
PaginationFirst:
description: Pagination. The number of elements that will be retrieved.
type: integer
default: 20
minimum: 1
maximum: 100
AmountMinor:
type: integer
format: amount-minor
description: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR).
example: 1000
CheckoutsSortsRequest:
description: Fields to sort the data by. If not set, the data will be sorted by the creation date descending.
type: array
minItems: 1
uniqueItems: true
items:
allOf:
- $ref: '#/components/schemas/BaseSortItemRequest'
- properties:
field:
enum:
- created_at
- amount
- seller_legal_name
PaymentMethodType:
description: The type of payment method.
type: string
enum:
- card
- sepa_direct_debit
QueryCheckoutsRequest:
allOf:
- $ref: '#/components/schemas/BaseQueryRequest'
- required:
- type
properties:
type:
type: string
enum:
- checkouts
filters:
$ref: '#/components/schemas/CheckoutsFiltersRequest'
sorts:
$ref: '#/components/schemas/CheckoutsSortsRequest'
AccountLegalName:
allOf:
- description: The legal name of the account.
- $ref: '#/components/schemas/MediumString'
DateTime:
description: 'UTC timestamp in ISO 8601 format with milliseconds ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)).
Always includes the ''Z'' UTC indicator.
'
type: string
format: date-time
minLength: 24
maxLength: 24
example: '2025-09-01T22:05:48.479Z'
PaginatedResponse:
type: object
required:
- data
properties:
cursor:
$ref: '#/components/schemas/PaginationCursor'
data:
$ref: '#/components/schemas/PaginationData'
QueryCheckoutsResponse:
allOf:
- required:
- type
properties:
type:
type: string
enum:
- checkouts
cursor:
type: string
data:
items:
required:
- id
- reference
- status
- amount
- currency
- created_at
- updated_at
- expires_at
- payment_methods
- seller
- parties
properties:
id:
$ref: '#/components/schemas/CheckoutId'
reference:
$ref: '#/components/schemas/Reference'
status:
$ref: '#/components/schemas/CheckoutStatus'
amount:
$ref: '#/components/schemas/AmountMinor'
currency:
$ref: '#/components/schemas/Currency'
created_at:
$ref: '#/components/schemas/CreatedAt'
updated_at:
$ref: '#/components/schemas/UpdatedAt'
expires_at:
$ref: '#/components/schemas/CheckoutExpiresAt'
payment_methods:
description: The list of payment methods available in the checkout.
type: array
minItems: 1
items:
$ref: '#/components/schemas/QueryPaymentMethodHint'
seller:
$ref: '#/components/schemas/SellerRef'
parties:
description: The list of parties involved in the transaction.
type: array
minItems: 1
items:
$ref: '#/components/schemas/PartyRef'
- $ref: '#/components/schemas/PaginatedResponse'
QueryPaymentsRequest:
allOf:
- $ref: '#/components/schemas/BaseQueryRequest'
- required:
- type
properties:
type:
type: string
enum:
- payments
filters:
$ref: '#/components/schemas/PaymentsFiltersRequest'
sorts:
$ref: '#/components/schemas/PaymentsSortsRequest'
CheckoutStatus:
description: 'The status of the checkout.
See the [list, transitions, and description of each status](/payments/checkouts#lifecycle) for more details.
'
type: string
enum:
- initiated
- started
- in_progress
- completed
- failed
- expired
BaseQueryRequest:
type: object
properties:
type:
description: 'The type of the Getpaid solution resources to query.
Some query endpoints infer the resource type from the request path. In those cases, if this field is set, it
must match the resource targeted by the request URL.
'
type: string
first:
allOf:
- $ref: '#/components/schemas/PaginationFirst'
after:
$ref: '#/components/schemas/PaginationAfter'
filters:
description: Filters to reduce the data set to query. If not set, all resources available of the given type will be queried.
sorts:
$ref: '#/components/schemas/BaseSortsRequest'
PartyRef:
description: A reference to a party account involved in the transaction.
type: object
required:
- id
- type
- legal_name
properties:
id:
$ref: '#/components/schemas/AccountId'
type:
description: The type of party.
type: string
enum:
- platform
- other
legal_name:
$ref: '#/components/schemas/AccountLegalName'
CreatedAt:
allOf:
- description: When the resource was created.
- $ref: '#/components/schemas/DateTime'
PaginationCursor:
description: The cursor to the last item. If non-empty, can be used to fetch the next page. If not set, there is no more elements.
type: string
maxLength: 250
example: Q3VyaW9zaXR5IEtpbGxlZCB0aGUgQ2F0Cg==
UpdatedAt:
allOf:
- description: When the resource was last updated.
- $ref: '#/components/schemas/DateTime'
PaymentsSortsRequest:
description: Fields to sort the data by. If not set, the data will be sorted by the creation date descending.
type: array
minItems: 1
uniqueItems: true
items:
allOf:
- $ref: '#/components/schemas/BaseSortItemRequest'
- properties:
field:
enum:
- created_at
- amount
- seller_legal_name
PaginationAfter:
description: Pagination. The `cursor` from next page will be retrieved.
type: string
maxLength: 250
CardScheme:
description: The card scheme.
type: string
enum:
- visa
- mastercard
Id:
type: string
format: id
minLength: 30
maxLength: 50
CardPaymentMethodHint:
allOf:
- required:
- scheme
properties:
type:
type: string
scheme:
$ref: '#/components/schemas/CardScheme'
- $ref: '#/components/schemas/BasePaymentMethodHint'
BaseSortItemRequest:
description: Each field to sort by.
type: object
required:
- field
- direction
properties:
field:
description: The field to sort by. Each field available can only be used once in the list.
type: string
direction:
description: The sort direction
type: string
enum:
- ascending
- descending
ShortString:
type: string
minLength: 1
maxLength: 50
CheckoutExpiresAt:
allOf:
- description: When the checkout session will expire if not completed.
- $ref: '#/components/schemas/DateTime'
PaymentMethodHint:
description: The payment method used.
oneOf:
- $ref: '#/components/schemas/BasePaymentMethodHint'
- $ref: '#/components/schemas/CardPaymentMethodHint'
discriminator:
propertyName: type
mapping:
card: '#/components/schemas/CardPaymentMethodHint'
sepa_direct_debit: '#/components/schemas/BasePaymentMethodHint'
PaymentsFiltersRequest:
description: Filtering payments.
type: object
properties:
id:
allOf:
- description: The payment identifier to filter by using an exact match operation.
- $ref: '#/components/schemas/PaymentId'
reference:
description: The payment reference to filter by using a contains operation.
type: string
seller_legal_name:
description: The seller legal name to filter by using a contains operation.
type: string
statuses:
description: The list of payment statuses to filter by.
type: array
minItems: 1
uniqueItems: true
items:
$ref: '#/components/schemas/PaymentStatus'
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
SellerRef:
description: A reference to the seller account.
type: object
required:
- id
- legal_name
properties:
id:
$ref: '#/components/schemas/AccountId'
legal_name:
$ref: '#/components/schemas/AccountLegalName'
CheckoutsFiltersRequest:
description: Filtering checkouts.
type: object
properties:
id:
allOf:
- description: The checkout identifier to filter by using an exact match operation.
- $ref: '#/components/schemas/CheckoutId'
reference:
description: The checkout reference to filter by using a contains operation.
type: string
seller_legal_name:
description: The seller legal name to filter by using a contains operation.
type: string
statuses:
description: The list of checkout statuses to filter by.
type: array
minItems: 1
uniqueItems: true
items:
$ref: '#/components/schemas/CheckoutStatus'
CheckoutId:
allOf:
- $ref: '#/components/schemas/Id'
- description: The unique identifier of the checkout.
example: cko_4kf9v6xp00hzc99rdwr5m97wce
BaseSortsRequest:
description: Fields to sort the data by. If not set, the data will be sorted by the creation date descending.
type: array
minItems: 1
uniqueItems: true
items:
description: Each field to sort by.
type: object
required:
- field
- direction
properties:
field:
description: The field to sort by. Each field available can only be used once in the list.
type: string
direction:
description: The sort direction
type: string
enum:
- ascending
- descending
PaymentStatus:
description: 'The status of the payment.
See the [list, transitions, and description of each status](/payments/lifecycle) for more details.
'
type: string
enum:
- initiated
- action_required
- submitted
- authorized
- captured
- declined
- failed
- partially_refunded
- refunded
QueryResourcesRequest:
oneOf:
- $ref: '#/components/schemas/QueryCheckoutsRequest'
- $ref: '#/components/schemas/QueryPaymentsRequest'
discriminator:
propertyName: type
mapping:
checkouts: '#/components/schemas/QueryCheckoutsRequest'
payments: '#/components/schemas/QueryPaymentsRequest'
examples:
FilteredPayments:
summary: Filtered payments
value:
type: payments
cursor: Q3VyaW9zaXR5IEtpbGxlZCB0aGUgQ2F0Cg==
data:
- id: pay_4y7kptsvn11qq6d354g5tx735v
reference: ORD-202510-0232
status: captured
amount: 1000
currency: EUR
created_at: '2023-03-15T12:34:56.999Z'
updated_at: '2023-03-15T12:34:56.999Z'
method:
type: card
scheme: visa
display_hint: 424242******4242
seller:
id: acc_44678r08jtm8zbt227tzhc4nw5
legal_name: Titan Biking
parties:
- id: acc_5y789s19kum9act338uaic5ox6
type: platform
legal_name: Titan Auto Parts GmbH
- id: pay_4y7kptsvn11qq6d354g5tx736w
reference: ORD-202511-0133
status: captured
amount: 1000
currency: EUR
created_at: '2023-03-15T12:34:56.999Z'
updated_at: '2023-03-15T12:34:56.999Z'
method:
type: card
scheme: visa
display_hint: 411111******1111
seller:
id: acc_44678r08jtm8zbt227tzhc4nw5
legal_name: Titan Biking
parties:
- id: acc_5y789s19kum9act338uaic5ox6
type: platform
legal_name: Titan Auto Parts GmbH
QueryPayments:
summary: Query payments
value:
type: payments
filters:
seller_legal_name: Titan Biking
statuses:
- captured
FilteredCheckouts:
summary: Filtered checkouts
value:
type: checkouts
cursor: Q3VyaW9zaXR5IEtpbGxlZCB0aGUgQ2F0Cg==
data:
- id: chk_4y7kptsvn11qq6d354g5tx735v
reference: ORD-202510-0232
status: expired
amount: 1000
currency: EUR
created_at: '2023-03-15T12:34:56.999Z'
updated_at: '2023-03-15T12:35:56.999Z'
expires_at: '2023-03-15T13:34:56.999Z'
payment_methods:
- type: card
scheme: visa
- type: card
scheme: mastercard
- type: sepa_direct_debit
seller:
id: acc_44678r08jtm8zbt227tzhc4nw5
legal_name: Titan Biking
parties:
- id: acc_5y789s19kum9act338uaic5ox6
type: platform
legal_name: Titan Auto Parts GmbH
- id: chk_4y7kptsvn11qq6d354g5tx736w
reference: ORD-202511-0133
status: failed
amount: 1000
currency: EUR
created_at: '2023-03-16T10:20:30.999Z'
updated_at: '2023-03-16T10:22:45.999Z'
expires_at: '2023-03-16T11:20:30.999Z'
payment_methods:
- type: card
scheme: visa
- type: sepa_direct_debit
seller:
id: acc_44678r08jtm8zbt227tzhc4nw5
legal_name: Titan Biking
parties:
- id: acc_5y789s19kum9act338uaic5ox6
type: platform
legal_name: Titan Auto Parts GmbH
QueryCheckouts:
summary: Query checkouts
value:
type: checkouts
filters:
seller_legal_name: Titan Biking
statuses:
- expired
- failed
QueryNext20Payments:
summary: Query next 20 payments
value:
type: payments
after: Q3VyaW9zaXR5IEtpbGxlZCB0aGUgQ2F0Cg==
first: 20
filters:
seller_legal_name: Titan Biking
statuses:
- captured
headers:
GetpaidTraceId:
description: The trace identifier for the request. It is a good idea to log this and provide it with any support requests
schema:
type: string
example: 96ce50247f87f540bb2d86771b3728b8
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