Update Reader Settings

PATCH/v0.1/merchants/{merchant_code}/readers/{reader_id}/settings

Updates the menu lock settings for a Solo reader. The reader must be online. A successful response confirms that the reader applied the update.

Include at least one of menu_lock.enabled or menu_lock.passcode. Omitted settings keep their current values. The response contains only the settings included in the request.

When enabling menu lock for a reader without a PIN, include a four-digit PIN in menu_lock.passcode in the same request.

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
The merchant code of the account that owns the reader.
reader_idstringrequired
The unique identifier of the reader.

Body parameters

application/jsonrequired

Menu lock settings to update.

menu_lockobjectrequired
Menu lock configuration. Provide at least one of enabled or passcode.
Show 2 properties
- enabledboolean
  Whether menu lock is enabled.
  
  Example: true
- passcodestring
  format: passwordpattern: ^[0-9]{4}$
  Four-digit PIN used to unlock the reader's menu.
  
  Example: "1234"

Responses

200application/json

Reader settings updated successfully.

dataobjectrequired
Show 2 properties
- menu_lockobjectrequired
  Settings included in the update. Omitted fields are not returned.
  
  Show 2 properties
  enabledboolean
  Whether menu lock is enabled.
  
  Example: true
  passcodestring
  format: passwordpattern: ^[0-9]{4}$
  Four-digit PIN used to unlock the reader's menu.
  
  Example: "1234"
- statusstringrequired
  Options:"applied"
  Indicates that the reader applied the settings update.
  
  Example: "applied"

400application/json

The request body is malformed.

errorsobjectrequired
Show 2 properties
- detailstringrequired
  Error message
- typestring
  Error code

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.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

{
  "detail": "Bad Request",
  "status": 400,
  "title": "Bad Request",
  "type": "https://developer.sumup.com/problem/bad-request"
}

401application/json

Unauthorized

errorsobjectrequired
Show 2 properties
- detailstringrequired
  Error message
- typestring
  Error code

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.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

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

404application/json

The reader was 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.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

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

The settings are invalid, the reader is offline, the reader model is not supported, or the reader could not apply the update.

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.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

{
  "detail": "The device is offline.",
  "status": 422,
  "title": "Reader Offline",
  "type": "https://developer.sumup.com/problem/reader-offline"
}

PATCH

Code sample

curl --request PATCH \
  --url https://api.sumup.com/v0.1/merchants/MC0X0ABC/readers/rdr_3MSAFM23CK82VSTT4BN6RWSQ65/settings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "menu_lock": {
    "enabled": true,
    "passcode": "1234"
  }
}
'

import SumUp from "@sumup/sdk";

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

  const result = await client.readers.updateReaderSettings(
    "MC0X0ABC",
    "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
    {
      "menu_lock": {
        "enabled": true,
        "passcode": "1234"
      }
    }
  );
  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.UpdateReaderSettingsAsync(
            "your-merchant-code",
            "your-reader-id",
            new UpdateReaderSettingsRequest
            {
                MenuLock = new UpdateReaderSettingsRequestMenuLock
                {
                    Enabled = true,
                    Passcode = "1234",
                },
            });

        Console.WriteLine(response.StatusCode);
    }
}

import com.sumup.sdk.SumUpClient;

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

    var result = client.readers().updateReaderSettings(
            "MC0X0ABC",
            "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
            com.sumup.sdk.models.UpdateReaderSettingsRequest.builder()
                .menuLock(com.sumup.sdk.models.UpdateReaderSettingsRequestMenuLock.builder()
                .enabled(true)
                .passcode("1234")
                .build())
                .build()
        );
    System.out.println(result);
  }
}

import os

import sumup

client = sumup.Sumup(api_key=os.environ["SUMUP_API_KEY"])
result = client.readers.update_reader_settings(
    "MC0X0ABC",
    "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
    menu_lock={
        "enabled": True,
        "passcode": "1234",
    },
)
print(result)

<?php

declare(strict_types=1);

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

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

$body = [
    'menu_lock' => [
        'enabled' => true,
        'passcode' => '1234',
    ],
];

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

var_dump($result);

package main

import (
	"context"
	"fmt"

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

func main() {
	client := sumup.NewClient()
	result, err := client.Readers.UpdateReaderSettings(context.TODO(), "MC0X0ABC", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", sumup.ReadersUpdateReaderSettingsParams{
		MenuLock: sumup.UpdateReaderSettingsRequestMenuLock{
			Enabled:  new(true),
			Passcode: new(secret.New("1234")),
		},
	})
	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::UpdateReaderSettingsRequest::builder()
        .menu_lock(
            sumup::resources::readers::UpdateReaderSettingsRequestMenuLock::builder()
                .enabled(true)
                .passcode(sumup::secret::Secret::new("1234"))
                .build(),
        )
        .build();
    let response = client
        .readers()
        .update_reader_settings("MERCHANT_CODE", "READER_ID", body)
        .await
        .expect("update_reader_settings request failed");
    println!("{response:#?}");
}

Response example

{
  "data": {
    "menu_lock": {
      "enabled": true,
      "passcode": "1234"
    },
    "status": "applied"
  }
}

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

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

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

{
  "errors": {
    "detail": "The device is offline.",
    "type": "READER_OFFLINE"
  }
}