GEgetpaid
Checkouts

Create a checkout

Create a payment checkout session.

Related webhooks:

  • checkout_completed: sent when the checkout process is completed with a successful payment.
  • checkout_failed: sent when the checkout lifetime is reached without a successful payment attempt, and at least one payment was attempted but none were successful.
  • checkout_in_progress: sent when the checkout lifetime reaches its expiration, but a payment attempt is still in progress.
  • checkout_unattempted: sent when the checkout lifetime is reached without a payment.
  • 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.
post/v2/checkouts

Request

Headers

Getpaid-Idempotency-Keystring required
Example:5c255194-30ec-11ed-a261-0242ac120002

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

Request body

referencestring required

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

amountinteger required

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

currencystring currency required

The processing currency code according to the ISO-4217 standard

descriptionstring required

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.

expires_instring time-span

Duration in [d.]hh:mm[:ss] notation. Days and seconds optional, all segments non-negative.

Hours above 23 are supported but not recommended. Excess hours roll over into the days component; for example, 1.720:00 represents 31 days.

Example request

{
  "reference": "ORD-202510-0232",
  "amount": 1000,
  "currency": "EUR",
  "description": "Order 202510-0232",
  "expires_in": "1.12:00",
  "payment_methods": {
    "options": {
      "cards": {
        "dynamic_descriptor": "TITAN*202510-0232"
      },
      "sepa_direct_debit": {
        "remittance_info": "Titan Auto Parts Ord. #0232 Inv. #202500632"
      }
    }
  },
  "splits": {
    "accounts": [
      {
        "id": "acc_44678r08jtm8zbt227tzhc4nw5",
        "split": {
          "amount": 1000
        },
        "processing_fee": {
          "percentage": 100
        }
      }
    ]
  },
  "buyer": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@company.com",
    "address": {
      "line1": "Immermannstraße",
      "line2": "Haus 2, Wohnung 3A",
      "street_number": "40",
      "city": "Düsseldorf",
      "region": "Nordrhein-Westfalen",
      "postal_code": "40210",
      "country": "DE"
    },
    "birth": {
      "date": "2023-09-01",
      "place": "Düsseldorf"
    },
    "nationality": "DE",
    "business": {
      "legal_name": "Motorbikes Düsseldorf GmbH",
      "country": "DE",
      "registration_number": {
        "type": "vat",
        "value": "DE123456789"
      }
    }
  },
  "redirect": {
    "default": "https://titanauto.com/checkout/complete?order=202510-0232",
    "completed": "https://titanauto.com/checkout/complete?order=202510-0232",
    "failed": "https://titanauto.com/checkout/payment-failed?order=202510-0232"
  },
  "integration": {
    "site_url": "https://shop.titanauto.com"
  },
  "webhooks": {
    "url": "https://webhooks.titanauto.com/getpaid"
  }
}

Response

Created

idstring id required

The unique identifier of the checkout.

status'initiated' | 'started' | 'in_progress' | 'completed' | 'failed' | 'unattempted' required

The status of the checkout. See the list, transitions, and description of each status for more details.

referencestring required

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

created_atstring date-time required

UTC timestamp in ISO 8601 format with milliseconds (RFC 3339). Always includes the 'Z' UTC indicator.

updated_atstring date-time required

UTC timestamp in ISO 8601 format with milliseconds (RFC 3339). Always includes the 'Z' UTC indicator.

expires_atstring date-time required

UTC timestamp in ISO 8601 format with milliseconds (RFC 3339). Always includes the 'Z' UTC indicator.

Example response

{
  "id": "cko_4kf9v6xp00hzc99rdwr5m97wce",
  "reference": "ORD-202510-0232",
  "created_at": "2025-09-01T22:05:48.479Z",
  "updated_at": "2025-09-01T22:05:48.479Z",
  "expires_at": "2025-09-01T22:05:48.479Z",
  "splits": {
    "accounts": [
      {
        "id": "acc_44678r08jtm8zbt227tzhc4nw5",
        "version": "2",
        "split": {
          "amount": 1000
        },
        "processing_fee": {
          "percentage": 100
        }
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.