Skip to content
SumUp Developer

Readers

SumUp API reference and code samples.

Readers

A reader represents a device that accepts payments. You can use the SumUp Solo to accept in-person payments.

The Reader object

A physical card reader device that can accept in-person payments.

Reader

  • id string min length: 30max length: 30 required

    Unique identifier of the object.

    Note that this identifies the instance of the physical devices pairing with your SumUp account. If you delete a reader, and pair the device again, the ID will be different. Do not use this ID to refer to a physical device.

    Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
  • name string max length: 500 required

    Custom human-readable, user-defined name for easier identification of the reader.

    Example: "Frontdesk"
  • status string required

    The status of the reader object gives information about the current state of the reader.

    Possible values:

    • unknown - The reader status is unknown.
    • processing - The reader is created and waits for the physical device to confirm the pairing.
    • paired - The reader is paired with a merchant account and can be used with SumUp APIs.
    • expired - The pairing is expired and no longer usable with the account. The resource needs to get recreated.
    Example: "paired"
  • device object required

    Information about the underlying physical device.

     Show attributes
     Close
    Attributes
    • identifier string required

      A unique identifier of the physical device (e.g. serial number).

      Example: "U1DT3NA00-CN"
    • model string required
      Options:  solo virtual-solo

      Identifier of the model of the device.

      Example: "solo"
  • metadata object max properties: 64

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

    Example: {}
  • service_account_id string uuid

    Identifier of the system-managed service account associated with this reader. Present only for readers that are already paired. This field is currently in beta and may change.

  • created_at string date-time required

    The timestamp of when the reader was created.

    Example: "2023-01-18T15:16:17Z"
  • updated_at string date-time required

    The timestamp of when the reader was last updated.

    Example: "2023-01-20T15:16:17Z"
The Reader object
{
  "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
  "name": "Frontdesk",
  "status": "paired",
  "device": {
    "identifier": "U1DT3NA00-CN",
    "model": "solo"
  },
  "metadata": {},
  "service_account_id": null,
  "created_at": "2023-01-18T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
}
Readers

List Readers

List all readers of the merchant.

Required scopes: readers.read
Required permissions: readers_list

Path Parameters

  • merchant_code string required

    Short unique identifier for the merchant.

    Example: "MK10CL2A"

Response 200

  • items []object required

    A physical card reader device that can accept in-person payments.

     Show attributes
     Close
    Reader
    • id string min length: 30max length: 30 required

      Unique identifier of the object.

      Note that this identifies the instance of the physical devices pairing with your SumUp account. If you delete a reader, and pair the device again, the ID will be different. Do not use this ID to refer to a physical device.

      Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
    • name string max length: 500 required

      Custom human-readable, user-defined name for easier identification of the reader.

      Example: "Frontdesk"
    • status string required

      The status of the reader object gives information about the current state of the reader.

      Possible values:

      • unknown - The reader status is unknown.
      • processing - The reader is created and waits for the physical device to confirm the pairing.
      • paired - The reader is paired with a merchant account and can be used with SumUp APIs.
      • expired - The pairing is expired and no longer usable with the account. The resource needs to get recreated.
      Example: "paired"
    • device object required

      Information about the underlying physical device.

       Show attributes
       Close
      Attributes
      • identifier string required

        A unique identifier of the physical device (e.g. serial number).

        Example: "U1DT3NA00-CN"
      • model string required
        Options:  solo virtual-solo

        Identifier of the model of the device.

        Example: "solo"
    • metadata object max properties: 64

      Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

      Example: {}
    • service_account_id string uuid

      Identifier of the system-managed service account associated with this reader. Present only for readers that are already paired. This field is currently in beta and may change.

    • created_at string date-time required

      The timestamp of when the reader was created.

      Example: "2023-01-18T15:16:17Z"
    • updated_at string date-time required

      The timestamp of when the reader was last updated.

      Example: "2023-01-20T15:16:17Z"
GET /v0.1/merchants/{merchant_code}/readers 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.readers.list("MK10CL2A");
using SumUp;


var client = new SumUpClient();


var result = await client.Readers.ListAsync(
    "MK10CL2A"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.readers().listReaders(
  "MK10CL2A"
);
from sumup import Sumup


client = Sumup()


result = client.readers.list("MK10CL2A")
$sumup = new \SumUp\SumUp();


$result = $sumup->readers->list('MK10CL2A');
client := sumup.NewClient()


result, err := client.Readers.List(context.Background(), "MK10CL2A")
use sumup::Client;


let client = Client::default();


let result = client.readers().list("MK10CL2A").await;
List Readers response
{
  "items": [
    {
      "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
      "name": "Frontdesk",
      "status": "paired",
      "device": {
        "identifier": "U1DT3NA00-CN",
        "model": "solo"
      },
      "metadata": {},
      "service_account_id": null,
      "created_at": "2023-01-18T15:16:17Z",
      "updated_at": "2023-01-20T15:16:17Z"
    }
  ]
}
Readers

Create a Reader

Create a new Reader for the merchant account.

Required scopes: readers.write
Required permissions: readers_create

Path Parameters

  • merchant_code string required

    Short unique identifier for the merchant.

    Example: "MK10CL2A"

Body Parameters

  • pairing_code string min length: 8max length: 9 required

    The pairing code is a 8 or 9 character alphanumeric string that is displayed on a SumUp Device after initiating the pairing. It is used to link the physical device to the created pairing.

    Example: "4WLFDSBF"
  • name string max length: 500 required

    Custom human-readable, user-defined name for easier identification of the reader.

    Example: "Frontdesk"
  • metadata object max properties: 64

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

    Example: {}

Reader

  • id string min length: 30max length: 30 required

    Unique identifier of the object.

    Note that this identifies the instance of the physical devices pairing with your SumUp account. If you delete a reader, and pair the device again, the ID will be different. Do not use this ID to refer to a physical device.

    Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
  • name string max length: 500 required

    Custom human-readable, user-defined name for easier identification of the reader.

    Example: "Frontdesk"
  • status string required

    The status of the reader object gives information about the current state of the reader.

    Possible values:

    • unknown - The reader status is unknown.
    • processing - The reader is created and waits for the physical device to confirm the pairing.
    • paired - The reader is paired with a merchant account and can be used with SumUp APIs.
    • expired - The pairing is expired and no longer usable with the account. The resource needs to get recreated.
    Example: "paired"
  • device object required

    Information about the underlying physical device.

     Show attributes
     Close
    Attributes
    • identifier string required

      A unique identifier of the physical device (e.g. serial number).

      Example: "U1DT3NA00-CN"
    • model string required
      Options:  solo virtual-solo

      Identifier of the model of the device.

      Example: "solo"
  • metadata object max properties: 64

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

    Example: {}
  • service_account_id string uuid

    Identifier of the system-managed service account associated with this reader. Present only for readers that are already paired. This field is currently in beta and may change.

  • created_at string date-time required

    The timestamp of when the reader was created.

    Example: "2023-01-18T15:16:17Z"
  • updated_at string date-time required

    The timestamp of when the reader was last updated.

    Example: "2023-01-20T15:16:17Z"
POST /v0.1/merchants/{merchant_code}/readers 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "pairing_code": "4WLFDSBF",
    "name": "Frontdesk"
  }'
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.readers.create("MK10CL2A", {
  pairing_code: "4WLFDSBF",
  name: "Frontdesk",
});
using SumUp;


var client = new SumUpClient();


var result = await client.Readers.CreateAsync(
    "MK10CL2A",
    new CreateReaderBody
    {
        PairingCode = "4WLFDSBF",
        Name = "Frontdesk",
    }
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.readers().createReader(
  "MK10CL2A",
  CreateReaderBody.builder()
    .pairingCode("4WLFDSBF")
    .name("Frontdesk")
    .build()
);
from sumup import Sumup


client = Sumup()


result = client.readers.create("MK10CL2A", CreateReaderBody(
  pairing_code="4WLFDSBF",
  name="Frontdesk",
))
$sumup = new \SumUp\SumUp();


$result = $sumup->readers->create('MK10CL2A', [
  'pairing_code' => '4WLFDSBF',
  'name' => 'Frontdesk',
]);
client := sumup.NewClient()


result, err := client.Readers.Create(context.Background(), "MK10CL2A", sumup.ReadersCreateParams{
  PairingCode: "4WLFDSBF",
  Name: "Frontdesk",
})
use sumup::Client;


let client = Client::default();


let result = client.readers().create("MK10CL2A", sumup::CreateReaderBody{
  pairing_code: "4WLFDSBF".to_string(),
  name: "Frontdesk".to_string(),
}).await;
Response
{
  "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
  "name": "Frontdesk",
  "status": "processing",
  "device": {
    "identifier": "U1DT3NA00-CN",
    "model": "solo"
  },
  "created_at": "2023-05-09T14:50:20.214Z",
  "updated_at": "2023-05-09T14:52:58.714Z"
}
Readers

Retrieve a Reader

Retrieve a Reader.

Required scopes: readers.read
Required permissions: readers_view

Path Parameters

  • merchant_code string required

    Short unique identifier for the merchant.

    Example: "MK10CL2A"
  • id string min length: 30max length: 30 required

    The unique identifier of the reader.

    Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"

Reader

  • id string min length: 30max length: 30 required

    Unique identifier of the object.

    Note that this identifies the instance of the physical devices pairing with your SumUp account. If you delete a reader, and pair the device again, the ID will be different. Do not use this ID to refer to a physical device.

    Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
  • name string max length: 500 required

    Custom human-readable, user-defined name for easier identification of the reader.

    Example: "Frontdesk"
  • status string required

    The status of the reader object gives information about the current state of the reader.

    Possible values:

    • unknown - The reader status is unknown.
    • processing - The reader is created and waits for the physical device to confirm the pairing.
    • paired - The reader is paired with a merchant account and can be used with SumUp APIs.
    • expired - The pairing is expired and no longer usable with the account. The resource needs to get recreated.
    Example: "paired"
  • device object required

    Information about the underlying physical device.

     Show attributes
     Close
    Attributes
    • identifier string required

      A unique identifier of the physical device (e.g. serial number).

      Example: "U1DT3NA00-CN"
    • model string required
      Options:  solo virtual-solo

      Identifier of the model of the device.

      Example: "solo"
  • metadata object max properties: 64

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

    Example: {}
  • service_account_id string uuid

    Identifier of the system-managed service account associated with this reader. Present only for readers that are already paired. This field is currently in beta and may change.

  • created_at string date-time required

    The timestamp of when the reader was created.

    Example: "2023-01-18T15:16:17Z"
  • updated_at string date-time required

    The timestamp of when the reader was last updated.

    Example: "2023-01-20T15:16:17Z"
GET /v0.1/merchants/{merchant_code}/readers/{id} 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{id} \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.readers.get("MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65");
using SumUp;


var client = new SumUpClient();


var result = await client.Readers.GetAsync(
    "MK10CL2A",
    "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.readers().getReader(
  "MK10CL2A",
  "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
);
from sumup import Sumup


client = Sumup()


result = client.readers.get("MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65")
$sumup = new \SumUp\SumUp();


$result = $sumup->readers->get('MK10CL2A', 'rdr_3MSAFM23CK82VSTT4BN6RWSQ65');
client := sumup.NewClient()


result, err := client.Readers.Get(context.Background(), "MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65")
use sumup::Client;


let client = Client::default();


let result = client.readers().get("MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65").await;
Retrieve a Reader response
{
  "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
  "name": "Frontdesk",
  "status": "paired",
  "device": {
    "identifier": "U1DT3NA00-CN",
    "model": "solo"
  },
  "metadata": {},
  "service_account_id": null,
  "created_at": "2023-01-18T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
}
Readers

Update a Reader

Update a Reader.

Required scopes: readers.write
Required permissions: readers_update

Path Parameters

  • merchant_code string required

    Short unique identifier for the merchant.

    Example: "MK10CL2A"
  • id string min length: 30max length: 30 required

    The unique identifier of the reader.

    Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"

Body Parameters

  • name string max length: 500

    Custom human-readable, user-defined name for easier identification of the reader.

    Example: "Frontdesk"
  • metadata object max properties: 64

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

    Example: {}

Reader

  • id string min length: 30max length: 30 required

    Unique identifier of the object.

    Note that this identifies the instance of the physical devices pairing with your SumUp account. If you delete a reader, and pair the device again, the ID will be different. Do not use this ID to refer to a physical device.

    Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
  • name string max length: 500 required

    Custom human-readable, user-defined name for easier identification of the reader.

    Example: "Frontdesk"
  • status string required

    The status of the reader object gives information about the current state of the reader.

    Possible values:

    • unknown - The reader status is unknown.
    • processing - The reader is created and waits for the physical device to confirm the pairing.
    • paired - The reader is paired with a merchant account and can be used with SumUp APIs.
    • expired - The pairing is expired and no longer usable with the account. The resource needs to get recreated.
    Example: "paired"
  • device object required

    Information about the underlying physical device.

     Show attributes
     Close
    Attributes
    • identifier string required

      A unique identifier of the physical device (e.g. serial number).

      Example: "U1DT3NA00-CN"
    • model string required
      Options:  solo virtual-solo

      Identifier of the model of the device.

      Example: "solo"
  • metadata object max properties: 64

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

    Example: {}
  • service_account_id string uuid

    Identifier of the system-managed service account associated with this reader. Present only for readers that are already paired. This field is currently in beta and may change.

  • created_at string date-time required

    The timestamp of when the reader was created.

    Example: "2023-01-18T15:16:17Z"
  • updated_at string date-time required

    The timestamp of when the reader was last updated.

    Example: "2023-01-20T15:16:17Z"
PATCH /v0.1/merchants/{merchant_code}/readers/{id} 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{id} \
 -X PATCH \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{}'
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.readers.update("MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", {


});
using SumUp;


var client = new SumUpClient();


var result = await client.Readers.UpdateAsync(
    "MK10CL2A",
    "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
    new UpdateReaderBody
    {


    }
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.readers().updateReader(
  "MK10CL2A",
  "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
  UpdateReaderBody.builder()


    .build()
);
from sumup import Sumup


client = Sumup()


result = client.readers.update("MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", UpdateReaderBody(


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


$result = $sumup->readers->update('MK10CL2A', 'rdr_3MSAFM23CK82VSTT4BN6RWSQ65', [


]);
client := sumup.NewClient()


result, err := client.Readers.Update(context.Background(), "MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", sumup.ReadersUpdateParams{


})
use sumup::Client;


let client = Client::default();


let result = client.readers().update("MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", sumup::UpdateReaderBody{}).await;
Update a Reader response
{
  "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
  "name": "Frontdesk",
  "status": "paired",
  "device": {
    "identifier": "U1DT3NA00-CN",
    "model": "solo"
  },
  "metadata": {},
  "service_account_id": null,
  "created_at": "2023-01-18T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
}
Readers

Delete a reader

Delete a reader.

Required scopes: readers.write
Required permissions: readers_delete

Path Parameters

  • merchant_code string required

    Short unique identifier for the merchant.

    Example: "MK10CL2A"
  • id string min length: 30max length: 30 required

    The unique identifier of the reader.

    Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
DELETE /v0.1/merchants/{merchant_code}/readers/{id} 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{id} \
 -X DELETE \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.readers.delete("MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65");
using SumUp;


var client = new SumUpClient();


var result = await client.Readers.DeleteAsync(
    "MK10CL2A",
    "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.readers().deleteReader(
  "MK10CL2A",
  "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
);
from sumup import Sumup


client = Sumup()


result = client.readers.delete("MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65")
$sumup = new \SumUp\SumUp();


$result = $sumup->readers->delete('MK10CL2A', 'rdr_3MSAFM23CK82VSTT4BN6RWSQ65');
client := sumup.NewClient()


result, err := client.Readers.Delete(context.Background(), "MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65")
use sumup::Client;


let client = Client::default();


let result = client.readers().delete("MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65").await;
Readers

Get a Reader Status

Provides the last known status for a Reader.

This endpoint allows you to retrieve updates from the connected card reader, including the current screen being displayed during the payment process and the device status (battery level, connectivity, and update state).

Supported States

  • IDLE – Reader ready for next transaction
  • SELECTING_TIP – Waiting for tip input
  • WAITING_FOR_CARD – Awaiting card insert/tap
  • WAITING_FOR_PIN – Waiting for PIN entry
  • WAITING_FOR_SIGNATURE – Waiting for customer signature
  • UPDATING_FIRMWARE – Firmware update in progress

Device Status

  • ONLINE – Device connected and operational
  • OFFLINE – Device disconnected (last state persisted)

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

Required scopes: readers.read
Required permissions: readers_view

Path Parameters

  • merchant_code string required

    Merchant Code

  • reader_id string required

    The unique identifier of the Reader

StatusResponse

  • data object required
     Show attributes
     Close
    Attributes
    • battery_level number minimum: 0maximum: 100

      Battery level percentage

      Example: 10.5
    • battery_temperature integer

      Battery temperature in Celsius

      Example: 35
    • connection_type string
      Options:  btle edge gprs lte umts usb Wi-Fi

      Type of connection used by the device

      Example: "Wi-Fi"
    • firmware_version string

      Firmware version of the device

      Example: "3.3.3.21"
    • last_activity string date-time

      Timestamp of the last activity from the device

      Example: "2025-09-25T15:20:00Z"
    • state string
      Options:  IDLE SELECTING_TIP WAITING_FOR_CARD WAITING_FOR_PIN WAITING_FOR_SIGNATURE UPDATING_FIRMWARE

      Latest state of the device

      Example: "IDLE"
    • status string required
      Options:  ONLINE OFFLINE

      Status of a device

      Example: "ONLINE"
GET /v0.1/merchants/{merchant_code}/readers/{reader_id}/status 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{reader_id}/status \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.readers.getStatus("merchant_code", "reader_id");
using SumUp;


var client = new SumUpClient();


var result = await client.Readers.GetStatusAsync(
    "merchant_code",
    "reader_id"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.readers().getReaderStatus(
  "merchant_code",
  "reader_id"
);
from sumup import Sumup


client = Sumup()


result = client.readers.get_status("merchant_code", "reader_id")
$sumup = new \SumUp\SumUp();


$result = $sumup->readers->getStatus('merchant_code', 'reader_id');
client := sumup.NewClient()


result, err := client.Readers.GetStatus(context.Background(), "merchant_code", "reader_id")
use sumup::Client;


let client = Client::default();


let result = client.readers().get_status("merchant_code", "reader_id").await;
Get a Reader Status response
{
  "data": {
    "battery_level": 10,
    "battery_temperature": 35,
    "connection_type": "Wi-Fi",
    "firmware_version": "3.3.3.21",
    "last_activity": "2025-09-25T15:20:00Z",
    "state": "IDLE",
    "status": "ONLINE"
  }
}
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 stared 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.

Required scopes: readers.write
Required permissions: readers_checkout_create

Path Parameters

  • merchant_code string required

    Merchant Code

  • reader_id string required

    The unique identifier of the Reader

CreateReaderCheckoutRequest

  • affiliate object nullable

    Affiliate metadata for the transaction. It is a field that allow for integrators to track the source of the transaction.

     Show attributes
     Close
    Affiliate
    • app_id string required

      Application ID of the affiliate. It is a unique identifier for the application and should be set by the integrator in the Affiliate Keys page.

      Example: "com.example.app"
    • foreign_transaction_id string required

      Foreign transaction ID of the affiliate. It is a unique identifier for the transaction. It can be used later to fetch the transaction details via the Transactions API.

      Example: "19e12390-72cf-4f9f-80b5-b0c8a67fa43f"
    • key string required

      Key of the affiliate. It is a unique identifier for the key and should be generated by the integrator in the Affiliate Keys page.

      Example: "123e4567-e89b-12d3-a456-426614174000"
    • tags object

      Additional metadata for the transaction. It is key-value object that can be associated with the transaction.

      Example: {"custom_key_1":"custom_value_1","custom_key_2":"custom_value_2"}
  • card_type string
    Options:  credit debit

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

    Example: "credit"
  • description string

    Description of the checkout to be shown in the Merchant Sales

  • installments integer minimum: 1nullable

    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.

    Example: 1
  • return_url string uri

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

    Example: "https://www.example.com"
  • tip_rates []number

    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_timeout integer 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
  • total_amount object required

    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.

     Show attributes
     Close
    Money
    • currency string required

      Currency ISO 4217 code

      Example: "EUR"
    • minor_unit integer minimum: 0 required

      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
    • value integer minimum: 0 required

      Integer value of the amount.

      Example: 1000
    Example: {"currency":"EUR","minor_unit":2,"value":1000}

CreateReaderCheckoutResponse

  • data object required
     Show attributes
     Close
    Attributes
    • client_transaction_id string required

      The client transaction ID is a unique identifier for the transaction that is generated for the client.

      It can be used later to fetch the transaction details via the Transactions API.

      Example: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
POST /v0.1/merchants/{merchant_code}/readers/{reader_id}/checkout 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{reader_id}/checkout \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "total_amount": {
      "currency": "EUR",
      "minor_unit": 2,
      "value": 5033
    }
  }'
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.readers.createCheckout("merchant_code", "reader_id", {
  total_amount: {
    currency: "EUR",
    minor_unit: 2,
    value: 5033,
  },
});
using SumUp;


var client = new SumUpClient();


var result = await client.Readers.CreateCheckoutAsync(
    "merchant_code",
    "reader_id",
    new CreateReaderCheckoutRequest
    {
        TotalAmount = new Money
        {
            Currency = "EUR",
            MinorUnit = 2,
            Value = 5033,
        },
    }
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.readers().createReaderCheckout(
  "merchant_code",
  "reader_id",
  CreateReaderCheckoutRequest.builder()
    .totalAmount(Money.builder()
        .currency("EUR")
        .minorUnit(2)
        .value(5033)
        .build())
    .build()
);
from sumup import Sumup


client = Sumup()


result = client.readers.create_checkout("merchant_code", "reader_id", CreateReaderCheckoutBody(
  total_amount=Money(
    currency="EUR",
    minor_unit=2,
    value=5033,
  ),
))
$sumup = new \SumUp\SumUp();


$result = $sumup->readers->createCheckout('merchant_code', 'reader_id', [
  'total_amount' => [
      'currency' => 'EUR',
      'minor_unit' => 2,
      'value' => 5033,
    ],
]);
client := sumup.NewClient()


result, err := client.Readers.CreateCheckout(context.Background(), "merchant_code", "reader_id", sumup.ReadersCreateCheckoutParams{
  TotalAmount: sumup.Money{
    Currency: "EUR",
    MinorUnit: 2,
    Value: 5033,
  },
})
use sumup::Client;


let client = Client::default();


let result = client.readers().create_checkout("merchant_code", "reader_id", sumup::CreateReaderCheckoutBody{
  total_amount: sumup::Money {
    currency: "EUR".to_string(),
    minor_unit: 2,
    value: 5033,
  },
}).await;
Create a Reader Checkout response
{
  "data": {
    "client_transaction_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}
Readers

Terminate a Reader Checkout

Terminate a Reader Checkout stops the current transaction on the target device.

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

There are some caveats when using this endpoint:

  • The target device must be online, otherwise terminate won't be accepted
  • The action will succeed only if the device is waiting for cardholder action: e.g: waiting for card, waiting for PIN, etc.
  • There is no confirmation of the termination.

If a transaction is successfully terminated and return_url was provided on Checkout, the transaction status will be sent as failed to the provided URL.

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

Required scopes: readers.write
Required permissions: readers_checkout_create

Path Parameters

  • merchant_code string required

    Merchant Code

  • reader_id string required

    The unique identifier of the Reader

POST /v0.1/merchants/{merchant_code}/readers/{reader_id}/terminate 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{reader_id}/terminate \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.readers.terminateCheckout("merchant_code", "reader_id");
using SumUp;


var client = new SumUpClient();


var result = await client.Readers.TerminateCheckoutAsync(
    "merchant_code",
    "reader_id"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.readers().createReaderTerminate(
  "merchant_code",
  "reader_id"
);
from sumup import Sumup


client = Sumup()


result = client.readers.terminate_checkout("merchant_code", "reader_id")
$sumup = new \SumUp\SumUp();


$result = $sumup->readers->terminateCheckout('merchant_code', 'reader_id');
client := sumup.NewClient()


result, err := client.Readers.TerminateCheckout(context.Background(), "merchant_code", "reader_id")
use sumup::Client;


let client = Client::default();


let result = client.readers().terminate_checkout("merchant_code", "reader_id").await;