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