---
title: "Checkout"
description: "Core checkout resource returned by the Checkouts API. A checkout is created before payment processing and then updated as payment attempts, redirects, and resulting transactions are attached to it."
image: "https://developer.sumup.com/og/index.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://developer.sumup.com/llms.txt
> Use this file to discover all available pages before exploring further.

Path: SumUp REST API

Core checkout resource returned by the Checkouts API. A checkout is created before payment processing and then updated as payment attempts, redirects, and resulting transactions are attached to it.

## Fields

- `checkout_reference` (`Checkout.checkout_reference`; string, optional) — Merchant-defined reference for the checkout. Use it to correlate the SumUp checkout with your own order, cart, subscription, or payment attempt in your systems.
  - maxLength 64; example `"f00a8f74-b05d-4605-bd73-2a901bae5802"`
- `amount` (`Checkout.amount`; number, optional) — Amount to be charged to the payer, expressed in major units.
  - format `float`; example `10.1`
- `currency` (`Checkout.currency`; string, optional) — Three-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code of the amount.
  - one of `"BRL"`, `"CHF"`, `"CLP"`, `"COP"`, `"CZK"`, `"DKK"`, `"EUR"`, `"GBP"`, `"HRK"`, `"HUF"`, `"NOK"`, `"PLN"`, `"RON"`, `"SEK"`, `"USD"`; example `"EUR"`
- `merchant_code` (`Checkout.merchant_code`; string, optional) — Short unique identifier for the merchant that receives the payment.
  - example `"MH4H92C7"`
- `description` (`Checkout.description`; string, optional) — Short merchant-defined description shown in SumUp tools and reporting. Use it to make the checkout easier to recognize in dashboards, support workflows, and reconciliation.
  - example `"Purchase"`
- `return_url` (`Checkout.return_url`; string, optional) — Optional backend callback URL for checkout status notifications. SumUp sends an HTTP POST with `event_type` and the checkout `id`. Retrieve the checkout to verify its current status before updating your order. See the [webhook guide](https://developer.sumup.com/online-payments/webhooks/) for the payload and response requirements.
  - format `uri`; example `"http://example.com"`
- `id` (`Checkout.id`; string, optional) — Unique SumUp identifier of the checkout resource.
  - example `"4e425463-3e1b-431d-83fa-1e51c2925e99"`
- `status` (`Checkout.status`; string, optional) — Current high-level state of the checkout. `PENDING` means the checkout exists but is not yet completed, `PAID` means a payment succeeded, `FAILED` means the latest processing attempt failed, and `EXPIRED` means the checkout can no longer be processed.
  - one of `"PENDING"`, `"FAILED"`, `"PAID"`, `"EXPIRED"`; example `"PENDING"`
- `date` (`Checkout.date`; string, optional) — The timestamp of when the checkout was created.
  - format `date-time`; example `"2020-02-29T10:56:56+00:00"`
- `valid_until` (`Checkout.valid_until`; string, optional, nullable) — Optional expiration timestamp. The checkout must be processed before this moment, otherwise it becomes unusable. If omitted, the checkout does not have an explicit expiry time.
  - format `date-time`; example `"2030-12-31T23:59:59Z"`
- `customer_id` (`Checkout.customer_id`; string, optional) — Merchant-scoped identifier of the customer associated with the checkout. Use it when storing payment instruments or reusing saved customer context for recurring and returning-payer flows.
  - example `"831ff8d4cd5958ab5670"`
- `mandate` (`Checkout.mandate`; object, optional) — Details of the mandate linked to the saved payment instrument.
  - example `{"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}`
  - `type` (`Checkout.mandate.type`; string, optional) — Type of mandate stored for the checkout or payment instrument.
    - example `"recurrent"`
  - `status` (`Checkout.mandate.status`; string, optional) — Current lifecycle status of the mandate.
    - one of `"active"`, `"inactive"`; example `"active"`
  - `merchant_code` (`Checkout.mandate.merchant_code`; string, optional) — Short unique identifier for the merchant for which the mandate is valid.
    - example `"MH4H92C7"`
- `hosted_checkout_url` (`Checkout.hosted_checkout_url`; string, optional) — URL of the SumUp-hosted payment page that handles the payment flow. Returned when Hosted Checkout is enabled for the checkout.
  - format `uri`; example `"https://checkout.sumup.com/pay/8f9316a3-cda9-42a9-9771-54d534315676"`
- `transactions` (`Checkout.transactions`; array<unknown>, optional) — Payment attempts and resulting transaction records linked to this checkout. Use the Transactions endpoints when you need the authoritative payment result and event history.
  - example `[{"id":"410fc44a-5956-44e1-b5cc-19c6f8d727a4","transaction_code":"TEENSK4W2K","amount":10.1,"currency":"EUR","timestamp":"2020-02-29T10:56:56.876Z","status":"SUCCESSFUL","payment_type":"ECOM","installments_count":1,"merchant_code":"MH4H92C7","vat_amount":6,"tip_amount":3,"entry_mode":"CUSTOMER_ENTRY","auth_code":"012345"}]`
  - `id` (`Checkout.transactions.id`; string, optional) — Unique identifier of the transaction.
    - example `"6b425463-3e1b-431d-83fa-1e51c2925e99"`
  - `transaction_code` (`Checkout.transactions.transaction_code`; string, optional) — SumUp transaction code, for example `TEENSK4W2K`. Use it to look up the transaction with the `transaction_code` query parameter. This is separate from the transaction's `id` and the card issuer's `auth_code`.
    - example `"TEENSK4W2K"`
  - `amount` (`Checkout.transactions.amount`; number, optional) — Total amount of the transaction in major units of `currency`, for example `10.1` for EUR 10.10.
    - format `float`; example `10.1`
  - `currency` (`Checkout.transactions.currency`; string, optional) — Three-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code of the amount.
    - one of `"BRL"`, `"CHF"`, `"CLP"`, `"COP"`, `"CZK"`, `"DKK"`, `"EUR"`, `"GBP"`, `"HRK"`, `"HUF"`, `"NOK"`, `"PLN"`, `"RON"`, `"SEK"`, `"USD"`; example `"EUR"`
  - `timestamp` (`Checkout.transactions.timestamp`; string, optional) — The timestamp of when the transaction was created.
    - format `date-time`; example `"2020-02-29T10:56:56.876Z"`
  - `status` (`Checkout.transactions.status`; string, optional) — Current status of the transaction. - `PENDING`: The transaction has been created but its final outcome is not known yet. - `SUCCESSFUL`: The transaction completed successfully. - `CANCELLED`: The transaction was cancelled or otherwise reversed before completion. - `FAILED`: The transaction attempt did not complete successfully. - `REFUNDED`: The transaction was refunded in full or in part.
    - one of `"SUCCESSFUL"`, `"CANCELLED"`, `"FAILED"`, `"PENDING"`, `"REFUNDED"`; example `"SUCCESSFUL"`
  - `payment_type` (`Checkout.transactions.payment_type`; string, optional) — Payment category recorded on a transaction, for example `POS` for a point-of-sale card payment, `ECOM` for an online card payment, or `RECURRING` for a recurring card payment. These reporting values are separate from the lowercase `payment_type` values used to process checkouts.
    - one of `"CASH"`, `"POS"`, `"ECOM"`, `"RECURRING"`, `"BITCOIN"`, `"BALANCE"`, `"MOTO"`, `"BOLETO"`, `"DIRECT_DEBIT"`, `"APM"`, `"UNKNOWN"`; example `"ECOM"`
  - `installments_count` (`Checkout.transactions.installments_count`; integer, optional) — Number of installments for a deferred payment.
    - min 1; example `1`
  - `merchant_code` (`Checkout.transactions.merchant_code`; string, optional) — Unique code of the registered merchant to whom the payment is made.
    - example `"MH4H92C7"`
  - `vat_amount` (`Checkout.transactions.vat_amount`; number, optional) — VAT included in the total transaction amount, in major units of the transaction's currency.
    - format `float`; example `6`
  - `tip_amount` (`Checkout.transactions.tip_amount`; number, optional) — Tip included in the total transaction amount, in major units of the transaction's currency.
    - format `float`; example `3`
  - `entry_mode` (`Checkout.transactions.entry_mode`; string, optional) — How the payment details were captured, for example `CHIP` or `CONTACTLESS` for card-present payments and `CUSTOMER_ENTRY` for card details entered by the payer. For wallet and alternative payment methods, this can identify the method, such as `APPLE_PAY` or `BLIK`.
    - one of `"BOLETO"`, `"SOFORT"`, `"IDEAL"`, `"BANCONTACT"`, `"EPS"`, `"MYBANK"`, `"SATISPAY"`, `"BLIK"`, `"P24"`, `"GIROPAY"`, `"PIX"`, `"QR_CODE_PIX"`, `"APPLE_PAY"`, `"GOOGLE_PAY"`, `"PAYPAL"`, `"TWINT"`, `"NONE"`, `"CHIP"`, `"MANUAL_ENTRY"`, `"CUSTOMER_ENTRY"`, `"MAGSTRIPE_FALLBACK"`, `"MAGSTRIPE"`, `"DIRECT_DEBIT"`, `"CONTACTLESS"`, `"MOTO"`, `"CONTACTLESS_MAGSTRIPE"`, `"N/A"`; example `"CUSTOMER_ENTRY"`
  - `auth_code` (`Checkout.transactions.auth_code`; string, optional) — Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
    - example `"053201"`


Source: https://developer.sumup.com/api/schemas/Checkout/index.md