Readers

Create a Reader 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.

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

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. Is 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 support installments. Otherwise, the checkout will be rejected.

return_urlstring uri

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

tip_ratesnumber[]

List of tipping rates to be displayed to the cardholder. The rates are in percentage and should be between 0.01 and 0.99. The list should be sorted in ascending order.

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": {}
  },
  "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

Changed in 5 of the 53 revisions of this API.116

Aug 3, 2026f50e1dc975231See the full diff
- ○
  added the optional property data/checkout_id to the response with the 201 status
  response-optional-property-added
This revision also has 5 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Apr 8, 202696b3b0180cb31See the full diff
- ○
  added the new optional request property aade
  new-optional-request-property
Mar 11, 2026cd79d83b07e07See the full diff
- ○
  added the media type application/problem+json for the response with the status 400
  response-media-type-added
- ○
  added the media type application/problem+json for the response with the status 401
  response-media-type-added
- ○
  added the media type application/problem+json for the response with the status 422
  response-media-type-added
- ○
  added the non-success response with the status 404
  response-non-success-status-added
- ○
  removed the non-success response with the status 500
  response-non-success-status-removed
- ○
  removed the non-success response with the status 502
  response-non-success-status-removed
- ○
  removed the non-success response with the status 504
  response-non-success-status-removed
This revision also has 3 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Feb 25, 2026bef1083e05805See the full diff
- ○
  added the required property errors/type to the response with the 400 status
  response-required-property-added
- ○
  added the required property errors/type to the response with the 401 status
  response-required-property-added
- ○
  added the required property errors/type to the response with the 500 status
  response-required-property-added
- ○
  added the required property errors/type to the response with the 502 status
  response-required-property-added
- ○
  added the required property errors/type to the response with the 504 status
  response-required-property-added
This revision also has 10 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Dec 11, 2025b8fb7c9463b812See the full diff
- ●
  the installments request property's min was set to 1.00
  request-property-min-set
- ○
  the request property affiliate became nullable
  request-property-became-nullable
- ○
  the request property installments became nullable
  request-property-became-nullable
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history