Skip to content
SumUp Developer

Readers

SumUp API reference and code samples.

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.

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

    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 required max length: 500

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

    Example: "Frontdesk"
  • status string required
    Options:  unknownprocessingpairedexpired

    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:  solovirtual-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 format: 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 required format: date-time

    The timestamp of when the reader was created.

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

    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

GET /v0.1/merchants/{merchant_code}/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

Returns a list Reader objects. See Reader object .

  • items []Reader required

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

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

      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 required max length: 500

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

      Example: "Frontdesk"
    • status string required
      Options:  unknownprocessingpairedexpired

      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:  solovirtual-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 format: 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 required format: date-time

      The timestamp of when the reader was created.

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

      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

POST /v0.1/merchants/{merchant_code}/readers

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 required min length: 8, max length: 9

    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 required 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: {}

Response

Returns the Reader object if the creation succeeded. See Reader object .

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

    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 required max length: 500

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

    Example: "Frontdesk"
  • status string required
    Options:  unknownprocessingpairedexpired

    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:  solovirtual-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 format: 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 required format: date-time

    The timestamp of when the reader was created.

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

    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"
}

Content-Type: application/problem+json

The request is invalid.

  • type string required format: uri

    A URI reference that identifies the problem type.

    Example: "https://developer.sumup.com/problem/not-found"
  • title string

    A short, human-readable summary of the problem type.

    Example: "Requested resource couldn't be found."
  • status integer

    The HTTP status code generated by the origin server for this occurrence of the problem.

    Example: 404
  • detail string

    A human-readable explanation specific to this occurrence of the problem.

    Example: "The requested resource doesn't exist or does not belong to you."
  • instance string format: uri

    A URI reference that identifies the specific occurrence of the problem.
Error 400
{
  "type": "https://developer.sumup.com/problem/not-found",
  "title": "Requested resource couldn't be found.",
  "status": 404,
  "detail": "The requested resource doesn't exist or does not belong to you.",
  "instance": null
}
Readers

Retrieve a Reader

GET /v0.1/merchants/{merchant_code}/readers/{id}

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 required min length: 30, max length: 30

    The unique identifier of the reader.

    Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"

Response

Returns a Reader object for a valid identifier. See Reader object .

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

    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 required max length: 500

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

    Example: "Frontdesk"
  • status string required
    Options:  unknownprocessingpairedexpired

    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:  solovirtual-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 format: 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 required format: date-time

    The timestamp of when the reader was created.

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

    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"
}

Content-Type: application/problem+json

The requested Reader resource does not exist.

  • type string required format: uri

    A URI reference that identifies the problem type.

    Example: "https://developer.sumup.com/problem/not-found"
  • title string

    A short, human-readable summary of the problem type.

    Example: "Requested resource couldn't be found."
  • status integer

    The HTTP status code generated by the origin server for this occurrence of the problem.

    Example: 404
  • detail string

    A human-readable explanation specific to this occurrence of the problem.

    Example: "The requested resource doesn't exist or does not belong to you."
  • instance string format: uri

    A URI reference that identifies the specific occurrence of the problem.
Error 404
{
  "type": "https://developer.sumup.com/problem/not-found",
  "title": "Requested resource couldn't be found.",
  "status": 404,
  "detail": "The requested resource doesn't exist or does not belong to you.",
  "instance": null
}
Readers

Update a Reader

PATCH /v0.1/merchants/{merchant_code}/readers/{id}

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 required min length: 30, max length: 30

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

Response

Returns the updated Reader object if the update succeeded. See Reader object .

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

    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 required max length: 500

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

    Example: "Frontdesk"
  • status string required
    Options:  unknownprocessingpairedexpired

    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:  solovirtual-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 format: 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 required format: date-time

    The timestamp of when the reader was created.

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

    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"
}

Content-Type: application/problem+json

The request isn't sufficiently authorized to modify the reader.

  • type string required format: uri

    A URI reference that identifies the problem type.

    Example: "https://developer.sumup.com/problem/not-found"
  • title string

    A short, human-readable summary of the problem type.

    Example: "Requested resource couldn't be found."
  • status integer

    The HTTP status code generated by the origin server for this occurrence of the problem.

    Example: 404
  • detail string

    A human-readable explanation specific to this occurrence of the problem.

    Example: "The requested resource doesn't exist or does not belong to you."
  • instance string format: uri

    A URI reference that identifies the specific occurrence of the problem.
Error 403
{
  "type": "https://developer.sumup.com/problem/not-found",
  "title": "Requested resource couldn't be found.",
  "status": 404,
  "detail": "The requested resource doesn't exist or does not belong to you.",
  "instance": null
}
Readers

Delete a reader

DELETE /v0.1/merchants/{merchant_code}/readers/{id}

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 required min length: 30, max length: 30

    The unique identifier of the reader.

    Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"

Response

Returns empty response.

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;

Content-Type: application/problem+json

The requested Reader resource does not exist.

  • type string required format: uri

    A URI reference that identifies the problem type.

    Example: "https://developer.sumup.com/problem/not-found"
  • title string

    A short, human-readable summary of the problem type.

    Example: "Requested resource couldn't be found."
  • status integer

    The HTTP status code generated by the origin server for this occurrence of the problem.

    Example: 404
  • detail string

    A human-readable explanation specific to this occurrence of the problem.

    Example: "The requested resource doesn't exist or does not belong to you."
  • instance string format: uri

    A URI reference that identifies the specific occurrence of the problem.
Error 404
{
  "type": "https://developer.sumup.com/problem/not-found",
  "title": "Requested resource couldn't be found.",
  "status": 404,
  "detail": "The requested resource doesn't exist or does not belong to you.",
  "instance": null
}
Readers

Get a Reader Status

GET /v0.1/merchants/{merchant_code}/readers/{reader_id}/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

Response

Response with the device status.

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

      Battery level percentage

      Example: 10.5
    • battery_temperature integer

      Battery temperature in Celsius

      Example: 35
    • connection_type string
      Options:  btleedgegprslteumtsusbWi-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 format: date-time

      Timestamp of the last activity from the device

      Example: "2025-09-25T15:20:00Z"
    • state string
      Options:  IDLESELECTING_TIPWAITING_FOR_CARDWAITING_FOR_PINWAITING_FOR_SIGNATUREUPDATING_FIRMWARE

      Latest state of the device

      Example: "IDLE"
    • status string required
      Options:  ONLINEOFFLINE

      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"
  }
}

Content-Type: application/problem+json

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

  • type string required format: uri

    A URI reference that identifies the problem type.

    Example: "https://developer.sumup.com/problem/not-found"
  • title string

    A short, human-readable summary of the problem type.

    Example: "Requested resource couldn't be found."
  • status integer

    The HTTP status code generated by the origin server for this occurrence of the problem.

    Example: 404
  • detail string

    A human-readable explanation specific to this occurrence of the problem.

    Example: "The requested resource doesn't exist or does not belong to you."
  • instance string format: uri

    A URI reference that identifies the specific occurrence of the problem.
Error 400
{
  "type": "https://developer.sumup.com/problem/not-found",
  "title": "Requested resource couldn't be found.",
  "status": 404,
  "detail": "The requested resource doesn't exist or does not belong to you.",
  "instance": null
}
Readers

Create a Reader Checkout

POST /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 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

Body Parameters

  • affiliate Affiliate 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:  creditdebit

    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: 1, 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.

    Example: 1
  • return_url string format: 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: 30, maximum: 120, default: 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 Money 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 required 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
    • value integer required minimum: 0

      Integer value of the amount.

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

Response

The Checkout got successfully created for the given reader.

  • 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"
  }
}

Content-Type: application/problem+json

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

  • type string required format: uri

    A URI reference that identifies the problem type.

    Example: "https://developer.sumup.com/problem/not-found"
  • title string

    A short, human-readable summary of the problem type.

    Example: "Requested resource couldn't be found."
  • status integer

    The HTTP status code generated by the origin server for this occurrence of the problem.

    Example: 404
  • detail string

    A human-readable explanation specific to this occurrence of the problem.

    Example: "The requested resource doesn't exist or does not belong to you."
  • instance string format: uri

    A URI reference that identifies the specific occurrence of the problem.
Error 400
{
  "type": "https://developer.sumup.com/problem/not-found",
  "title": "Requested resource couldn't be found.",
  "status": 404,
  "detail": "The requested resource doesn't exist or does not belong to you.",
  "instance": null
}
Readers

Terminate a Reader Checkout

POST /v0.1/merchants/{merchant_code}/readers/{reader_id}/terminate

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

Response

Returns empty response.

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;

Content-Type: application/problem+json

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

  • type string required format: uri

    A URI reference that identifies the problem type.

    Example: "https://developer.sumup.com/problem/not-found"
  • title string

    A short, human-readable summary of the problem type.

    Example: "Requested resource couldn't be found."
  • status integer

    The HTTP status code generated by the origin server for this occurrence of the problem.

    Example: 404
  • detail string

    A human-readable explanation specific to this occurrence of the problem.

    Example: "The requested resource doesn't exist or does not belong to you."
  • instance string format: uri

    A URI reference that identifies the specific occurrence of the problem.
Error 400
{
  "type": "https://developer.sumup.com/problem/not-found",
  "title": "Requested resource couldn't be found.",
  "status": 404,
  "detail": "The requested resource doesn't exist or does not belong to you.",
  "instance": null
}