Sign in

v50

latestOpenAPI 3.0.3Apache 2.0raw.githubusercontent.com2026-08-0342108400.9 KB
Checkouts

Create a checkout

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. To use the Hosted Checkout page, set the hosted_checkout.enabled to true.

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

post/v0.1/checkouts

Request body

checkout_referencestring required

Merchant-defined reference for the new checkout. It should be unique enough for you to identify the payment attempt in your own systems.

amountnumber float required

Amount to be charged to the payer, expressed in major units.

currency'BGN' | 'BRL' | 'CHF' | 'CLP' | 'COP' | 'CZK' | 'DKK' | 'EUR' | 'GBP' | 'HRK' | 'HUF' | 'NOK' | 'PLN' | 'RON' | 'SEK' | 'USD' required

Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

merchant_codestring required

Merchant account that should receive the payment.

descriptionstring

Short merchant-defined description shown in SumUp tools and reporting for easier identification of the checkout.

return_urlstring uri

Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.

customer_idstring

Merchant-scoped customer identifier. Required when setting up recurring payments and useful when the checkout should be linked to a returning payer.

purpose'CHECKOUT' | 'SETUP_RECURRING_PAYMENT'

Business purpose of the checkout. Use CHECKOUT for a standard payment and SETUP_RECURRING_PAYMENT when collecting consent and payment details for future recurring charges.

valid_untilstring date-time 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.

redirect_urlstring

URL where the payer should be sent after a redirect-based payment or SCA flow completes. This is required for APMs and recommended for card checkouts that may require 3DS. If it is omitted, the Payment Widget can render the challenge in an iframe instead of using a full-page redirect.

Example request

{
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "amount": 10.1,
  "currency": "EUR",
  "merchant_code": "MH4H92C7",
  "description": "Purchase",
  "return_url": "http://example.com/",
  "customer_id": "831ff8d4cd5958ab5670",
  "valid_until": "2020-02-29T10:56:56+00:00",
  "redirect_url": "https://mysite.com/completed_purchase",
  "hosted_checkout": {
    "enabled": true
  }
}

Response

Returns the created checkout resource.

checkout_referencestring

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.

amountnumber float

Amount to be charged to the payer, expressed in major units.

currency'BGN' | 'BRL' | 'CHF' | 'CLP' | 'COP' | 'CZK' | 'DKK' | 'EUR' | 'GBP' | 'HRK' | 'HUF' | 'NOK' | 'PLN' | 'RON' | 'SEK' | 'USD'

Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

merchant_codestring

Merchant account that receives the payment.

descriptionstring

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.

return_urlstring uri

Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.

idstring

Unique SumUp identifier of the checkout resource.

status'PENDING' | 'FAILED' | 'PAID' | 'EXPIRED'

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.

datestring date-time

Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.

valid_untilstring date-time 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.

customer_idstring

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.

hosted_checkout_urlstring uri

URL of the SumUp-hosted payment page that handles the payment flow. Returned when Hosted Checkout is enabled for the checkout.

Example response

{
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "amount": 10.1,
  "currency": "EUR",
  "merchant_code": "MH4H92C7",
  "description": "Purchase",
  "return_url": "http://example.com",
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
  "status": "PENDING",
  "date": "2020-02-29T10:56:56+00:00",
  "valid_until": "2020-02-29T10:56:56+00:00",
  "customer_id": "831ff8d4cd5958ab5670",
  "mandate": {
    "type": "recurrent",
    "status": "active",
    "merchant_code": "MH4H92C7"
  },
  "hosted_checkout_url": "https://checkout.sumup.com/pay/8f9316a3-cda9-42a9-9771-54d534315676",
  "transactions": [
    {
      "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"
    }
  ]
}