Checkout Create Request

{
  "$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"
  ]
}