GetPaid Accept payments webhooks API
Webhooks related to accepting payment events.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/getpaid-accept-payments-webhooks-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.2.0
info:
title: Getpaid Accept payments webhooks 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: Accept payments webhooks
description: Webhooks related to accepting payment events.
paths: {}
webhooks:
checkout_completed:
post:
summary: checkout_completed
operationId: checkout_completed
description: The `checkout_completed` webhook is sent when the checkout process is completed with a successful payment.
tags:
- Accept payments webhooks
security: []
parameters:
- $ref: '#/components/parameters/GetpaidTraceId'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/WebhookBaseRequest'
- properties:
type:
const: checkout_completed
data:
type: object
required:
- id
- origin
- reference
- payment
properties:
id:
$ref: '#/components/schemas/CheckoutId'
origin:
$ref: '#/components/schemas/PaymentOrigin'
reference:
$ref: '#/components/schemas/Reference'
payment:
description: The successful payment associated with the completed checkout.
type: object
required:
- id
properties:
id:
$ref: '#/components/schemas/PaymentId'
standing_instruction:
description: The standing instruction associated with the payment, if the payment is the first of a recurring series.
required:
- id
- status
properties:
id:
$ref: '#/components/schemas/StandingInstructionId'
status:
allOf:
- $ref: '#/components/schemas/StandingInstructionStatus'
- const: active
example: active
responses:
'429':
description: The webhook action will be retried according to the workflow retry schedule
2XX:
description: Indicate success, the webhook will not be retried
4XX:
description: The webhook action will be disabled
5XX:
description: The webhook action will be retried according to the workflow retry schedule
checkout_failed:
post:
summary: checkout_failed
operationId: checkout_failed
description: '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.
'
tags:
- Accept payments webhooks
security: []
parameters:
- $ref: '#/components/parameters/GetpaidTraceId'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/WebhookBaseRequest'
- properties:
type:
const: checkout_failed
data:
type: object
required:
- id
- origin
- reference
- payment
properties:
id:
$ref: '#/components/schemas/CheckoutId'
origin:
$ref: '#/components/schemas/PaymentOrigin'
reference:
$ref: '#/components/schemas/Reference'
payment:
allOf:
- $ref: '#/components/schemas/WebhookCheckoutPayment'
- description: The last payment failed associated with the checkout.
responses:
'429':
description: The webhook action will be retried according to the workflow retry schedule
2XX:
description: Indicate success, the webhook will not be retried
4XX:
description: The webhook action will be disabled
5XX:
description: The webhook action will be retried according to the workflow retry schedule
checkout_in_progress:
post:
summary: checkout_in_progress
operationId: checkout_in_progress
description: '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.
'
tags:
- Accept payments webhooks
security: []
parameters:
- $ref: '#/components/parameters/GetpaidTraceId'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/WebhookBaseRequest'
- properties:
type:
const: checkout_in_progress
data:
type: object
required:
- id
- origin
- reference
- payment
properties:
id:
$ref: '#/components/schemas/CheckoutId'
origin:
$ref: '#/components/schemas/PaymentOrigin'
reference:
$ref: '#/components/schemas/Reference'
payment:
allOf:
- $ref: '#/components/schemas/WebhookCheckoutPayment'
- description: The payment in progress pending to be confirmed its final status and associated with the checkout.
type: object
properties:
estimated_update_before:
description: The estimated UTC datetime before which the payment status is expected to be updated.
allOf:
- $ref: '#/components/schemas/DateTime'
responses:
'429':
description: The webhook action will be retried according to the workflow retry schedule
2XX:
description: Indicate success, the webhook will not be retried
4XX:
description: The webhook action will be disabled
5XX:
description: The webhook action will be retried according to the workflow retry schedule
checkout_unattempted:
post:
summary: checkout_unattempted
operationId: checkout_unattempted
description: 'The `checkout_unattempted` webhook is sent when the checkout lifetime is reached without a payment.
'
tags:
- Accept payments webhooks
security: []
parameters:
- $ref: '#/components/parameters/GetpaidTraceId'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/WebhookBaseRequest'
- properties:
type:
const: checkout_unattempted
data:
type: object
required:
- id
- origin
- reference
properties:
id:
$ref: '#/components/schemas/CheckoutId'
origin:
$ref: '#/components/schemas/PaymentOrigin'
reference:
$ref: '#/components/schemas/Reference'
responses:
'429':
description: The webhook action will be retried according to the workflow retry schedule
2XX:
description: Indicate success, the webhook will not be retried
4XX:
description: The webhook action will be disabled
5XX:
description: The webhook action will be retried according to the workflow retry schedule
payment_captured:
post:
summary: payment_captured
operationId: payment_captured
description: The `payment_captured` webhook is sent when a payment is successfully captured and the funds are secured for the seller.
tags:
- Accept payments webhooks
security: []
parameters:
- $ref: '#/components/parameters/GetpaidTraceId'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/WebhookBaseRequest'
- properties:
type:
const: payment_captured
data:
type: object
required:
- id
- origin
- reference
- capture_id
properties:
id:
$ref: '#/components/schemas/PaymentId'
origin:
$ref: '#/components/schemas/PaymentOrigin'
reference:
$ref: '#/components/schemas/Reference'
capture_id:
$ref: '#/components/schemas/CaptureId'
responses:
'429':
description: The webhook action will be retried according to the workflow retry schedule
2XX:
description: Indicate success, the webhook will not be retried
4XX:
description: The webhook action will be disabled
5XX:
description: The webhook action will be retried according to the workflow retry schedule
payment_failed:
post:
summary: payment_failed
operationId: payment_failed
description: The `payment_failed` webhook is sent when a payment fails due to business (decline) or technical issues.
tags:
- Accept payments webhooks
security: []
parameters:
- $ref: '#/components/parameters/GetpaidTraceId'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/WebhookBaseRequest'
- properties:
type:
const: payment_failed
data:
type: object
required:
- id
- origin
- reference
- status
properties:
id:
$ref: '#/components/schemas/PaymentId'
origin:
$ref: '#/components/schemas/PaymentOrigin'
reference:
$ref: '#/components/schemas/Reference'
status:
allOf:
- $ref: '#/components/schemas/PaymentStatus'
- example: failed
responses:
'429':
description: The webhook action will be retried according to the workflow retry schedule
2XX:
description: Indicate success, the webhook will not be retried
4XX:
description: The webhook action will be disabled
5XX:
description: The webhook action will be retried according to the workflow retry schedule
payment_refunded:
post:
summary: payment_refunded
operationId: payment_refunded
description: The `payment_refunded` webhook is sent when a refund is successfully completed and the funds have been returned to the buyer.
tags:
- Accept payments webhooks
security: []
parameters:
- $ref: '#/components/parameters/GetpaidTraceId'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/WebhookBaseRequest'
- properties:
type:
const: payment_refunded
data:
type: object
required:
- id
- origin
- reference
- refund
properties:
id:
$ref: '#/components/schemas/PaymentId'
origin:
$ref: '#/components/schemas/PaymentOrigin'
reference:
$ref: '#/components/schemas/Reference'
refund:
description: The refund details.
type: object
required:
- id
- reference
properties:
id:
$ref: '#/components/schemas/RefundId'
reference:
allOf:
- $ref: '#/components/schemas/Reference'
- example: RFD-202510-0002
responses:
'429':
description: The webhook action will be retried according to the workflow retry schedule
2XX:
description: Indicate success, the webhook will not be retried
4XX:
description: The webhook action will be disabled
5XX:
description: The webhook action will be retried according to the workflow retry schedule
payment_refund_failed:
post:
summary: payment_refund_failed
operationId: payment_refund_failed
description: The `payment_refund_failed` webhook is sent when a refund has failed.
tags:
- Accept payments webhooks
security: []
parameters:
- $ref: '#/components/parameters/GetpaidTraceId'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/WebhookBaseRequest'
- properties:
type:
const: payment_refund_failed
data:
type: object
required:
- id
- origin
- reference
- refund
properties:
id:
$ref: '#/components/schemas/PaymentId'
origin:
$ref: '#/components/schemas/PaymentOrigin'
reference:
$ref: '#/components/schemas/Reference'
refund:
description: The refund details.
type: object
required:
- id
- reference
properties:
id:
$ref: '#/components/schemas/RefundId'
reference:
allOf:
- $ref: '#/components/schemas/Reference'
- example: RFD-202510-0002
responses:
'429':
description: The webhook action will be retried according to the workflow retry schedule
2XX:
description: Indicate success, the webhook will not be retried
4XX:
description: The webhook action will be disabled
5XX:
description: The webhook action will be retried according to the workflow retry schedule
components:
schemas:
StandingInstructionStatus:
description: 'The status of the standing instruction.
- `new`: requested to creation as part of an initial payment.
- `active`: standing instruction is active and can be used for subsequent payments.
'
type: string
enum:
- new
- active
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
Id:
type: string
format: id
minLength: 30
maxLength: 50
CheckoutId:
allOf:
- $ref: '#/components/schemas/Id'
- description: The unique identifier of the checkout.
example: cko_4kf9v6xp00hzc99rdwr5m97wce
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
PaymentOriginApi:
allOf:
- $ref: '#/components/schemas/PaymentOriginBase'
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'
PaymentMethodType:
description: The type of payment method.
type: string
enum:
- card
- sepa_direct_debit
PaymentOriginBase:
type: object
required:
- type
properties:
type:
description: 'The payment origin type.
- `api`: The payment was created via the API.
- `checkout`: The payment was created as an attempt of a checkout session.
'
type: string
enum:
- api
- checkout
ShortString:
type: string
minLength: 1
maxLength: 50
StandingInstructionId:
allOf:
- $ref: '#/components/schemas/Id'
- description: The unique identifier of the standing instruction.
example: sti_4tbftjwzxja1h71nzas1g0g1xm
WebhookCheckoutPayment:
type: object
required:
- id
- method
properties:
id:
$ref: '#/components/schemas/PaymentId'
method:
description: The payment method used.
type: object
required:
- type
properties:
type:
$ref: '#/components/schemas/PaymentMethodType'
PaymentOrigin:
description: The origin of the payment creation.
allOf:
- $ref: '#/components/schemas/PaymentOriginApi'
- $ref: '#/components/schemas/PaymentOriginCheckout'
discriminator:
propertyName: type
mapping:
api: '#/components/schemas/PaymentOriginApi'
checkout: '#/components/schemas/PaymentOriginCheckout'
RefundId:
allOf:
- $ref: '#/components/schemas/Id'
- description: The unique identifier of the refund of a payment.
example: rfd_4a4m2pjycdb1jbj68h1rvk9kcz
EventId:
allOf:
- $ref: '#/components/schemas/Id'
- description: The unique identifier of the event.
example: evt_4a4m2pjycdb1jbj68h1rvk9kcz
PaymentOriginCheckout:
allOf:
- $ref: '#/components/schemas/PaymentOriginBase'
- required:
- id
properties:
id:
$ref: '#/components/schemas/CheckoutId'
PaymentId:
allOf:
- $ref: '#/components/schemas/Id'
- description: The unique identifier of the payment.
example: pay_4a4m2pjycdb1jbj68h1rvk9kcz
CaptureId:
allOf:
- $ref: '#/components/schemas/Id'
- description: The unique identifier of a capture
example: cpt_57fm2pjycji1jbj68h1rvk9bnc
WebhookBaseRequest:
type: object
required:
- id
- type
- version
- occurred_at
- data
properties:
id:
$ref: '#/components/schemas/EventId'
type:
description: The type of event.
type: string
version:
description: The version of the event type.
type: string
const: v2
example: v2
occurred_at:
$ref: '#/components/schemas/DateTime'
description: The UTC date and time at which the event occurred.
data:
description: The event data specific to each event type and version.
type: object
parameters:
GetpaidTraceId:
name: Getpaid-Trace-Id
in: header
description: The trace identifier for the request. It is a good idea to log this and provide it with any support requests
required: true
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