SUsumup
Readers

Create a Reader Checkout

Changed on

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.

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

Request

  • Base URL
    https://api.sumup.com
  • URL
    https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{reader_id}/checkout
  • Auth
    • HTTP bearer
    • or OAuth 2
      Authorization code: https://api.sumup.com/authorize
      Token URL: https://api.sumup.com/token scopes: readers.write

Path parameters

merchant_codestring required

Merchant Code

reader_idstring required

The unique identifier of the Reader

Request body

card_type'credit' | 'debit'

The card type of the card used for the transaction. It is required only for some countries (e.g: Brazil).

descriptionstring

Description of the checkout to be shown in the Merchant Sales

installmentsinteger nullable

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.

payment_type'card' | 'pix'

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.

return_urlstring uri

Webhook URL to which the payment result will be sent. It must be a HTTPS url.

tip_ratesnumber[]

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

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 request

{
  "aade": {
    "provider_id": "123",
    "signature": "QjcxRDdBNTU1MDcyRTNFRTREMkZEM0Y0NTdBMjkxMTU4MzBFNkNCQTs7MjAyNTExMTIyMTQ3MTM7Nzk2OzEwNDs5MDA7OTAwOzU0ODg5MDM5",
    "signature_data": "B71D7A555072E3EE4D2FD3F457A29115830E6CBA;;20251112214713;796;104;900;900;54889039"
  },
  "affiliate": {
    "app_id": "com.example.app",
    "foreign_transaction_id": "123456",
    "key": "ef7b684a-d6f4-4e93-9b1b-6acdd6564a8e",
    "tags": {
      "custom_key_1": "custom_value_1",
      "custom_key_2": "custom_value_2"
    }
  },
  "card_type": "debit",
  "description": "This is a description...",
  "installments": 1,
  "return_url": "https://webhook.site/e21ddbb0-42c4-4358-a981-f5a95cd86fb5",
  "tip_rates": [
    0.05,
    0.1,
    0.15
  ],
  "tip_timeout": 60,
  "total_amount": {
    "currency": "EUR",
    "minor_unit": 2,
    "value": 5033
  }
}

Response

The Checkout got successfully created for the given reader.

Example response

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

Changes

  • 38138e18acd1Revision changes
    • breaking

      the request property's minItems was increased to 3

    • warning

      the / request property's max was set to 1.00

    • warning

      the / request property's min was set to 0.01

    • info

      added the new optional request property

    • info

      the request property / became optional

  • f50e1dc97523Revision changes
    • info

      added the optional property / to the response with the status