---
title: "Create a checkout"
method: POST
path: "/v2/checkouts"
tags: ["Checkouts"]
---

# Create a checkout

`POST /v2/checkouts`

## Request

- Base URL: `https://api.getpaid.io`
- URL: `https://api.getpaid.io/v2/checkouts`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://auth.getpaid.io/oauth/token` scopes: `payments:read_write`
- TypeScript: <https://skmtc.dev/getpaid/apis/getpaid-api/docs/v2/checkouts/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a payment checkout session.

Related webhooks:

- [`checkout_completed`](#tag/Accept-payments-webhooks/operation/checkout_completed): sent when the checkout process is completed with a successful payment.
- [`checkout_failed`](#tag/Accept-payments-webhooks/operation/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`](#tag/Accept-payments-webhooks/operation/checkout_in_progress): sent when the checkout lifetime reaches its expiration, but a payment attempt is still in progress.
- [`checkout_unattempted`](#tag/Accept-payments-webhooks/operation/checkout_unattempted): sent when the checkout lifetime is reached without a payment.
- For each payment attempt:
  - [`payment_captured`](#tag/Accept-payments-webhooks/operation/payment_captured): sent when the payment funds are captured and secured.
  - [`payment_failed`](#tag/Accept-payments-webhooks/operation/payment_failed): sent when a payment fails due to business (decline) or technical issues.

## Headers

- `Getpaid-Idempotency-Key` string, required

## Request body

- CreateCheckoutRequest
  - `reference` string, required: An identifier in your system. It is recommended to make it unique but the uniqueness is not enforced by the solution.
  - `amount` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR).
  - `currency` string, currency, required: The processing currency code according to the [ISO-4217 standard](https://en.wikipedia.org/wiki/ISO_4217)
  - `description` string, 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_in` string, 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.
  - `payment_methods` union: Configure payment methods for the checkout. - `explicit`: use `available` to provide the methods to display. - `default`: all available payment methods are selected automatically.
    - CheckoutExplicitPaymentMethodsRequest
      - `type` string, required: The available payment methods selection method.
      - `available` PaymentMethodDescriptor[], required: The list of payment methods to display in the checkout overriding the default methods.
        - union: A payment method.
          - PaymentMethodBase
            - `type` 'card' | 'sepa_direct_debit', required: The type of payment method.
          - CardPaymentMethodDescriptor
            - `type` 'card' | 'sepa_direct_debit', required: The type of payment method.
            - `scheme` 'visa' | 'mastercard', required: The card scheme.
      - `options` CheckoutPaymentMethodsOptions: Configuration options for the payment methods available in the checkout.
        - `cards` CheckoutCardPaymentMethodOptions: Configuration options for card payment methods in the checkout.
          - `dynamic_descriptor` string, required: The card dynamic descriptor. It will be prefixed with `GPD*` when displayed on the buyer statement. You don't need to include the `GPD*` prefix in the value sent.
        - `sepa_direct_debit` CheckoutSepaDirectDebitPaymentMethodOptions: Configuration options for SEPA Direct Debit payment methods in the checkout.
          - `remittance_info` string, required: The SEPA Direct Debit remittance information shown on the buyer statement.
    - CheckoutDefaultPaymentMethodsRequest
      - `type` string, required: The available payment methods selection method.
      - `options` CheckoutPaymentMethodsOptions: Configuration options for the payment methods available in the checkout.
        - `cards` CheckoutCardPaymentMethodOptions: Configuration options for card payment methods in the checkout.
          - `dynamic_descriptor` string, required: The card dynamic descriptor. It will be prefixed with `GPD*` when displayed on the buyer statement. You don't need to include the `GPD*` prefix in the value sent.
        - `sepa_direct_debit` CheckoutSepaDirectDebitPaymentMethodOptions: Configuration options for SEPA Direct Debit payment methods in the checkout.
          - `remittance_info` string, required: The SEPA Direct Debit remittance information shown on the buyer statement.
  - `splits` SplitsRequest, required: The list of payment splits for the accounts involved in the funds flow. See [how splits work](/monetize/splits) for more information.
    - `type` 'per_transaction', required: The type of payment split.
    - `accounts` object[], required: The list of accounts involved in the payment that will receive the funds.
      - `type` 'platform' | 'seller' | 'other', required: The type of account. Exactly one of type `seller` is required and allowed per payment.
      - `id` string, id, required: The unique identifier of the account.
      - `split` union, required: The amount in the payment currency to be allocated to this account.
        - SplitFixedAmount: The amount in payment currency to be allocated to this account. The sum of all split amounts for all accounts must be exactly the total amount of the payment or use the `remaining` type for one of the accounts to allocate the remaining amount after all other splits have been calculated.
          - `type` 'fixed' | 'percentage' | 'remaining', required: The type of split amount.
          - `amount` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR).
        - SplitPercentageAmountRequest: The amount in payment currency to be allocated to this account. The sum of all split amounts for all accounts must be exactly the total amount of the payment or use the `remaining` type for one of the accounts to allocate the remaining amount after all other splits have been calculated.
          - `type` 'fixed' | 'percentage' | 'remaining', required: The type of split amount.
          - `percentage` number, float, required: The percentage of the total amount to allocate to this account.
        - SplitRemainingAmountRequest: The amount in payment currency to be allocated to this account. The sum of all split amounts for all accounts must be exactly the total amount of the payment or use the `remaining` type for one of the accounts to allocate the remaining amount after all other splits have been calculated.
          - `type` 'fixed' | 'percentage' | 'remaining', required: The type of split amount.
      - `processing_fee` ProcessingFeeRequest: The processing fee covered by this account. If not specified, the account will not cover any processing fee, except when the payment has exactly one seller account and that seller is the authenticated platform account. In that platform-as-seller case, the API defaults the missing processing fee to 100%. The sum of all processing fees covered by all accounts must be exactly 100%.
        - `percentage` number, float, required: The percentage of the total processing fee that this account will cover.
  - `buyer` CheckoutBuyerRequest: Buyer details to pre-fill during checkout. **Required if the country of the seller account is Canada (CA).**
    - `first_name` string: The buyer's first name.
    - `last_name` string: The buyer's last name.
    - `email` string, email: An email address.
    - `address` CheckoutBuyerAddress: The buyer's address. **Required if the country of the seller account is Canada (CA).**
      - `line1` string: The first line of the address.
      - `line2` string: The second line of the address.
      - `street_number` string: The number assigned to the building on the street. May include alphanumeric formatting such as "7A" or "12-14". street number.
      - `city` string: The city, town, municipality, or locality where the address is located.
      - `region` string: The administrative area such as region, province, state, or county.
      - `postal_code` string: The postal code, postcode, or ZIP code used for mail delivery.
      - `country` string, country: The two-letter [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
    - `birth` object: The buyer's birth details.
      - `date` string, date: The buyer's date of birth.
      - `place` string: The buyer's town or city of birth.
    - `nationality` string, country: The two-letter [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
    - `business` object: The buyer's business details.
      - `legal_name` string: The legal name of the business.
      - `country` string, country: The two-letter [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
      - `registration_number` union: The business' registration number. The registration number is validated based on the country of the business.
        - BaseRegistrationNumber: The company registration number.
          - `type` string, required: The type of registration number. See the list of supported [registration numbers per country](/integration/api/references/registration-numbers).
          - `value` string, required: The registration number. See the format for each registration number type in the [registration numbers list](/integration/api/references/registration-numbers).
        - GermanRegistrationNumber: The company registration number.
          - `type` string, required: The type of registration number. See the list of supported [registration numbers per country](/integration/api/references/registration-numbers).
          - `value` string, required: The registration number. See the format for each registration number type in the [registration numbers list](/integration/api/references/registration-numbers).
          - `registry` string, required: The Germany district court where the business is registered. See the [list of Germany registry courts](/integration/api/references/registration-numbers/germany-registry-courts).
  - `standing_instruction` InitialStandingInstructionRequest: Terms for a new standing instruction to gather the consent in the initial payment in a series of recurring payments.
    - `terms` StandingInstructionTerms, required: Terms for standing instructions of recurring payments.
      - `type` 'recurring' | 'unscheduled', required: Type of standing instruction. - `recurring`: periodic charges at a fixed frequency. - `unscheduled`: payments with no fixed schedule or frequency.
  - `redirect` object, required: Configuration for the redirect behavior after the payment is completed.
    - `default` string, uri, required: The URL to which the buyer will be redirected after the payment is completed (success or failure), if `completed` or `failed` are not provided.
    - `completed` string, uri: The URL to which the buyer will be redirected if the payment results in success.
    - `failed` string, uri: The URL to which the buyer will be redirected if the payment results in failure.
  - `integration` object: Configuration for the specific checkout integration method used.
    - `type` 'hosted', required: The integration type.
    - `site_url` string, uri, required: The website URL where the buyer is browsing and completing the buy process, before being redirected to the Getpaid hosted checkout. Only the origin (scheme, hostname, and optional port) of this URL is used, not its path, query string, or fragment.
  - `webhooks` PaymentWebhooksRequest: Configuration for webhooks to receive payment status updates.
    - `url` string, uri, required: The URL to which webhook events will be sent.

## Response `201`

Created

- CreateCheckoutResponse
  - `id` string, 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](/payments/checkouts#lifecycle) for more details.
  - `reference` string, required: An identifier in your system. It is recommended to make it unique but the uniqueness is not enforced by the solution.
  - `created_at` string, date-time, required: UTC timestamp in ISO 8601 format with milliseconds ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)). Always includes the 'Z' UTC indicator.
  - `updated_at` string, date-time, required: UTC timestamp in ISO 8601 format with milliseconds ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)). Always includes the 'Z' UTC indicator.
  - `expires_at` string, date-time, required: UTC timestamp in ISO 8601 format with milliseconds ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)). Always includes the 'Z' UTC indicator.
  - `flow` CheckoutFlow, required: The flow required for the checkout to complete.
    - `next_step` object, required: The next step required to complete the flow.
      - `type` 'redirect', required: The type of the next step.
      - `url` string, uri, required: The URL to redirect the buyer to complete the payment.
  - `payment_methods` CheckoutPaymentMethodsResponse, required: The payment methods of this checkout.
    - `type` 'default' | 'explicit', required: The available payment methods selection method.
    - `available` PaymentMethodDescriptor[], required: The list of payment methods available for this checkout.
      - union: A payment method.
        - PaymentMethodBase
          - `type` 'card' | 'sepa_direct_debit', required: The type of payment method.
        - CardPaymentMethodDescriptor
          - `type` 'card' | 'sepa_direct_debit', required: The type of payment method.
          - `scheme` 'visa' | 'mastercard', required: The card scheme.
  - `splits` SplitsCalculated, required: The list of payment splits for the accounts involved in the funds flow. The final split gross amounts have been calculated but processing fees are not included until the payment is captured.
    - `type` 'per_transaction', required: The type of payment split.
    - `accounts` object[], required: The list of accounts involved in the payment that will receive the funds.
      - `type` 'platform' | 'seller' | 'other', required: The type of account. Exactly one of type `seller` is required and allowed per payment.
      - `id` string, id, required: The unique identifier of the account.
      - `version` string, version, required: A resource version.
      - `legal_name` string, required: The legal name of the account.
      - `split` union, required: The amount in the payment currency to be allocated to this account.
        - SplitFixedAmount: The amount in payment currency to be allocated to this account. The sum of all split amounts for all accounts must be exactly the total amount of the payment or use the `remaining` type for one of the accounts to allocate the remaining amount after all other splits have been calculated.
          - `type` 'fixed' | 'percentage' | 'remaining', required: The type of split amount.
          - `amount` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR).
        - SplitPercentageAmountCalculated: The amount in payment currency to be allocated to this account. The sum of all split amounts for all accounts must be exactly the total amount of the payment or use the `remaining` type for one of the accounts to allocate the remaining amount after all other splits have been calculated.
          - `type` 'fixed' | 'percentage' | 'remaining', required: The type of split amount.
          - `percentage` number, float, required: The percentage of the total amount to allocate to this account.
          - `amount` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR).
        - SplitRemainingAmountCalculated: The amount in payment currency to be allocated to this account. The sum of all split amounts for all accounts must be exactly the total amount of the payment or use the `remaining` type for one of the accounts to allocate the remaining amount after all other splits have been calculated.
          - `type` 'fixed' | 'percentage' | 'remaining', required: The type of split amount.
          - `amount` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR).
      - `processing_fee` ProcessingFeeRequest, required: The processing fee covered by this account. If not specified, the account will not cover any processing fee, except when the payment has exactly one seller account and that seller is the authenticated platform account. In that platform-as-seller case, the API defaults the missing processing fee to 100%. The sum of all processing fees covered by all accounts must be exactly 100%.
        - `percentage` number, float, required: The percentage of the total processing fee that this account will cover.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `422`: Invalid Parameters
- `429`: Too Many Requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/getpaid/apis/getpaid-api.md) - [All operations](https://skmtc.dev/getpaid/apis/getpaid-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getpaid/apis/getpaid-api/revisions/458eae3d49ad?raw)