Cloud API for SumUp Go

The Cloud API lets you start a transaction from an external payment system (EPS) running on any platform capable of sending HTTPS requests and complete that transaction on a Go reader.

Key advantages include:

• Compatibility with any operating system and platform
• Ability to process simultaneous transactions on multiple Go readers at once
• No distance limitation between your EPS and the Go reader; transactions can be sent remotely
• No Bluetooth connection required
• PCI compliance, ensuring secure and compliant transactions

The Cloud API integration supports:

• Debit, credit, and contactless transactions
• Pairing multiple Go readers with any SumUp account
• Naming each Go reader as desired to streamline checkout
• Wi-Fi and mobile data connectivity

Prerequisites

• Your EPS must be authorized to use the Cloud API. Refer to the authorization guide and implement the method that best fits your use case. An API key should be sufficient if you do not plan to delegate access to third parties. With OAuth, request the readers.write, payments, and transactions.history scopes.
• We recommend keeping the Go terminals plugged in when using the Cloud API.
• A Go reader is available in Australia, Mexico, and Canada. Examples on this page use CAD.

Pairing Go Reader via Cloud API

The Cloud API acts as a bridge between your EPS and the Go reader. It supports two main processes:

• Pairing a Go reader to your account
• Taking in-person payments via Go

Once the Go reader is paired to your SumUp account, your EPS can initiate a card charge request. SumUp handles the rest, providing a seamless payment experience where all card data is encrypted end-to-end. Transaction results are available by polling the Transactions API.

sequenceDiagram
    title: Cloud API Overview
    participant A as Go Reader
    participant B as Cloud API
    participant C as Your EPS
    autonumber
    A ->> B: generate pairing code
    C ->> B: Pair Reader using code
    B ->> C: Return Reader ID
    B ->> A: Display confirmation message
    C ->> B: Start payment on Reader
    B ->> C: Return transaction code
    B ->> A: Initiate payment
    A ->> A: Present payment to customer
    C ->> B: Poll the transaction status

Generate Pairing Code

To initiate a payment on the Go reader, it must be enrolled with the merchant account. This enrollment, called reader pairing, starts on the card reader by generating a pairing code and finishes when your EPS completes a pairing request using the Cloud API with that code. Both your EPS and the Go reader must be connected to the internet (not necessarily the same network).

Note

The pairing process has an expiration time of 5 minutes. If any issue occurs, the process must be restarted.

To generate a pairing code on the Go reader:

1. On the login screen, tap the Connections icon.
2. Select API and tap Connect.
3. Copy the pairing code displayed on the reader screen — you need it to pair the reader from your EPS.

Pair the Card Reader with Pairing Code

1. Send the pairing code and a name for the reader to the Create Reader endpoint. The id in the response is the reader ID you use to start payments.

   curl -X POST \
     https://api.sumup.com/v0.1/merchants/$SUMUP_MERCHANT_CODE/readers \
     -H "Authorization: Bearer $SUMUP_API_KEY" \
     -H 'Content-Type: application/json' \
     -d '{
           "pairing_code": "4WLFDSBF",
           "name": "Frontdesk"
         }'

2. Verify pairing confirmation on the reader screen. It appears for a short while, after which the reader returns to the idle screen.

Using Paired Reader

The Cloud API lets you manage transactions and readers connected to your account.

Initiate Transaction

Initiate a payment on a paired Go reader. client_transaction_id is your identifier for the payment: generate a new value, such as a UUID, for every payment and store it before you send the request.

curl -X POST \
  https://api.sumup.com/v0/merchants/$SUMUP_MERCHANT_CODE/readers/$READER_ID/go-checkout \
  -H "Authorization: Bearer $SUMUP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
        "client_transaction_id": "19e12390-72cf-4f9f-80b5-b0c8a67fa43f",
        "total_amount": {
          "currency": "CAD",
          "value": 1500
        }
      }'

Important notes:

• The target device must be online, otherwise the payment request is not accepted.
• client_transaction_id is an idempotency key. If a request times out or fails with a network error, retry it with the same value: you get the original payment back instead of charging the customer twice.
• You can identify your integration by sending your Affiliate Key in the optional affiliate object.
• The response includes a transaction_code you can use to look up the final transaction status.

Read the Create Go Reader Payment API endpoint documentation for details on the API request, examples, and parameter descriptions.

Tipping

Go supports tipping only when your EPS includes a tip_amount in the payment request. The tip is set by your system before the payment is sent to the reader — it is not entered on the Go terminal.

total_amount.value is the amount charged on the reader, in minor units, and it already includes the tip. tip_amount is the portion of that total that is a tip, in the same minor units. For a CAD 15.00 sale and a CAD 2.00 tip, set total_amount.value to 1700 and tip_amount to 200.

curl -X POST \
  https://api.sumup.com/v0/merchants/$SUMUP_MERCHANT_CODE/readers/$READER_ID/go-checkout \
  -H "Authorization: Bearer $SUMUP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
        "client_transaction_id": "19e12390-72cf-4f9f-80b5-b0c8a67fa43f",
        "total_amount": {
          "currency": "CAD",
          "value": 1700
        },
        "tip_amount": 200
      }'

Receive Transaction Results

Payment processing is asynchronous. The go-checkout response confirms that the payment was accepted and returns a transaction_code — not that the payment succeeded. Poll the Retrieve a transaction endpoint until the transaction reaches a final state.

Look up the transaction by the transaction_code from the go-checkout response:

cURL

curl "https://api.sumup.com/v2.1/merchants/$SUMUP_MERCHANT_CODE/transactions?transaction_code=$TRANSACTION_CODE" \
  -H "Authorization: Bearer $SUMUP_API_KEY"

JavaScript

const transaction = await client.transactions.get(merchantCode, {
  transaction_code: transactionCode,
});

.NET

var transaction = await client.Transactions.GetAsync(
    merchantCode,
    new TransactionsGetParams { TransactionCode = transactionCode });

Java

var transaction = client.transactions().get(
    merchantCode,
    TransactionsGetParams.builder()
        .transactionCode(transactionCode)
        .build()
);

Go

transaction, err := client.Transactions.Get(ctx, merchantCode, sumup.TransactionsGetParams{
    TransactionCode: &transactionCode,
})

Python

transaction = await client.transactions.get(
    merchant_code,
    transaction_code=transaction_code,
)

Rust

let transaction = client.transactions().get(
    &merchant_code,
    TransactionsGetParams {
        transaction_code: Some(transaction_code),
        ..Default::default()
    },
).await?;

Alternatively, pass the client_transaction_id you sent in the go-checkout request:

curl "https://api.sumup.com/v2.1/merchants/$SUMUP_MERCHANT_CODE/transactions?client_transaction_id=$CLIENT_TRANSACTION_ID" \
  -H "Authorization: Bearer $SUMUP_API_KEY"

Check the status field on the transaction resource. SUCCESSFUL means the payment completed, FAILED and CANCELLED are final, and PENDING means the customer has not finished the payment yet.

The transaction may not be available immediately after the go-checkout request. If the lookup returns 404 Not Found, keep polling — it does not mean the payment failed. Poll at a fixed interval, such as every 2 seconds, rather than in a tight loop.

List Connected Readers

List all readers connected to your merchant account.

cURL

curl https://api.sumup.com/v0.1/merchants/$SUMUP_MERCHANT_CODE/readers \
  -H "Authorization: Bearer $SUMUP_API_KEY"

JavaScript

const readers = await client.readers.list(merchantCode)

.NET

var readers = await client.Readers.ListAsync(merchantCode);

Java

var readers = client.readers().listReaders(merchantCode);

Go

readers, err := client.Readers.List(ctx, merchantCode)

Python

readers = await client.readers.list(merchant_code)

Rust

let readers = client.readers().list(&merchant_code).await?;

Read the List API endpoint documentation for details on the API request, examples, and parameter descriptions.

Unpairing Go Reader

Unpairing is only possible from your EPS via the Readers API. The Go reader does not expose an unpair action in its UI — it can only refresh its pairing status to detect whether it is still paired.

To unpair a reader from the merchant account:

1. Send a request to the Delete a Reader endpoint.
2. On the Go reader, tap the refresh icon to update the pairing status. The reader returns to the unpaired state.

What’s Next?

• Compare with the Solo Cloud API guide if you also support Solo readers.
• Browse reader compatibility for Go-specific device details.