Create a Go Reader Payment

/v0/merchants/{merchant_code}/readers/{reader_id}/go-checkout

Initiates a payment on the SumUp Go terminal identified by the reader ID.

Use client_transaction_id as an idempotency key: retrying the request with the same value returns the result of the original payment instead of creating a duplicate.

OAuth scopes: Requires one of: payments, readers.write.

Required permissions:

readers_checkout_create

Authorization

Use one of the following alternatives:

apiKey
oauth2 with scopes paymentsreaders.write

Authorization guide

Path parameters

merchant_codestringrequired
Short unique identifier for the merchant.

Example: "MK10CL2A"
reader_idstringrequired
minLength: 30maxLength: 30
The unique identifier of the reader.

Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"

Body parameters

application/jsonrequired

Payment details to initiate on the reader.

client_transaction_idstringrequired
Caller-supplied correlation identifier, used as the idempotency key.

Example: "19e12390-72cf-4f9f-80b5-b0c8a67fa43f"
total_amountobjectrequired
Amount charged on the reader, including any tip. The amount is represented as an integer value altogether with the currency and the minor unit. For example, MXN 10.00 is represented as value 1000 with minor unit of 2.

Example: {"currency":"MXN","value":1000}
Show 2 properties
- currencystringrequired
  Currency ISO 4217 code
  
  Example: "MXN"
- valueintegerrequired
  Amount in minor units (e.g. cents).
  
  Example: 1000
affiliateobject
Optional caller-supplied context about the integration initiating the payment.
Show 2 properties
- app_idstringrequired
  Example: "com.example.app"
- keystringrequired
  Example: "123e4567-e89b-12d3-a456-426614174000"
tip_amountinteger
Portion of total_amount that is a tip, in minor units.

Example: 200

Responses

200application/json

Returns the result of the payment initiated on the reader.

dataobject
Show 2 properties
- client_transaction_idstring
  Caller-supplied correlation identifier that was provided in the request.
  
  Example: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
- transaction_codestring
  Transaction code returned by the acquirer/processing entity after processing the transaction.
  
  Example: "TEENSK4W2K"

400application/problem+json

The request is invalid.

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"

401application/problem+json

Authentication failed or missing required scope.

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"

404application/problem+json

The requested Reader resource does not exist.

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"

422application/problem+json

The request could not be processed as it violates a business rule.

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"

Code sample

curl --request POST \
  --url https://api.sumup.com/v0/merchants/MK10CL2A/readers/rdr_3MSAFM23CK82VSTT4BN6RWSQ65/go-checkout \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "affiliate": {
    "app_id": "com.example.app",
    "key": "123e4567-e89b-12d3-a456-426614174000"
  },
  "client_transaction_id": "19e12390-72cf-4f9f-80b5-b0c8a67fa43f",
  "tip_amount": 200,
  "total_amount": {
    "currency": "MXN",
    "value": 1000
  }
}
'

sumup readers go-checkout "rdr_3MSAFM23CK82VSTT4BN6RWSQ65" \
  --merchant-code "MK10CL2A" \
  --amount "10" \
  --currency "EUR" \
  --client-transaction-id "19e12390-72cf-4f9f-80b5-b0c8a67fa43f" \
  --tip-amount "2" \
  --affiliate-app-id "com.example.app" \
  --affiliate-key "123e4567-e89b-12d3-a456-426614174000"

import SumUp from "@sumup/sdk";

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

  const result = await client.readers.createGoCheckout(
    "MK10CL2A",
    "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
    {
      "client_transaction_id": "19e12390-72cf-4f9f-80b5-b0c8a67fa43f",
      "tip_amount": 200,
      "total_amount": {
        "currency": "MXN",
        "value": 1000
      }
    }
  );
  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.CreateGoCheckoutAsync(
            "your-merchant-code",
            "your-reader-id",
            new ReaderPaymentRequestParams
            {
                ClientTransactionId = "19e12390-72cf-4f9f-80b5-b0c8a67fa43f",
                TipAmount = 200,
                TotalAmount = new ReaderPaymentRequestParamsTotalAmount
                {
                    Currency = "MXN",
                    Value = 1000,
                },
            });

        Console.WriteLine(response.StatusCode);
    }
}

import com.sumup.sdk.SumUpClient;

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

    var result = client.readers().createGoCheckout(
            "MK10CL2A",
            "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
            com.sumup.sdk.models.ReaderPaymentRequestParams.builder()
                .clientTransactionId("19e12390-72cf-4f9f-80b5-b0c8a67fa43f")
                .totalAmount(com.sumup.sdk.models.ReaderPaymentRequestParamsTotalAmount.builder()
                .currency("MXN")
                .value(1000L)
                .build())
                .build()
        );
    System.out.println(result);
  }
}

import os

import sumup

client = sumup.Sumup(api_key=os.environ["SUMUP_API_KEY"])
result = client.readers.create_go_checkout(
    "MK10CL2A",
    "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
    client_transaction_id="19e12390-72cf-4f9f-80b5-b0c8a67fa43f",
    tip_amount=200,
    total_amount={
        "currency": "MXN",
        "value": 1000,
    },
)
print(result)

<?php

declare(strict_types=1);

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

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

$body = [
    'client_transaction_id' => '19e12390-72cf-4f9f-80b5-b0c8a67fa43f',
    'tip_amount' => 200,
    'total_amount' => [
        'currency' => 'MXN',
        'value' => 1000,
    ],
];

$result = $sumup->readers()->createGoCheckout(
    'MK10CL2A',
    'rdr_3MSAFM23CK82VSTT4BN6RWSQ65',
    $body,
);

var_dump($result);

package main

import (
	"context"
	"fmt"

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

func main() {
	client := sumup.NewClient()
	result, err := client.Readers.CreateGoCheckout(context.TODO(), "MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", sumup.ReadersCreateGoCheckoutParams{
		ClientTransactionID: "19e12390-72cf-4f9f-80b5-b0c8a67fa43f",
		TipAmount:           new(200),
		TotalAmount: sumup.ReaderPaymentRequestParamsTotalAmount{
			Currency: "MXN",
			Value:    1000,
		},
	})
	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::CreateGoCheckoutRequest::builder()
        .client_transaction_id("19e12390-72cf-4f9f-80b5-b0c8a67fa43f")
        .total_amount(
            sumup::resources::common::Amount::builder()
                .currency("MXN")
                .value(1000i64)
                .build(),
        )
        .build();
    let response = client
        .readers()
        .create_go_checkout("MERCHANT_CODE", "READER_ID", body)
        .await
        .expect("create_go_checkout request failed");
    println!("{response:#?}");
}

Response example

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

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

{
  "type": "https://developer.sumup.com/problem/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication credentials are missing or invalid."
}

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

{
  "type": "https://developer.sumup.com/problem/validation-error",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Validation failed."
}