Create a checkout

/v0.1/checkouts

Creates a payment checkout for the specified merchant, amount, and currency. Supply a checkout_reference to identify the payment attempt in your own systems. Creating a checkout does not charge a payment instrument.

Set hosted_checkout.enabled to true to receive a Hosted Checkout URL where the customer can complete the payment. Use redirect_url for redirect-based payment and 3DS flows. If return_url is provided, SumUp sends processing updates to that backend callback URL.

Complete the payment through Hosted Checkout or the Payment Widget.

OAuth scopes: Requires one of: payments, checkouts.write.

Authorization

Use one of the following alternatives:

apiKey
oauth2 with scopes paymentscheckouts.write

Authorization guide

Body parameters

application/jsonrequired

Details for creating a checkout resource.

checkout_referencestringrequired
maxLength: 64
Merchant-defined reference for the new checkout, up to 64 characters. Use it to correlate the checkout with an order or payment attempt in your own system. If a checkout already exists for the supplied unique parameters, creation returns 409 with DUPLICATED_CHECKOUT; see the conflict response.

Example: "f00a8f74-b05d-4605-bd73-2a901bae5802"
amountnumberrequired
format: float
Amount to be charged to the payer, expressed in major units.

Example: 10.1
currencystringrequired
Options:"BRL""CHF""CLP""COP""CZK""DKK""EUR""GBP""HRK""HUF""NOK""PLN""RON""SEK""USD"
Three-letter ISO 4217 currency code of the amount.

Example: "EUR"
merchant_codestringrequired
Short unique identifier for the merchant that should receive the payment.

Example: "MH4H92C7"
descriptionstring
Short merchant-defined description shown in SumUp tools and reporting for easier identification of the checkout.

Example: "Purchase"
return_urlstring
format: uri
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 for the payload and response requirements.

Example: "http://example.com/"
customer_idstring
Merchant-scoped customer identifier. Required when setting up recurring payments and useful when the checkout should be linked to a returning payer.

Example: "831ff8d4cd5958ab5670"
purposestring
Options:"CHECKOUT""SETUP_RECURRING_PAYMENT"
default: "CHECKOUT"
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_untilstringnullable
format: date-time
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.

Example: "2030-12-31T23:59:59Z"
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: "https://mysite.com/completed_purchase"
hosted_checkoutobject
Hosted Checkout configuration. Enable it to receive a SumUp-hosted payment page URL in the checkout response.
Show 1 property
- enabledbooleanrequired
  Whether the checkout should include a SumUp-hosted payment page.
  
  Example: true

Request examples

Standard request body for creating a checkout

Checkout

{
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "amount": 10.1,
  "currency": "EUR",
  "merchant_code": "MH4H92C7",
  "description": "Purchase",
  "valid_until": "2030-12-31T23:59:59Z",
  "redirect_url": "https://sumup.com"
}

Create a 3DS checkout

Checkout3DS

{
  "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",
  "redirect_url": "https://mysite.com/completed_purchase"
}

Create an Alternative Payment Method checkout

CheckoutAPM

{
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "amount": 10.1,
  "currency": "EUR",
  "merchant_code": "MH4H92C7",
  "redirect_url": "https://mysite.com/completed_purchase"
}

Create a checkout with a SumUp-hosted payment page

HostedCheckout

{
  "checkout_reference": "b50pr914-6k0e-3091-a592-890010285b3d",
  "amount": 12,
  "currency": "EUR",
  "merchant_code": "MCXXXXXX",
  "description": "A sample checkout",
  "hosted_checkout": {
    "enabled": true
  }
}

Responses

201application/json

Returns the created checkout resource.

checkout_referencestring
maxLength: 64
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.

Example: "f00a8f74-b05d-4605-bd73-2a901bae5802"
amountnumber
format: float
Amount to be charged to the payer, expressed in major units.

Example: 10.1
currencystring
Options:"BRL""CHF""CLP""COP""CZK""DKK""EUR""GBP""HRK""HUF""NOK""PLN""RON""SEK""USD"
Three-letter ISO 4217 currency code of the amount.

Example: "EUR"
merchant_codestring
Short unique identifier for the merchant that receives the payment.

Example: "MH4H92C7"
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.

Example: "Purchase"
return_urlstring
format: uri
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 for the payload and response requirements.

Example: "http://example.com"
idstring
Unique SumUp identifier of the checkout resource.

Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
statusstring
Options:"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.

Example: "PENDING"
datestring
format: date-time
The timestamp of when the checkout was created.

Example: "2020-02-29T10:56:56+00:00"
valid_untilstringnullable
format: date-time
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.

Example: "2030-12-31T23:59:59Z"
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.

Example: "831ff8d4cd5958ab5670"
mandateobject
Details of the mandate linked to the saved payment instrument.

Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
Show 3 properties
- typestring
  Type of mandate stored for the checkout or payment instrument.
  
  Example: "recurrent"
- statusstring
  Options:"active""inactive"
  Current lifecycle status of the mandate.
  
  Example: "active"
- merchant_codestring
  Short unique identifier for the merchant for which the mandate is valid.
  
  Example: "MH4H92C7"
hosted_checkout_urlstring
format: uri
URL of the SumUp-hosted payment page that handles the payment flow. Returned when Hosted Checkout is enabled for the checkout.

Example: "https://checkout.sumup.com/pay/8f9316a3-cda9-42a9-9771-54d534315676"
transactionsarray<unknown>
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"}]
Show 13 properties
- idstring
  Unique identifier of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- transaction_codestring
  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"
- amountnumber
  format: float
  Total amount of the transaction in major units of currency, for example 10.1 for EUR 10.10.
  
  Example: 10.1
- currencystring
  Options:"BRL""CHF""CLP""COP""CZK""DKK""EUR""GBP""HRK""HUF""NOK""PLN""RON""SEK""USD"
  Three-letter ISO 4217 currency code of the amount.
  
  Example: "EUR"
- timestampstring
  format: date-time
  The timestamp of when the transaction was created.
  
  Example: "2020-02-29T10:56:56.876Z"
- statusstring
  Options:"SUCCESSFUL""CANCELLED""FAILED""PENDING""REFUNDED"
  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.
  
  Example: "SUCCESSFUL"
- payment_typestring
  Options:"CASH""POS""ECOM""RECURRING""BITCOIN""BALANCE""MOTO""BOLETO""DIRECT_DEBIT""APM""UNKNOWN"
  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.
  
  Example: "ECOM"
- installments_countinteger
  minimum: 1
  Number of installments for a deferred payment.
  
  Example: 1
- merchant_codestring
  Unique code of the registered merchant to whom the payment is made.
  
  Example: "MH4H92C7"
- vat_amountnumber
  format: float
  VAT included in the total transaction amount, in major units of the transaction's currency.
  
  Example: 6
- tip_amountnumber
  format: float
  Tip included in the total transaction amount, in major units of the transaction's currency.
  
  Example: 3
- entry_modestring
  Options:"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"
  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.
  
  Example: "CUSTOMER_ENTRY"
- auth_codestring
  Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
  
  Example: "053201"

400application/json

The request body is invalid.

messagestring
Short description of the error.

Example: "Resource not found"
error_codestring
Platform code for the error.

Example: "NOT_FOUND"
paramstring
Parameter name (with relative location) to which the error applies. Parameters from embedded resources are displayed using dot notation. For example, card.name refers to the name parameter embedded in the card object.

Example: "card.name"

401application/json

The request is not authorized.

typestringrequired
format: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestring
format: uri
A URI reference that identifies the specific occurrence of the problem.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

403application/json

The request isn't sufficiently authorized to create a checkout.

error_messagestring
Short description of the error.

Example: "request_not_allowed"
error_codestring
Platform code for the error.

Example: "FORBIDDEN"
status_codestring
HTTP status code for the error.

Example: "403"

409application/json

A checkout already exists for the provided unique parameters.

messagestring
Short description of the error.

Example: "Resource not found"
error_codestring
Platform code for the error.

Example: "NOT_FOUND"

Code sample

curl --request POST \
  --url https://api.sumup.com/v0.1/checkouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "amount": 10.1,
  "currency": "EUR",
  "merchant_code": "MH4H92C7",
  "description": "Purchase",
  "valid_until": "2030-12-31T23:59:59Z",
  "redirect_url": "https://sumup.com"
}
'

sumup checkouts create \
  --reference "f00a8f74-b05d-4605-bd73-2a901bae5802" \
  --amount "10.1" \
  --currency "EUR" \
  --merchant-code "MH4H92C7" \
  --description "Purchase" \
  --redirect-url "https://sumup.com" \
  --valid-until "2030-12-31T23:59:59Z"

import SumUp from "@sumup/sdk";

async function main() {
  const client = new SumUp({ apiKey: "sup_sk_your_api_key" });

  const result = await client.checkouts.create(
    {
      "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
      "amount": 10.1,
      "currency": "EUR",
      "merchant_code": "MH4H92C7",
      "description": "Purchase",
      "valid_until": "2030-12-31T23:59:59Z",
      "redirect_url": "https://sumup.com"
    }
  );
  console.log(result);
}

main().catch(console.error);

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using SumUp;

public static class Program
{
    public static async Task Main()
    {
        using var client = new SumUpClient();
        var response = await client.Checkouts.CreateAsync(
            new CheckoutCreateRequest
            {
                Amount = 10.1f,
                CheckoutReference = "f00a8f74-b05d-4605-bd73-2a901bae5802",
                Currency = Currency.Eur,
                Description = "Purchase",
                MerchantCode = "MH4H92C7",
                RedirectUrl = "https://sumup.com",
                ValidUntil = DateTimeOffset.Parse("2030-12-31T23:59:59Z"),
            });

        Console.WriteLine(response.StatusCode);
    }
}

import com.sumup.sdk.SumUpClient;

public final class CreateCheckoutCheckoutSample {
  public static void main(String[] args) throws Exception {
    var client = new SumUpClient();

    var result = client.checkouts().create(
            com.sumup.sdk.models.CheckoutCreateRequest.builder()
                .amount(10.1f)
                .checkoutReference("f00a8f74-b05d-4605-bd73-2a901bae5802")
                .currency(com.sumup.sdk.models.Currency.of("EUR"))
                .description("Purchase")
                .merchantCode("MH4H92C7")
                .redirectUrl("https://sumup.com")
                .validUntil(java.time.OffsetDateTime.parse("2030-12-31T23:59:59Z"))
                .build()
        );
    System.out.println(result);
  }
}

import os

import sumup

client = sumup.Sumup(api_key=os.environ["SUMUP_API_KEY"])
result = client.checkouts.create(
    checkout_reference="f00a8f74-b05d-4605-bd73-2a901bae5802",
    amount=10.1,
    currency="EUR",
    merchant_code="MH4H92C7",
    description="Purchase",
    valid_until="2030-12-31T23:59:59Z",
    redirect_url="https://sumup.com",
)
print(result)

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

$sumup = new \SumUp\SumUp('sup_sk_your_api_key');

$body = [
    'amount' => 10.1,
    'checkout_reference' => 'f00a8f74-b05d-4605-bd73-2a901bae5802',
    'currency' => 'EUR',
    'description' => 'Purchase',
    'merchant_code' => 'MH4H92C7',
    'redirect_url' => 'https://sumup.com',
    'valid_until' => '2030-12-31T23:59:59Z',
];

$result = $sumup->checkouts()->create(
    $body,
);

var_dump($result);

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/sumup/sumup-go"
	"github.com/sumup/sumup-go/nullable"
)

func main() {
	client := sumup.NewClient()
	result, err := client.Checkouts.Create(context.TODO(), sumup.CheckoutsCreateParams{
		Amount:            10.1,
		CheckoutReference: "f00a8f74-b05d-4605-bd73-2a901bae5802",
		Currency:          "EUR",
		Description:       new("Purchase"),
		MerchantCode:      "MH4H92C7",
		RedirectURL:       new("https://sumup.com"),
		ValidUntil:        nullable.Value(time.Date(2030, time.December, 31, 23, 59, 59, 0, time.UTC)),
	})
	if err != nil {
		panic(err.Error())
	}

	fmt.Printf("%+v\n", result)
}

use sumup::{Authorization, Client};
#[tokio::main]
async fn main() {
    let client = Client::default()
        .with_authorization(Authorization::api_key("sup_sk_test_..."));
    let body = sumup::resources::checkouts::CreateRequest::builder()
        .amount(10.1f32)
        .checkout_reference("f00a8f74-b05d-4605-bd73-2a901bae5802")
        .currency(sumup::resources::common::Currency::EUR)
        .description("Purchase")
        .merchant_code("MH4H92C7")
        .redirect_url("https://sumup.com")
        .valid_until(
            sumup::Nullable::Value("2030-12-31T23:59:59Z".parse().expect("valid date")),
        )
        .build();
    let response = client.checkouts().create(body).await.expect("create request failed");
    println!("{response:#?}");
}

Response example

{
  "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5",
  "amount": 10.1,
  "currency": "EUR",
  "merchant_code": "MH4H92C7",
  "merchant_country": "DE",
  "description": "My Checkout",
  "return_url": "http://example.com",
  "id": "88fcf8de-304d-4820-8f1c-ec880290eb92",
  "status": "PENDING",
  "date": "2020-02-29T10:56:56+00:00",
  "valid_until": "2030-12-31T23:59:59Z",
  "customer_id": "831ff8d4cd5958ab5670",
  "mandate": {
    "type": "recurrent",
    "status": "active",
    "merchant_code": "MH4H92C7"
  },
  "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"
    }
  ]
}

{
  "message": "Validation error",
  "error_code": "MISSING",
  "param": "merchant_code"
}

{
  "detail": "Unauthorized.",
  "status": 401,
  "title": "Unauthorized",
  "trace_id": "3c77294349d3b5647ea2d990f0d8f017",
  "type": "https://developer.sumup.com/problem/unauthorized"
}

{
  "error_message": "checkout_payments_not_allowed",
  "error_code": "FORBIDDEN",
  "status_code": "403"
}

{
  "error_code": "DUPLICATED_CHECKOUT",
  "message": "Checkout with this checkout reference and pay to email already exists"
}