Create a Reader Checkout

/v0.1/merchants/{merchant_code}/readers/{reader_id}/checkout

Creates a Checkout for a Reader.

This process is asynchronous and the actual transaction may take some time to be started on the device.

There are some caveats when using this endpoint:

The target device must be online, otherwise checkout won't be accepted
After the checkout is accepted, the system has 60 seconds to start the payment on the target device. During this time, any other checkout for the same device will be rejected.

Note: If the target device is a Solo, it must be in version 3.3.24.3 or higher.

Optionally include an affiliate object to attach integrator metadata to the payment. Provide both app_id and key when including this object.

OAuth scopes: Requires one of: readers.write.

Required permissions:

readers.checkouts.create

Authorization

Use one of the following alternatives:

apiKey
oauth2 with scopes readers.write

Authorization guide

Path parameters

merchant_codestringrequired
Merchant Code
reader_idstringrequired
The unique identifier of the Reader

Body parameters

application/jsonrequired

A checkout initial attributes

total_amountobjectrequired
Amount structure.

The amount is represented as an integer value altogether with the currency and the minor unit.

For example, EUR 1.00 is represented as value 100 with minor unit of 2.

Example: {"currency":"EUR","minor_unit":2,"value":1000}
Show 3 properties
- currencystringrequired
  Currency ISO 4217 code
  
  Example: "EUR"
- minor_unitintegerrequired
  minimum: 0
  The minor units of the currency. It represents the number of decimals of the currency. For the currencies CLP, COP and HUF, the minor unit is 0.
  
  Example: 2
- valueintegerrequired
  minimum: 0
  Integer value of the amount.
  
  Example: 1000
aadeobject
Optional object containing data for transactions from ERP integrators in Greece that comply with the AADE 1155 protocol. When such regulatory/business requirements apply, this object must be provided and contains the data needed to validate the transaction with the AADE signature provider.
Show 3 properties
- provider_idstringrequired
  The identifier of the AADE signature provider.
  
  Example: "123"
- signaturestringrequired
  The base64 encoded signature of the transaction data.
  
  Example: "QjcxRDdBNTU1MDcyRTNFRTREMkZEM0Y0NTdBMjkxMTU4MzBFNkNCQTs7MjAyNTExMTIyMTQ3MTM7Nzk2OzEwNDs5MDA7OTAwOzU0ODg5MDM5"
- signature_datastringrequired
  The string containing the signed transaction data.
  
  Example: "B71D7A555072E3EE4D2FD3F457A29115830E6CBA;;20251112214713;796;104;900;900;54889039"
affiliateobjectnullable
Optional affiliate metadata associated with the checkout's payment. Provide both app_id and key when including this object.
Show 4 properties
- app_idstringrequired
  Integrator application identifier from the Affiliate Keys page. Required when the affiliate object is provided.
  
  Example: "com.example.app"
- keystringrequired
  Affiliate key generated in the Affiliate Keys page. Required when the affiliate object is provided.
  
  Example: "123e4567-e89b-12d3-a456-426614174000"
- foreign_transaction_idstring
  Integrator-owned transaction reference. Optional. Can be used to retrieve the transaction via the Transactions API.
  
  Example: "19e12390-72cf-4f9f-80b5-b0c8a67fa43f"
- tagsobject
  Optional key-value metadata associated with the transaction.
  
  Example: {"custom_key_1":"custom_value_1","custom_key_2":"custom_value_2"}
card_typestring
Options:"credit""debit"
The card type of the card used for the transaction. It is required only for some countries (e.g: Brazil).

Example: "credit"
descriptionstring
Description of the checkout to be shown in the Merchant Sales
installmentsintegernullable
minimum: 1
Number of installments for the transaction. It may vary according to the merchant country. For example, in Brazil, the maximum number of installments is 12.

Omit if the merchant country does not support installments. Otherwise, the checkout will be rejected.

Example: 1
payment_typestring
Options:"card""pix"
default: "card"
The payment method type for the transaction. Defaults to card.

Use pix to initiate a Pix QR-code payment flow on the device. Pix is only supported for Brazilian merchants; other merchants will receive a 422 error.

Example: "card"
return_urlstring
format: uri
Webhook URL to which the payment result will be sent. It must be a HTTPS url.

Example: "https://www.example.com"
tip_ratesarray<number>
format: floatminimum: 0.01maximum: 1
Exactly three distinct tipping rates to be displayed to the cardholder. Each rate is a fraction between 0.01 and 1.00 in increments of 0.01. The rates are sorted in ascending order by the server.
tip_timeoutinteger
minimum: 30maximum: 120default: 30
Time in seconds the cardholder has to select a tip rate. If not provided, the default value is 30 seconds.

It can only be set if tip_rates is provided.

Note: If the target device is a Solo, it must be in version 3.3.38.0 or higher.

Example: 30

Responses

201application/json

The Checkout got successfully created for the given reader.

dataobjectrequired
Show 2 properties
- client_transaction_idstringrequired
  Unique identifier for the transaction associated with this checkout. Use this value to match the checkout with payment events and transaction records.
  
  Example: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
- checkout_idstring
  The checkout ID is a unique identifier for the checkout.
  
  Example: "3fa85f64-5717-4562-b3fc-2c963f66afa6"

400application/json

Response when given params (or one of them) are invalid

errorsobjectrequired
Show 2 properties
- typestringrequired
  Error code
- detailstring
  Error message

application/problem+json

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.

{
  "detail": "Invalid affiliate key.",
  "status": 400,
  "title": "Invalid Affiliate Key",
  "type": "https://developer.sumup.com/problem/invalid-affiliate-key"
}

401application/json

Unauthorized

errorsobjectrequired
Show 2 properties
- typestringrequired
  Error code
- detailstring
  Error message

application/problem+json

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.

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

404application/json

Response when given reader is not found

errorsobjectrequired
Show 1 property
- detailstringrequired
  Fuller message giving context to error

application/problem+json

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.

{
  "detail": "The requested resource doesn't exist or does not belong to you.",
  "status": 404,
  "title": "Requested resource couldn't be found.",
  "type": "https://developer.sumup.com/problem/not-found"
}

422application/json

Response when given params (or one of them) are invalid

errorsobjectrequired

application/problem+json

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.

{
  "detail": "Payment method not allowed for this merchant.",
  "status": 422,
  "title": "Payment Method Not Allowed",
  "type": "https://developer.sumup.com/problem/payment-method-not-allowed"
}

Code sample

curl --request POST \
  --url https://api.sumup.com/v0.1/merchants/MC0X0ABC/readers/rdr_3MSAFM23CK82VSTT4BN6RWSQ65/checkout \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "return_url": "https://example.com/sumup/webhook",
  "total_amount": {
    "currency": "EUR",
    "minor_unit": 2,
    "value": 1500
  }
}
'

import SumUp from "@sumup/sdk";

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

  const result = await client.readers.createCheckout(
    "MC0X0ABC",
    "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
    {
      "return_url": "https://example.com/sumup/webhook",
      "total_amount": {
        "currency": "EUR",
        "minor_unit": 2,
        "value": 1500
      }
    }
  );
  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.Readers.CreateCheckoutAsync(
            "your-merchant-code",
            "your-reader-id",
            new CreateReaderCheckoutRequest
            {
                ReturnUrl = "https://example.com/sumup/webhook",
                TotalAmount = new CreateReaderCheckoutRequestTotalAmount
                {
                    Currency = "EUR",
                    MinorUnit = 2,
                    Value = 1500,
                },
            });

        Console.WriteLine(response.StatusCode);
    }
}

import com.sumup.sdk.SumUpClient;

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

    var result = client.readers().createCheckout(
            "MC0X0ABC",
            "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
            com.sumup.sdk.models.CreateReaderCheckoutRequest.builder()
                .returnUrl("https://example.com/sumup/webhook")
                .totalAmount(com.sumup.sdk.models.Money.builder()
                .currency("EUR")
                .minorUnit(2L)
                .value(1500L)
                .build())
                .build()
        );
    System.out.println(result);
  }
}

import os

import sumup

client = sumup.Sumup(api_key=os.environ["SUMUP_API_KEY"])
result = client.readers.create_checkout(
    "MC0X0ABC",
    "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
    return_url="https://example.com/sumup/webhook",
    total_amount={
        "currency": "EUR",
        "minor_unit": 2,
        "value": 1500,
    },
)
print(result)

<?php

declare(strict_types=1);

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

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

$body = [
    'return_url' => 'https://example.com/sumup/webhook',
    'total_amount' => [
        'currency' => 'EUR',
        'minor_unit' => 2,
        'value' => 1500,
    ],
];

$result = $sumup->readers()->createCheckout(
    'MC0X0ABC',
    'rdr_3MSAFM23CK82VSTT4BN6RWSQ65',
    $body,
);

var_dump($result);

package main

import (
	"context"
	"fmt"

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

func main() {
	client := sumup.NewClient()
	result, err := client.Readers.CreateCheckout(context.TODO(), "MC0X0ABC", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", sumup.ReadersCreateCheckoutParams{
		ReturnURL: new("https://example.com/sumup/webhook"),
		TotalAmount: sumup.CreateCheckoutRequestTotalAmount{
			Currency:  "EUR",
			MinorUnit: 2,
			Value:     1500,
		},
	})
	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::readers::CreateCheckoutRequest::builder()
        .return_url("https://example.com/sumup/webhook")
        .total_amount(
            sumup::resources::readers::CreateCheckoutRequestTotalAmount::builder()
                .currency("EUR")
                .minor_unit(2i64)
                .value(1500i64)
                .build(),
        )
        .build();
    let response = client
        .readers()
        .create_checkout("MERCHANT_CODE", "READER_ID", body)
        .await
        .expect("create_checkout request failed");
    println!("{response:#?}");
}

Response example

{
  "data": {
    "checkout_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "client_transaction_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

{
  "errors": {
    "detail": "Invalid affiliate key.",
    "type": "INVALID_AFFILIATE_KEY"
  }
}

{
  "errors": {
    "detail": "string",
    "type": "string"
  }
}

{
  "errors": {
    "detail": "Not Found"
  }
}

{
  "DataValidation": {
    "description": "Validation errors for the informed fields.",
    "value": {
      "errors": {
        "card_type": [
          "is invalid"
        ],
        "installments": [
          "not allowed"
        ],
        "return_url": [
          "must be a valid URL"
        ],
        "tip_rates": [
          "has an invalid entry"
        ],
        "total_amount": [
          "must be greater than 0"
        ]
      }
    }
  },
  "InstallmentsTooLow": {
    "description": "Error returned when installments is not within the allowed range.",
    "value": {
      "errors": {
        "installments": [
          "is invalid"
        ]
      }
    }
  },
  "PaymentMethodNotAllowed": {
    "description": "Error returned when the requested payment method is not supported for the merchant (e.g. pix for non-BR merchants).",
    "value": {
      "errors": {
        "detail": "Payment method not allowed for this merchant.",
        "type": "PAYMENT_METHOD_NOT_ALLOWED"
      }
    }
  },
  "ReaderBusy": {
    "description": "Error returned when a checkout was requested in the last 60 seconds.",
    "value": {
      "errors": {
        "detail": "There is a pending checkout for the device.",
        "type": "READER_BUSY"
      }
    }
  },
  "ReaderOffline": {
    "description": "Error returned when the target device is not online.",
    "value": {
      "errors": {
        "detail": "The device is offline.",
        "type": "READER_OFFLINE"
      }
    }
  }
}