SumUp · Schema

Checkout Create Request

Request body for creating a checkout before processing payment. Define the payment amount, currency, merchant, and optional customer or redirect behavior here.

PaymentsPOSPoint of SaleCard ReadersCheckoutFintechMobile PaymentsOnline Payments

Properties

Name	Type	Description
checkout_reference	string	Merchant-defined reference for the new checkout. It should be unique enough for you to identify the payment attempt in your own systems.
amount	number	Amount to be charged to the payer, expressed in major units.
currency	object
merchant_code	string	Merchant account that should receive the payment.
description	string	Short merchant-defined description shown in SumUp tools and reporting for easier identification of the checkout.
return_url	string	Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.
customer_id	string	Merchant-scoped customer identifier. Required when setting up recurring payments and useful when the checkout should be linked to a returning payer.
purpose	string	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_until	string	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_url	string	URL where the payer should be sent after a redirect-based payment or SCA flow completes. This is required for [APMs](https://developer.sumup.com/online-payments/apm/introduction) and recommended for c
hosted_checkout	object

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Checkout Create Request",
  "description": "Request body for creating a checkout before processing payment. Define the payment amount, currency, merchant, and optional customer or redirect behavior here.",
  "type": "object",
  "properties": {
    "checkout_reference": {
      "description": "Merchant-defined reference for the new checkout. It should be unique enough for you to identify the payment attempt in your own systems.",
      "type": "string",
      "example": "f00a8f74-b05d-4605-bd73-2a901bae5802",
      "maxLength": 90
    },
    "amount": {
      "description": "Amount to be charged to the payer, expressed in major units.",
      "type": "number",
      "format": "float",
      "example": 10.1
    },
    "currency": {
      "$ref": "#/components/schemas/Currency"
    },
    "merchant_code": {
      "description": "Merchant account that should receive the payment.",
      "type": "string",
      "example": "MH4H92C7"
    },
    "description": {
      "description": "Short merchant-defined description shown in SumUp tools and reporting for easier identification of the checkout.",
      "type": "string",
      "example": "Purchase"
    },
    "return_url": {
      "description": "Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.",
      "type": "string",
      "format": "uri",
      "example": "http://example.com/"
    },
    "customer_id": {
      "description": "Merchant-scoped customer identifier. Required when setting up recurring payments and useful when the checkout should be linked to a returning payer.",
      "type": "string",
      "example": "831ff8d4cd5958ab5670"
    },
    "purpose": {
      "description": "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.",
      "type": "string",
      "default": "CHECKOUT",
      "enum": [
        "CHECKOUT",
        "SETUP_RECURRING_PAYMENT"
      ]
    },
    "valid_until": {
      "description": "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.",
      "type": "string",
      "format": "date-time",
      "example": "2020-02-29T10:56:56+00:00",
      "nullable": true
    },
    "redirect_url": {
      "description": "URL where the payer should be sent after a redirect-based payment or SCA flow completes. This is required for [APMs](https://developer.sumup.com/online-payments/apm/introduction) and recommended for card checkouts that may require [3DS](https://developer.sumup.com/online-payments/features/3ds). If it is omitted, the [Payment Widget](https://developer.sumup.com/online-payments/checkouts) can render the challenge in an iframe instead of using a full-page redirect.",
      "type": "string",
      "example": "https://mysite.com/completed_purchase"
    },
    "hosted_checkout": {
      "$ref": "#/components/schemas/HostedCheckout"
    }
  },
  "required": [
    "checkout_reference",
    "amount",
    "currency",
    "merchant_code"
  ]
}