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

# Create a checkout

`POST /v0.1/checkouts`

Creates a new payment checkout resource. The unique `checkout_reference` created by this request, is used for further manipulation of the checkout.

For 3DS checkouts, add the `redirect_url` parameter to your request body schema.

Follow by processing a checkout to charge the provided payment instrument.

## Request body

- CheckoutCreateRequest — Details of the payment checkout.
  - `checkout_reference` string, required — Unique ID of the payment checkout specified by the client application when creating the checkout resource.
  - `amount` number, float, required — Amount of the payment.
  - `currency` 'BGN' | 'BRL' | 'CHF' | 'CLP' | 'COP' | 'CZK' | 'DKK' | 'EUR' | 'GBP' | 'HRK' | 'HUF' | 'NOK' | 'PLN' | 'RON' | 'SEK' | 'USD', required — Three-letter [ISO4217](https://en.wikipedia.org/wiki/ISO_4217) code of the currency for the amount. Currently supported currency values are enumerated above.
  - `merchant_code` string, required — Unique identifying code of the merchant profile.
  - `description` string — Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.
  - `return_url` string, uri — URL to which the SumUp platform sends the processing status of the payment checkout.
  - `customer_id` string — Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referenced customer.
  - `purpose` 'CHECKOUT' | 'SETUP_RECURRING_PAYMENT' — Purpose of the checkout.
  - `valid_until` string, date-time, nullable — Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.
  - `redirect_url` string — __Required__ for [APMs](https://developer.sumup.com/online-payments/apm/introduction) and __recommended__ for card payments. Refers to a url where the end user is redirected once the payment processing completes. If not specified, the [Payment Widget](https://developer.sumup.com/online-payments/tools/card-widget) renders [3DS challenge](https://developer.sumup.com/online-payments/features/3ds) within an iframe instead of performing a full-page redirect.

## Response `201`

Returns the created checkout resource.

- Checkout — Details of the payment checkout.
  - `checkout_reference` string — Unique ID of the payment checkout specified by the client application when creating the checkout resource.
  - `amount` number, float — Amount of the payment.
  - `currency` 'BGN' | 'BRL' | 'CHF' | 'CLP' | 'COP' | 'CZK' | 'DKK' | 'EUR' | 'GBP' | 'HRK' | 'HUF' | 'NOK' | 'PLN' | 'RON' | 'SEK' | 'USD' — Three-letter [ISO4217](https://en.wikipedia.org/wiki/ISO_4217) code of the currency for the amount. Currently supported currency values are enumerated above.
  - `merchant_code` string — Unique identifying code of the merchant profile.
  - `description` string — Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.
  - `return_url` string, uri — URL to which the SumUp platform sends the processing status of the payment checkout.
  - `id` string — Unique ID of the checkout resource.
  - `status` 'PENDING' | 'FAILED' | 'PAID' | 'EXPIRED' — Current status of the checkout.
  - `date` string, date-time — Date and time of the creation of the payment checkout. Response format expressed according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) code.
  - `valid_until` string, date-time, nullable — Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.
  - `customer_id` string — Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referenced customer.
  - `mandate` MandateResponse — Created mandate
    - `type` string — Indicates the mandate type
    - `status` string — Mandate status
    - `merchant_code` string — Merchant code which has the mandate
  - `transactions` object[] — List of transactions related to the payment.
    - `id` string — Unique ID of the transaction.
    - `transaction_code` string — Transaction code returned by the acquirer/processing entity after processing the transaction.
    - `amount` number, float — Total amount of the transaction.
    - `currency` 'BGN' | 'BRL' | 'CHF' | 'CLP' | 'COP' | 'CZK' | 'DKK' | 'EUR' | 'GBP' | 'HRK' | 'HUF' | 'NOK' | 'PLN' | 'RON' | 'SEK' | 'USD' — Three-letter [ISO4217](https://en.wikipedia.org/wiki/ISO_4217) code of the currency for the amount. Currently supported currency values are enumerated above.
    - `timestamp` string, date-time — Date and time of the creation of the transaction. Response format expressed according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) code.
    - `status` 'SUCCESSFUL' | 'CANCELLED' | 'FAILED' | 'PENDING' — Current status of the transaction.
    - `payment_type` 'CASH' | 'POS' | 'ECOM' | 'RECURRING' | 'BITCOIN' | 'BALANCE' | 'MOTO' | 'BOLETO' | 'DIRECT_DEBIT' | 'APM' | 'UNKNOWN' — Payment type used for the transaction.
    - `installments_count` integer — Current number of the installment for deferred payments.
    - `merchant_code` string — Unique code of the registered merchant to whom the payment is made.
    - `vat_amount` number, float — Amount of the applicable VAT (out of the total transaction amount).
    - `tip_amount` number, float — Amount of the tip (out of the total transaction amount).
    - `entry_mode` 'none' | 'magstripe' | 'chip' | 'manual entry' | 'customer entry' | 'magstripe fallback' | 'contactless' | 'moto' | 'contactless magstripe' | 'boleto' | 'direct debit' | 'sofort' | 'ideal' | 'bancontact' | 'eps' | 'mybank' | 'satispay' | 'blik' | 'p24' | 'giropay' | 'pix' | 'qr code pix' | 'apple pay' | 'google pay' | 'paypal' | 'twint' | 'na' — Entry mode of the payment details.
    - `auth_code` string — Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
    - `internal_id` integer — Internal unique ID of the transaction on the SumUp platform.

## Other responses

- `400` — The request body is invalid.
- `401` — The request is not authorized.
- `403` — The request isn't sufficiently authorized to create a checkout.
- `409` — A checkout already exists for the provided unique parameters.

## Changes

- **2026-03-24** `bc466839f97d` — 1 warning
  - added the new `twint` enum value to the `transactions/items/allOf[subschema #2: Transaction Checkout Info]/entry_mode` response property for the response status `201`
- **2026-03-11** `cd79d83b07e0` — 2 warning, 5 info
  - removed the optional property `error_code` from the response with the `401` status
  - removed the optional property `message` from the response with the `401` status
  - added the optional property `detail` to the response with the `401` status
  - added the optional property `instance` to the response with the `401` status
  - …3 more
- **2026-02-25** `bef1083e0580` — 2 warning, 2 info
  - added the new `COP` enum value to the `currency` response property for the response status `201`
  - added the new `COP` enum value to the `transactions/items/allOf[#/components/schemas/TransactionBase]/currency` response property for the response status `201`
  - added the new `COP` enum value to the request property `currency`
  - added the new `COP` enum value to the request property `transactions/items/allOf[#/components/schemas/TransactionBase]/currency`
- …earlier changes not shown

[Full history](https://skmtc.dev/sumup/apis/sumup-rest-api/changes/v0.1/checkouts/post.md)

---

[API](https://skmtc.dev/sumup/apis/sumup-rest-api.md) · [All operations](https://skmtc.dev/sumup/apis/sumup-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/sumup/sumup-rest-api/revisions/bc466839f97d/schema)