• `sent` - the form is sent to the server for processing. The second parameter contains information about the last four digits of the card's number and the card's scheme.
• `invalid` - trying to submit the form but there are validation errors.
• `auth-screen` - the user is prompt to authenticate the payment.
• `error` - the server responded with error. The second parameter gives more information about the error.
• `success` - successful result returned by the checkout endpoint **which does not always mean the transaction was successful**. We recommend verifying the [checkout status](/api/checkouts/get) on your server. The second parameter contains the response from the [endpoint](/api/checkouts/process).
• `fail` - failed result returned by the checkout endpoint, can occur when the user cancels the payment form or the session has timed out.

• **`merchantId`** is a value provided by Google [after registration](https://developers.google.com/pay/api/web/guides/setup#registration). (not to be confused with your SumUp `merchantCode`)
• **`merchantName`** is visible to the customer on the Google Pay payment flow.

• `submit()` method will submit the form.
• `unmount()` method will destroy the card.
• `update({})` method will dynamically change some configurations, it accepts one argument which has to be an object with at least one of the following configuration keys: `checkoutId`, `email`, `amount`, `currency` or `installments`.

Test CSP

## Configure Authentication Set the `SUMUP_API_KEY` environment variable or pass the token directly. ```bash export SUMUP_API_KEY="sup_sk_MvxmLOl0..." ``` ```java import com.sumup.sdk.SumUpClient; SumUpClient client = new SumUpClient("sup_sk_MvxmLOl0..."); ``` ## Examples ### Online Payment Checkout ```java import com.sumup.sdk.SumUpClient; import com.sumup.sdk.models.CheckoutCreateRequest; import com.sumup.sdk.models.Currency; SumUpClient client = SumUpClient.builder().build(); CheckoutCreateRequest request = CheckoutCreateRequest.builder() .amount(25.00f) .currency(Currency.EUR) .checkoutReference("ORDER-1001") .merchantCode(System.getenv("SUMUP_MERCHANT_CODE")) .description("Online payment via card widget") .build(); var checkout = client.checkouts().createCheckout(request); System.out.println(checkout.id()); ``` ### Cloud API Checkout ```java import com.sumup.sdk.SumUpClient; import com.sumup.sdk.models.CreateReaderCheckoutRequest; import com.sumup.sdk.models.Money; SumUpClient client = SumUpClient.builder().build(); String merchantCode = System.getenv("SUMUP_MERCHANT_CODE"); String readerId = client.readers().listReaders(merchantCode).items().stream() .findFirst() .orElseThrow(() -> new IllegalStateException("No paired readers found.")) .id() .value(); CreateReaderCheckoutRequest request = CreateReaderCheckoutRequest.builder() .description("Reader checkout") .totalAmount( Money.builder() .currency("EUR") .minorUnit(2L) .value(1500L) .build()) .build(); client.readers().createReaderCheckout(merchantCode, readerId, request); ``` # Node.js SDK > Use the official TypeScript client to talk to every SumUp public API. The [`@sumup/sdk`](https://github.com/sumup/sumup-ts) package wraps SumUp API, ships TypeScript declarations, and works in modern Node.js runtimes (>=18) as well as Cloudflare Workers, Vercel, and other ESM-friendly environments. ## Installation Install with `npm install @sumup/sdk` (or `yarn add` / `pnpm add`). ## Configure Authentication The client reads the `SUMUP_API_KEY` environment variable automatically, so deploying with `SUMUP_API_KEY=sup_sk_MvxmLOl0...` is enough for most server workloads. You can also pass the secret explicitly: ```ts const client = new SumUp({ apiKey: "sup_sk_MvxmLOl0..." }); ``` If you use OAuth, exchange the authorization code for an access token and pass it as the `accessToken` option instead of `apiKey`. ## Examples ### Online Payment Checkout ```ts import SumUp from "@sumup/sdk"; const client = new SumUp({ apiKey: process.env.SUMUP_API_KEY ?? "" }); async function createOnlineCheckout() { const checkout = await client.checkouts.create({ amount: 2500, checkout_reference: "ORDER-1001", currency: "EUR", merchant_code: process.env.SUMUP_MERCHANT_CODE ?? "", pay_to_email: process.env.SUMUP_PAY_TO_EMAIL ?? "", description: "Online payment via card widget", }); console.log(checkout.id); // Return checkout.id to your webpage so the SumUp card widget can complete the payment. } createOnlineCheckout().catch((error) => { console.error(error); process.exit(1); }); ``` ### Cloud API Checkout ```ts import SumUp from "@sumup/sdk"; const client = new SumUp({ apiKey: process.env.SUMUP_API_KEY ?? "" }); async function createSoloCheckout() { const merchantCode = process.env.SUMUP_MERCHANT_CODE ?? ""; const affiliateKey = process.env.SUMUP_AFFILIATE_KEY ?? ""; const affiliateAppId = process.env.SUMUP_APP_ID ?? ""; if (!affiliateKey || !affiliateAppId) { throw new Error( "Set SUMUP_AFFILIATE_KEY and SUMUP_APP_ID to use the Cloud API.", ); } const { items: readers } = await client.readers.list(merchantCode); const solo = readers.find((reader) => reader.device.model === "solo"); if (!solo) { throw new Error("Pair a Solo reader before using the Cloud API."); } const checkout = await client.readers.createCheckout(merchantCode, solo.id, { total_amount: { currency: "EUR", minor_unit: 2, value: 1500, }, }); console.log(checkout.data.client_transaction_id); } createSoloCheckout().catch((error) => { console.error(error); process.exit(1); }); ``` # PHP SDK > Introduction to the SumUp PHP SDK and first steps to get you started. The [`sumup-php`](https://github.com/sumup/sumup-php) package is the official PHP SDK for SumUp APIs. It provides service clients for common resources, such as: - managing merchant accounts - managing checkouts - managing customers - managing payouts - querying transactions - managing readers ## Installation Install with `composer require sumup/sumup-php`. ## Configure Authentication Set the `SUMUP_API_KEY` environment variable or pass the API key directly to the `SumUp\SumUp` constructor. You can also provide an OAuth access token via `access_token`. ```bash export SUMUP_API_KEY='your-api-key-here' ``` ## Examples ### Online Payment Checkout ```php checkouts->create([ 'merchant_code' => getenv('SUMUP_MERCHANT_CODE'), 'amount' => 25.00, 'currency' => 'EUR', 'checkout_reference' => 'ORDER-1001', 'description' => 'Online payment via card widget', ]); echo $checkout->id . PHP_EOL; // Return $checkout->id to your webpage so the SumUp card widget can complete the payment. } catch (SDKException $exception) { echo 'SumUp SDK error: ' . $exception->getMessage(); } ``` ### Cloud API Checkout ```php readers->list($merchantCode)->items ?? []; $firstSolo = $readers[0] ?? null; if (!$firstSolo) { throw new RuntimeException('Pair a Solo reader before using the Cloud API.'); } $payload = [ 'total_amount' => [ 'currency' => 'EUR', 'minor_unit' => 2, 'value' => 1500, ], 'affiliate' => [ 'app_id' => getenv('SUMUP_APP_ID'), 'foreign_transaction_id' => 'solo-' . time(), 'key' => getenv('SUMUP_AFFILIATE_KEY'), ], 'description' => 'Cloud API checkout', ]; $checkoutResponse = $sumup->readers->createCheckout( $merchantCode, $firstSolo->id, $payload ); echo $checkoutResponse->data['client_transaction_id'] . PHP_EOL; } catch (SDKException | RuntimeException $exception) { echo 'Error: ' . $exception->getMessage(); } ``` ## SDK Documentation For more information read the **[documentation](https://github.com/sumup/sumup-php)**. # Python SDK > Build synchronous or async SumUp integrations with Python. [`sumup-py`](https://github.com/sumup/sumup-py) provides first-party Python bindings for every SumUp API. It ships both synchronous and asynchronous clients powered by `httpx`, includes Pydantic models for request bodies, and offers type hints for modern editors. ## Installation Install with `pip install sumup`. If you use [uv](https://docs.astral.sh/uv/), run `uv add sumup`. ## Configure Authentication Expose your secret API key or OAuth access token as an environment variable and pass it to either the synchronous `Sumup` or asynchronous `AsyncSumup` client. You can also pass the key manually: ```py client = Sumup(api_key="sup_sk_MvxmLOl0...") ``` ## Examples ### Online Payment Checkout ```py import os from sumup import Sumup from sumup.checkouts.resource import CreateCheckoutBody client = Sumup(api_key=os.environ["SUMUP_API_KEY"]) checkout = client.checkouts.create( CreateCheckoutBody( merchant_code=os.environ["SUMUP_MERCHANT_CODE"], amount=25.00, checkout_reference="ORDER-1001", currency="EUR", description="Online payment via card widget", ) ) print(checkout.id) # Return checkout.id to your webpage so the SumUp card widget can complete the payment. ``` ### Cloud API Checkout ```py import asyncio import os from time import time from sumup import AsyncSumup from sumup.readers.resource import ( CreateReaderCheckoutBody, CreateReaderCheckoutBodyAffiliate, CreateReaderCheckoutBodyTotalAmount, ) async def create_solo_checkout() -> None: client = AsyncSumup(api_key=os.environ["SUMUP_API_KEY"]) merchant_code = os.environ["SUMUP_MERCHANT_CODE"] readers = await client.readers.list(merchant_code) solo = next((reader for reader in readers.items if reader.device.model == "solo"), None) if solo is None: raise RuntimeError("Pair a Solo reader before using the Cloud API.") checkout = await client.readers.create_checkout( merchant_code, solo.id, CreateReaderCheckoutBody( total_amount=CreateReaderCheckoutBodyTotalAmount(currency="EUR", minor_unit=2, value=1500), ), ) print(checkout.data.client_transaction_id) asyncio.run(create_solo_checkout()) ``` # React Native Checkout SDK > Step-by-step guide for integrating the SumUp React Native Payment SDK, from prerequisites to checkout creation and mounting the payment sheet. import { Aside, Tabs, TabItem } from '@astrojs/starlight/components'; import Button from '@components/content/Button.astro'; import Image from '@components/content/Image.astro'; SumUp's React Native Payment SDK provides a payment sheet that is displayed on top of your app. It collects user payment details, confirms a payment, and saves a card for future usage. Moreover, it allows a user to use Apple Pay or Google Pay to process payments. ## Integration ### Before You Begin Here are the things that you need in order to complete the steps in this guide: - You have a merchant account with [SumUp](https://me.sumup.com/login) and have already filled in your [account details](https://me.sumup.com/account). - For a **sandbox merchant account** reach out to our support team through this [contact form](/contact). - You have [registered your client application](/tools/authorization/oauth/#register-an-oauth-application) with SumUp. - You have a valid access token obtained via the [Authorization code flow](/tools/authorization/oauth/#authorization-code-flow). - The restricted `payment_instruments` scope is enabled for your client application. If it isn't enabled, [contact us](/contact) and request it. - Review the [single payment guide](https://developer.sumup.com/online-payments/guides/single-payment/#before-you-begin). ### Create a Checkout Initializing the SDK works by passing it a `checkout_id`. To [create a checkout](/api/checkouts/create) on your backend make the following request: ```bash curl --request POST \ --url https://api.sumup.com/v0.1/checkouts \ --header "Authorization: Bearer $SUMUP_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "checkout_reference": "44ea5096-b83f-46e1-9323-fe82a8cb7eb5", "currency": "SEK", "amount": 9.99, "description": "Order #1234", "merchant_code": "MXXXXXXX", "return_url": "https://example.com", "redirect_url": "https://sumup.com" }' ``` ```ts const checkout = await client.checkouts.create({ checkout_reference: "44ea5096-b83f-46e1-9323-fe82a8cb7eb5", amount: 9.99, currency: "SEK", merchant_code: "MXXXXXXX", description: "Order #1234", return_url: "https://example.com", redirect_url: "https://sumup.com", }); ``` ```csharp var checkout = await client.Checkouts.CreateAsync(new CheckoutCreateRequest { CheckoutReference = "44ea5096-b83f-46e1-9323-fe82a8cb7eb5", Amount = 9.99f, Currency = Currency.Sek, MerchantCode = "MXXXXXXX", Description = "Order #1234", ReturnUrl = "https://example.com", RedirectUrl = "https://sumup.com", }); ``` ```java var checkout = client.checkouts().createCheckout( CheckoutCreateRequest.builder() .checkoutReference("44ea5096-b83f-46e1-9323-fe82a8cb7eb5") .amount(9.99f) .currency(Currency.SEK) .merchantCode("MXXXXXXX") .description("Order #1234") .returnUrl("https://example.com") .redirectUrl("https://sumup.com") .build() ); ``` ```go description := "Order #1234" returnURL := "https://example.com" redirectURL := "https://sumup.com" checkout, err := client.Checkouts.Create(ctx, sumup.CheckoutsCreateParams{ CheckoutReference: "44ea5096-b83f-46e1-9323-fe82a8cb7eb5", Amount: 9.99, Currency: sumup.CurrencySEK, MerchantCode: "MXXXXXXX", Description: &description, ReturnURL: &returnURL, RedirectURL: &redirectURL, }) ``` ```py from sumup.checkouts.resource import CreateCheckoutBody checkout = client.checkouts.create( CreateCheckoutBody( checkout_reference="44ea5096-b83f-46e1-9323-fe82a8cb7eb5", amount=9.99, currency="SEK", merchant_code="MXXXXXXX", description="Order #1234", return_url="https://example.com", redirect_url="https://sumup.com", ) ) ``` ```rust let checkout = client .checkouts() .create(Some(sumup::resources::checkouts::CheckoutCreateRequest { checkout_reference: "44ea5096-b83f-46e1-9323-fe82a8cb7eb5".into(), amount: 9.99, currency: sumup::resources::checkouts::Currency::SEK, merchant_code: "MXXXXXXX".into(), description: Some("Order #1234".into()), return_url: Some("https://example.com".into()), redirect_url: Some("https://sumup.com".into()), customer_id: None, purpose: None, id: None, status: None, date: None, valid_until: None, transactions: None, })) .await?; ``` ```php $checkout = $sumup->checkouts->create([ 'checkout_reference' => '44ea5096-b83f-46e1-9323-fe82a8cb7eb5', 'currency' => 'SEK', 'amount' => 9.99, 'description' => 'Order #1234', 'merchant_code' => 'MXXXXXXX', 'return_url' => 'https://example.com', 'redirect_url' => 'https://sumup.com', ]); ``` The SDK will process the checkout once a customer provides payment details. If payment details aren't passed an error will be received. ## Set up SDK Install the npm module by one of the following commands: ```bash npm i sumup-react-native-alpha npm i react-native-webview ``` ```bash yarn add sumup-react-native-alpha yarn add react-native-webview ``` You need to install `react-native-localization` to automatically detect the user system language. ```bash npm i react-native-localization ``` ```bash yarn add react-native-localization ``` If you don't need it, please provide the language field in the `initPaymentSheet` function. ```javascript await initPaymentSheet({ checkoutId, language: 'en', }); ``` Next, install the native modules. ```bash cd ios pod install ``` SDK should be initialized by wrapping your payment screen into SumUpProvider. This component requires an `apiKey` you can create in the [API Keys settings](/tools/authorization/api-keys/). ```javascript import { SumUpProvider } from 'sumup-react-native-alpha'; export default function App() { return ( ); } ``` ## Provide Payment Details Before showing the payment sheet, it needs to be initialized. Call `initPaymentSheet` with the parameters like in example below: ```js import React, { useEffect } from "react"; import { View, Alert } from "react-native"; import { useSumUp } from "sumup-react-native-alpha"; export default function MainScreen() { const { initPaymentSheet } = useSumUp(); const initSumUpPaymentSheet = async () => { const { error } = await initPaymentSheet({ checkoutId: "...", customerId: "...", language: "en", // en or sv are supported }); if (error) { Alert.alert( error.status, error.status === "failure" ? error.message : undefined ); } else { Alert.alert("Payment Sheet was configured"); } }; useEffect(() => { initSumUpPaymentSheet(); }, []); ... ``` **Required** fields for `initPaymentSheet`: - `checkoutId` - described in section [Create a checkout](/online-payments/sdks/react-native/#create-a-checkout). *Optional*: - `customerId` - used for saving cards for future usage. - `language` - English and Sweden are supported (if undefined, react-native-localization will be used to check user device language). ## Show Payment Sheet After initialization a payment sheet can be shown. When a user presses a button, you can show it by calling `presentPaymentSheet()`. After a user completes a payment, this function will return a callback. If any errors take place, the callback will contain an error field with the details. ```js ... const showPaymentSheet = async () => { const { error } = await presentPaymentSheet(); if (error) { Alert.alert( error.status, error.status === "failure" ? error.message : undefined ); } else { Alert.alert("Payment successfully was processed"); } }; return ( ); } ``` ## Optional Integrations ### Save a Card for Future Usage To save a card for future usage, a customer should be created. It can be achieved by making the following request: ```bash curl -L -X POST 'https://api.sumup.com/v0.1/customers' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H "Authorization: Bearer $SUMUP_API_KEY" \ --data-raw '{ "customer_id": "831ff8d4cd5958ab5670", "personal_details": { "first_name": "John", "last_name": "Doe", "email": "user@example.com", "phone": "+491635559723", "birthdate": "1993-12-31", "address": { "city": "Berlin", "country": "DE", "line1": "Sample street", "line2": "ap. 5", "postal_code": "10115", "state": "Berlin" } } }' ``` ```ts const customer = await client.customers.create({ customer_id: "831ff8d4cd5958ab5670", personal_details: { first_name: "John", last_name: "Doe", email: "user@example.com", phone: "+491635559723", birth_date: "1993-12-31", address: { city: "Berlin", state: "Berlin", country: "DE", line_1: "Sample street", line_2: "ap. 5", postal_code: "10115", }, }, }); ``` ```csharp var customer = await client.Customers.CreateAsync(new Customer { CustomerId = "831ff8d4cd5958ab5670", PersonalDetails = new PersonalDetails { FirstName = "John", LastName = "Doe", Email = "user@example.com", Phone = "+491635559723", BirthDate = new System.DateTime(1993, 12, 31), Address = new AddressLegacy { City = "Berlin", State = "Berlin", Country = "DE", Line1 = "Sample street", Line2 = "ap. 5", PostalCode = "10115", }, }, }); ``` ```java var customer = client.customers().createCustomer( Customer.builder() .customerId("831ff8d4cd5958ab5670") .personalDetails( PersonalDetails.builder() .firstName("John") .lastName("Doe") .email("user@example.com") .phone("+491635559723") .birthDate(java.time.LocalDate.parse("1993-12-31")) .address( AddressLegacy.builder() .city("Berlin") .state("Berlin") .country("DE") .line1("Sample street") .line2("ap. 5") .postalCode("10115") .build() ) .build() ) .build() ); ``` ```go str := func(v string) *string { return &v } customer, err := client.Customers.Create(ctx, sumup.CustomersCreateParams{ CustomerID: "831ff8d4cd5958ab5670", PersonalDetails: &sumup.PersonalDetails{ FirstName: str("John"), LastName: str("Doe"), Email: str("user@example.com"), Phone: str("+491635559723"), Address: &sumup.AddressLegacy{ City: str("Berlin"), State: str("Berlin"), Country: str("DE"), Line1: str("Sample street"), Line2: str("ap. 5"), PostalCode: str("10115"), }, }, }) ``` ```py from sumup.customers.resource import CreateCustomerBody from sumup.customers.types import AddressLegacy, PersonalDetails customer = client.customers.create( CreateCustomerBody( customer_id="831ff8d4cd5958ab5670", personal_details=PersonalDetails( first_name="John", last_name="Doe", email="user@example.com", phone="+491635559723", birth_date="1993-12-31", address=AddressLegacy( city="Berlin", state="Berlin", country="DE", line_1="Sample street", line_2="ap. 5", postal_code="10115", ), ), ) ) ``` ```rust let customer = client .customers() .create(sumup::resources::customers::Customer { customer_id: "831ff8d4cd5958ab5670".into(), personal_details: Some(sumup::resources::common::PersonalDetails { first_name: Some("John".into()), last_name: Some("Doe".into()), email: Some("user@example.com".into()), phone: Some("+491635559723".into()), birth_date: None, tax_id: None, address: Some(sumup::resources::common::AddressLegacy { city: Some("Berlin".into()), state: Some("Berlin".into()), country: Some("DE".into()), line_1: Some("Sample street".into()), line_2: Some("ap. 5".into()), postal_code: Some("10115".into()), }), }), }) .await?; ``` ```php $customer = $sumup->customers->create([ 'customer_id' => '831ff8d4cd5958ab5670', 'personal_details' => [ 'first_name' => 'John', 'last_name' => 'Doe', 'email' => 'user@example.com', 'phone' => '+491635559723', 'address' => [ 'city' => 'Berlin', 'state' => 'Berlin', 'country' => 'DE', 'line_1' => 'Sample street', 'line_2' => 'ap. 5', 'postal_code' => '10115', ], ], ]); ``` For more information on saving a customer refer to [this guide](/api/customers/create). To use the newly created customer, create a checkout by passing the `customer_id` and provide it to the `initPaymentSheet` function. ```js await initPaymentSheet({ // ... customerId: '...', }); ``` ### Use Google Pay To use Google Pay, first enable the Google Pay API by adding the following to the `application` tag of your `AndroidManifest.xml`: ```bash ... ``` For more details, see [Google Pay’s Set up Google Pay API for Android](https://developers.google.com/pay/api/android/guides/setup). Then provide `googlePay` object to the `initPaymentSheet` to initialize. ```js await initPaymentSheet({ // ... googlePay: { isProductionEnvironment: false, }, }); ``` ### Use Apple Pay #### Register for an Apple Merchant ID Obtain an Apple Merchant ID by registering for a new identifier on the Apple Developer website. Fill out the form with a description and identifier. Your description is for your own records and you can modify it in the future. **Create a new Apple Pay certificate - needs to be implemented.** To enable Apple Pay in Xcode: 1. Open your target settings 2. Go to Signing & Capabilities tab 3. Click on Add Capability button 4. Select your merchant identifier  Then provide an `applePay` object in `initPaymentSheet` to initialize. ```js await initPaymentSheet({ // ... applePay: { merchantIdentifier: 'merchant.com.{{YOUR_APP_NAME}}', label: 'Pay', }, }); ``` # Rust SDK > Use the `sumup` crate to access SumUp APIs from Rust. [`sumup-rs`](https://github.com/sumup/sumup-rs) is the official crate published as [`sumup`](https://crates.io/crates/sumup). It covers all public APIs, supports async/await, and exposes helpers for card-present and e-commerce workflows. ## Installation Install the crate with `cargo add sumup` (enable the `jiff` feature if you prefer alternative datetime handling). ## Configure Authentication Set the `SUMUP_API_KEY` environment variable (or provide an OAuth token) and pass it to `Client::builder().with_api_key`. You can also inject the key directly: ```rs let client = Client::builder() .with_api_key("sup_sk_MvxmLOl0...") .build()?; ``` ## Examples ### Online Payment Checkout ```rs use sumup::{resources::checkouts::CheckoutCreateRequest, Client, Currency}; #[tokio::main] async fn main() -> Result<(), Box> { let client = Client::builder() .with_api_key(std::env::var("SUMUP_API_KEY")?) .build()?; let checkout = client .checkouts() .create(Some(CheckoutCreateRequest { merchant_code: std::env::var("SUMUP_MERCHANT_CODE")?, amount: 25.00, checkout_reference: "ORDER-1001".into(), currency: Currency::EUR, description: Some("Online payment via card widget".into()), customer_id: None, purpose: None, id: None, status: None, date: None, valid_until: None, transactions: None, redirect_url: None, return_url: None, })) .await?; println!("{}", checkout.id.unwrap_or_default()); // Return checkout ID to your webpage so the SumUp card widget can complete the payment. Ok(()) } ``` ### Cloud API Checkout ```rs use std::{ io::{Error, ErrorKind}, time::{SystemTime, UNIX_EPOCH}, }; use sumup::{ resources::readers::CreateReaderCheckoutRequestAffiliate, Client, CreateReaderCheckoutRequest, Money, }; #[tokio::main] async fn main() -> Result<(), Box> { let client = Client::builder() .with_api_key(std::env::var("SUMUP_API_KEY")?) .build()?; let merchant_code = std::env::var("SUMUP_MERCHANT_CODE")?; let readers = client.readers().list(&merchant_code).await?; let solo = readers .items .into_iter() .find(|reader| reader.device.model == "solo") .ok_or_else(|| Error::new(ErrorKind::NotFound, "Pair a Solo reader before using the Cloud API."))?; let checkout = client .readers() .create_checkout( &merchant_code, &solo.id, CreateReaderCheckoutRequest { total_amount: Money { currency: "EUR".into(), minor_unit: 2, value: 1_500, }, affiliate: None, card_type: None, description: None, installments: None, return_url: None, tip_rates: None, tip_timeout: None, }, ) .await?; println!("{}", checkout.data.client_transaction_id); Ok(()) } ``` # Testing > Learn how to test online payments using a sandbox merchant account and test cards with different 3D Secure flows. import { Aside, Steps } from "@astrojs/starlight/components"; import Table from "@components/content/Table"; Testing your online payments integration is crucial before going live. SumUp provides sandbox merchant accounts and a comprehensive set of test cards to simulate various payment scenarios, including different 3D Secure authentication flows. ## Setting up a Sandbox Merchant Account Before you can test online payments, you need to create a sandbox merchant account in the SumUp Dashboard. 1. Log in to your SumUp account. 2. Open the drop-down menu between Support and your user panel. 3. Select **Sandbox merchant account**. ## How to Use Test Cards When testing with card payments, you can use the following common details for all test cards: - **CVV**: Any 3 digits (e.g., `123`) - **Expiry Date**: Any future date (e.g., `12/25`) - **Cardholder Name**: Any name ## Test Successful Payments Use this section as your primary end-to-end test path. It validates that a payment can be completed successfully without additional customer authentication steps. What to verify: 1. Your checkout completes successfully without additional cardholder action 2. You correctly handle frictionless authentication and continue order processing 3. Your success path is robust across different card brands ## Test Unsuccessful Payments Use this section to verify how your integration handles declined or failed payments. To simulate an unsuccessful payment, create a checkout for amount `42.01`, `42.76`, or `42.91` (depending on currency, for example `4201` in minor units[^minor_units]). These amounts result in a failed payment. What to verify: 1. Your frontend displays a clear failure message and allows safe retry 2. Your backend marks the payment as failed and avoids creating a successful order 3. Your logs and monitoring capture the failure reason for troubleshooting ## Test 3D Secure Authentication 3D Secure (3DS) adds an authentication step between payment submission and final authorization when issuer verification is required. Primary option: use the [Payment Widget](/online-payments/checkouts/card-widget/). It handles authentication screens and redirect behavior for you. Secondary option: direct Checkouts API integration. This path requires PCI compliance and explicit onboarding/approval from SumUp. After [processing a checkout](/api/checkouts/process), use the returned `next_step` object (`url`, `method`, optional `payload`, `redirect_url`, and `mechanism`) to continue the flow. ### Successful 3D Secure Authentication Scenarios For Payment Widget integrations, `onResponse` can emit `auth-screen` when challenge authentication starts. After challenge completion, verify the final checkout result on your backend with [Retrieve a checkout](/api/checkouts/get). What to verify: 1. Your frontend handles challenge redirects and return URLs correctly 2. Your backend waits for the final authentication result before fulfillment 3. Retry and timeout handling behaves correctly when users abandon the challenge ### 3D Secure Failure Scenarios Use these cards to validate failed authentication and non-participation behavior. These cards simulate: - Technical authentication errors - Cardholder not enrolled for 3D Secure - Card/issuer not participating in 3D Secure What to verify: 1. You display actionable error messaging for technical authentication failures 2. You handle non-enrolled and non-participating cards without crashing 3. Failed payments do not create successful order states in your system ## Next Steps Once you've thoroughly tested your integration with your sandbox merchant account and test cards: 1. Switch back to your live account in the Dashboard 2. Ensure your production credentials are properly configured 3. Process a small real transaction to verify everything works as expected 4. Monitor your first transactions closely to ensure proper payment processing [^minor_units]: [Minor unit fractions](https://en.wikipedia.org/wiki/ISO_4217#Minor_unit_fractions) refer to the smallest denomination of a currency, which is used for representing transaction amounts. For example, if a currency has two decimal places, like USD (dollars and cents), the minor unit is the cent, and an amount is represented as a whole number of cents # Webhooks > Webhooks notify your application about checkout status changes. import { Aside } from '@astrojs/starlight/components'; Webhooks are a convenient approach to notify an application about relevant events that have taken place within another application. The event is similar to one in real-life, where you’re awaiting your favorite item to restock in a shop and ask a representative to notify you once it’s back. In this scenario, SumUp plays the role of the shop, the representative is the [SumUp APIs](/api) and the update seeker is your application. ## Events At this time our system only allows you to get notified about a status change for a checkout. To subscribe to an event, specify a `return_url` parameter upon [checkout creation](/api/checkouts/create). New events may be introduced at any time, without prior notice. Your application has to be able to cope with such. Our recommendation would be to silently ignore unknown events. ## Handling a Webhook Webhooks are delivered in the form of a HTTP POST request, to which your application should reply to as soon as possible. If the response takes longer, our system accepts this as a failed notification and retries it. Your application should return a valid, empty response with any `2xx` status code. Any response other than a `2xx` is treated as erroneous. Here's a sample of the webhook payload: ```json { "event_type": "CHECKOUT_STATUS_CHANGED", "id": "id-of-the-changed-checkout" } ``` ## Retries When an erroneous response is received, a webhook delivery is retried with the following delays: - 1 minute - 5 minutes - 20 minutes - 2 hours # Problems > Reference of common SumUp API error responses with HTTP status codes, payload formats, and handling guidance. This section lists the common error responses that the SumUp API can return. Each page describes the HTTP status code, error structure and suggestions for how to handle it in your integration. - [Invalid Parameter](/problem/invalid-parameter) - [Multiple Invalid Parameters](/problem/multiple-invalid-parameters) - [Payment Method Not Allowed](/problem/payment-method-not-allowed) - [Unknown Payment Method](/problem/unknown-payment-method) - [Validation Failed](/problem/validation-failed) - [Bad Request](/problem/bad-request) - [Invalid Token](/problem/invalid-token) - [Missing Token](/problem/missing-token) - [Not Authorised Token](/problem/not-authorised-token) - [Unauthorized](/problem/unauthorized) - [Forbidden](/problem/forbidden) - [Checkout Not Found](/problem/checkout-not-found) - [Not Found](/problem/not-found) - [Session Already Processed](/problem/session-already-processed) - [Session Can't Be Deactivated](/problem/session-cant-be-deactivated) - [Session Expired](/problem/session-expired) - [Unprocessable Entity](/problem/unprocessable-entity) - [Internal Server Error](/problem/internal-server-error) - [Gateway Timeout](/problem/gateway-timeout) # Bad Request Indicates that the server cannot or will not process the request due to a client error. ## Common Causes - The request body is malformed JSON. - A required field is missing or has an invalid value. - The request uses an unsupported content type. ```json { "type": "https://developer.sumup.com/problem/bad-request", "status": 400, "detail": "Bad Request", "fields": [ { "path": "$.user.name", "name": "name", "message": "Name must not be empty" } ] } ``` # Checkout Not Found Indicates that the server can't find the requested checkout resource. ## Common Causes - The checkout ID is incorrect or does not exist. - The checkout belongs to a different merchant. ```json { "type": "https://developer.sumup.com/problem/checkout-not-found", "title": "Not Found", "status": 404, "detail": "A checkout session with the id 61b06d01-ffc4-4432-9053-2ea587f735b1 does not exist" } ``` # Forbidden Indicates that the server understood the request but refuses to authorize it. ## Common Causes - The merchant account is not permitted to perform this action. - The resource belongs to another merchant or app. - The operation is blocked due to compliance or risk checks. ```json { "error_message": "request_not_allowed", "error_code": "FORBIDDEN", "status_code": 403 } ``` # Gateway Timeout Indicates that the server did not receive a timely response to complete the request. Retry the request, and if timeouts continue, check the [SumUp status page](https://status.sumup.com/) or [contact us](/contact). ## Common Causes - An upstream dependency did not respond in time. - Network latency or connectivity issues delayed the response. - The request required longer processing than the timeout window. ```json { "type": "https://developer.sumup.com/problem/gateway-timeout", "title": "Gateway Timeout", "status": 504, "instance": "8cb5b380786b" } ``` # Internal Server Error Indicates that an unexpected server error occurred. Retry the request, if this persists, check the [SumUp status page](https://status.sumup.com/) or [contact us](/contact). ## Common Causes - A transient internal exception occurred while processing the request. - A downstream dependency returned an unexpected error. - The service was temporarily unavailable under load. ```json { "type": "https://developer.sumup.com/problem/internal-server-error", "title": "Internal Server Error", "status": 500, "instance": "8cb5b380896b" } ``` # Invalid Parameter Indicates that the server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). ## Common Causes - A required field is missing or empty. - A field has the wrong type or format (for example, a string where a number is expected). - A value is outside the allowed range or list of supported values. ```json { "message": "Validation error", "error_code": "INVALID", "param": "card.expiry_year" } ``` # Invalid Token Indicates that the request has not been applied because it lacks valid authentication credentials for the target resource. ## Common Causes - The access token has expired. - The token has been revoked or is no longer valid. - The token belongs to a different app or environment. ```json { "error_message": "invalid access token", "error_code": "NOT_AUTHORIZED" } ``` # Missing Token Indicates that the request has not been applied because it lacks valid authentication credentials for the target resource. ## Common Causes - The `Authorization` header is missing. - The token is not included in the request at all. - The header is present but empty or malformed. ```json { "message": "access token required", "error_code": "NOT_AUTHORIZED" } ``` # Multiple Invalid Parameters Indicates that the server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). ## Common Causes - Multiple fields fail validation in the same request. - Mutually exclusive parameters are provided together. - A nested object contains one or more invalid fields. ```json [ { "error_code": "INVALID", "message": "Validation error", "param": "card.name" }, { "error_code": "INVALID", "message": "Validation error", "param": "card.number" }, { "error_code": "INVALID", "message": "Validation error", "param": "card.expiry_year" } ] ``` # Not Authorised Token Indicates that the request has not been applied because it lacks valid authentication credentials for the target resource. ## Common Causes - The token lacks the required scopes for the endpoint. - The token belongs to a different merchant than the resource. - A refresh token is used instead of an access token. ```json { "error_message": "NOT_AUTHORIZED", "error_code": "NOT_AUTHORIZED" } ``` # Not Found Indicates that the server can't find the requested resource. ## Common Causes - The resource ID is incorrect or no longer exists. - The request isn't authenticated to access the resource. - The resource was deleted or expired. - The request path or method does not match a valid endpoint. ```json { "error_code": "NOT_FOUND", "message": "Resource not found" } ``` # Payment Method Not Allowed Ensure the payment method for the respective checkout, supports the merchant's country. To check which countries a payment method supports, visit our documentation on [Alternative Payment Methods](/online-payments/apm). ## Common Causes - The payment method is not enabled for the merchant account. - The checkout currency is not supported by the selected payment method. - The payment method is not available in the merchant's country. ```json { "type": "https://developer.sumup.com/problem/payment-method-not-allowed", "title": "Bad Request", "status": 400, "detail": "The BLIK payment method is not allowed for this checkout session", "instance": "7fe5fcddbf28" } ``` # Session Already Processed Indicates the checkout has already been processed. Check the transaction status by calling our `get transaction` endpoint. ## Common Causes - The checkout has already completed successfully. - A duplicate processing request is sent for the same checkout. - A retry occurs after the transaction has already been captured. ```json { "type": "https://developer.sumup.com/problem/session-already-processed", "title": "Conflict", "status": 409, "detail": "The checkout session ae98b9cc-2287-4621-afa1-d36ae2ea219d is already processed", "instance": "1bfe72b34387" } ``` # Session Can't Be Deactivated Indicates checkout session can't be canceled due to a pending Boleto payment. ## Common Causes - A Boleto payment is still pending for the checkout. - The checkout is in a non-cancellable state. - A payment authorization is already in progress. ```json { "type": "https://developer.sumup.com/problem/session-cant-be-deactivated", "title": "Conflict", "status": 409, "detail": "The checkout can't be cancelled due to a pending Boleto payment", "error_code": "CHECKOUT_CANT_BE_DEACTIVATED", "message": "The checkout can't be cancelled due to a pending Boleto payment", "instance": "8aeafaccae28" } ``` # Session Expired Indicates checkout session has reached its expiration point. Initiate a new checkout. ## Common Causes - The checkout reached its expiration time before payment completed. - The customer attempted to pay after the checkout TTL elapsed. - A delayed payment method completed after expiration. ```json { "type": "https://developer.sumup.com/problem/session-expired", "title": "Conflict", "status": 409, "detail": "The checkout session ae98b9cc-2287-4621-afa1-d36ae2ea219d is already processed", "instance": "1bfe72b34387" } ``` # Unauthorized Indicates that the request lacks valid authentication credentials for the target resource. ## Common Causes - The access token is missing or empty. - The access token is expired or revoked. - The token is for a different environment or app. ```json { "type": "https://developer.sumup.com/problem/unauthorized", "status": 401, "detail": "Unauthorized" } ``` # Unknown Payment Method Indicates the payment method is unknown to SumUp. ## Common Causes - The payment method value is misspelled or not supported. - The method is not returned by the available payment methods endpoint. - The method is not enabled for the merchant account. ```json { "type": "https://developer.sumup.com/problem/unknown-payment-method", "title": "Bad Request", "status": 400, "detail": "Unknown payment method: NonExistingPaymentMethod", "instance": "7fe5fcddbf28" } ``` # Unprocessable Entity Indicates that the server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions. **Important:** The client should not repeat this request without modification. ## Common Causes - The request is syntactically valid but violates business rules. - A state transition is not allowed for the current resource status. - Referenced resources exist but are incompatible (for example, currency mismatch). # Validation Failed Indicates that the request payload fails validation rules. ## Common Causes - An ID or reference does not match the expected format. - A field violates length or pattern constraints. - A required nested field is missing in the payload. ```json { "type": "https://developer.sumup.com/problem/validation-failed", "title": "Bad Request", "status": 400, "detail": "Validation failed", "instance": "9b8eda265e35" "failed_constraints": [ { "reference": "checkoutId", "message": "Invalid checkout ID: 'not_a_valid_id'" } ] } ``` # PSD2 Open Banking Payment Services Directive 2 is a European directive that regulates payment services and payment service providers throughout the European Union (EU) by creating a more integrated payments market. The directive also promotes safer payments and consumer protection. As part of PSD2, all payments services providers are required to provide application programming interfaces (APIs) that permit third parties to electronically access financial information in a secure and efficient manner and _only_ with customer approval. To ensure the above, SumUp has partnered with Token.io to handle the data exchange. The regulation allows users to access their payments account information and initiate payments through authorized third-party payment service providers (TPPs). Users will be able to control this through a dedicated interface where they control the access levels, between the Account Information Servive (AIS) and Payment Initiation Services (PIS) options. - **AIS** pulls data from your bank accounts and accumulates their information in the same location, through a certified TPP. - **PIS** allows secure checkouts on any website that supports it. ## Impact on SumUp Merchants All SumUp merchants who have connected their SumUp Card to their SumUp Business Account will find additional controls for allowing TPPs to access their account information through a dedicated interface. The SumUp Business Account information and payment initiation through a TPP will be performed in a secure and safe manner, upon the explicit approval of the merchant. Our partnership with [Token.io](https://token.io) has allowed SumUp to enable a [publicly available test environment](https://sumup.dashboard.sandbox.token.io/) for TPPs to test the Open Banking APIs where technical documentation is also available. ## Interface Availability & Performance Data We publish statistics every three months about the performance of our Open Banking services. You can find the quarterly reports below: | | | | | | ---------------- | --- | ------------------- | ------------------------------------------------------------------------------------------------------- | | 1st October 2020 | to | 31st December 2020 | [PDF](/open-banking-reports/REP020_Q4.pdf) | | 1st January 2021 | to | 31st March 2021 | [PDF](/open-banking-reports/REP021_Q1.pdf) | | 1st April 2021 | to | 30th June 2021 | [PDF](/open-banking-reports/REP021_Q2.pdf) | | 1st July 2021 | to | 30th September 2021 | [PDF](/open-banking-reports/REP021_Q3.pdf) | | 1st October 2021 | to | 31st December 2021 | [PDF](/open-banking-reports/REP021_Q4.pdf) | | 1st January 2022 | to | 31st March 2022 | [PDF](/open-banking-reports/REP022_Q1.pdf) | | 1st April 2022 | to | 30th June 2022 | [PDF](/open-banking-reports/REP022_Q2.pdf) | | 1st July 2022 | to | 30th September 2022 | [PDF](/open-banking-reports/REP022_Q3.pdf) | | 1st October 2022 | to | 31st December 2022 | [PDF](/open-banking-reports/REP022_Q4.pdf) | | 1st January 2023 | to | 31st March 2023 | [PDF](/open-banking-reports/REP023_Q1.pdf) | | 1st April 2023 | to | 30th June 2023 | [PDF](/open-banking-reports/REP023_Q2.pdf) | | 1st July 2023 | to | 30th September 2023 | [PDF](/open-banking-reports/REP023_Q3.pdf) | | 1st October 2023 | to | 31st December 2023 | [PDF](/open-banking-reports/REP023_Q4.pdf) | | 1st January 2024 | to | 31st March 2024 | [PDF](/open-banking-reports/REP024_Q1.pdf) | | 1st April 2024 | to | 30th June 2024 | [PDF](/open-banking-reports/REP024_Q2.pdf) | | 1st July 2024 | to | 30th September 2024 | [UK](/open-banking-reports/REP024_Q3_UK.pdf) [IE](/open-banking-reports/REP024_Q3_EU.pdf) | | 1st October 2024 | to | 31st December 2024 | [UK](/open-banking-reports/REP024_Q4_UK.pdf) [IE](/open-banking-reports/REP024_Q4_EU.pdf) | | 1st January 2025 | to | 31st March 2025 | [UK](/open-banking-reports/REP025_Q1_UK.pdf) [IE](/open-banking-reports/REP025_Q1_EU.pdf) | | 1st April 2025 | to | 30th June 2025 | [UK](/open-banking-reports/REP025_Q2_UK_REP024.pdf) [IE](/open-banking-reports/REP025_Q2_EU_REP023.pdf) | | 1st July 2025 | to | 30th September 2025 | [UK](/open-banking-reports/REP025_Q3_UK_REP024.pdf) [IE](/open-banking-reports/REP025_Q3_EU_REP023.pdf) | | 1st October 2025 | to | 31st December 2025 | [UK](/open-banking-reports/REP025_Q4_UK.pdf) [IE](/open-banking-reports/REP025_Q4_EU.pdf) | # In-Person Payments > Quickstart for terminal payments, covering prerequisites, hardware options, and affiliate key requirements. import { Aside, Steps } from '@astrojs/starlight/components'; import Image from '@components/content/Image.astro'; You can accept card payments using SumUp’s platform accompanied by our proprietary Card Terminals available in these [European countries](https://help.sumup.com/hc/en-gb/articles/360018586874-Accepting-card-payments-abroad), Brazil, Chile, and the USA. You can offer a complete user journey through the payment flow with our [SDK](/terminal-payments/sdks) or approach a lightweight integration with our [API](/terminal-payments/payment-switch), using the SumUp app to execute payments. ## Prerequisites - Before integrating either the [Native SDK](/terminal-payments/sdks/) or the [Payment API Switch](/terminal-payments/payment-switch), create a SumUp account in the [SumUp Dashboard](https://me.sumup.com). The dashboard offers [a sandbox merchant account](#getting-a-sandbox-merchant-account), allowing for integration tests without involving real money. - Once you have an account, [create an Affiliate Key](/tools/authorization/affiliate-keys/) for your app and [provide authorization](/tools/authorization/). The Card Terminals allow complete flexibility as they are not assigned to individual accounts. Once connected to a merchant account, the card terminals lock to specific countries and currencies. This applies to sandbox merchant accounts, which are for testing integrations and do not process transactions. You are now ready to integrate SumUp payment capabilities into your app, provided you have a SumUp card terminal: SumUp Air, SumUp Air Lite, SumUp Top/PIN+, SumUp 3G, SumUp Total, SumUp Super, SumUp On, or SumUp Air Register. ## Getting a Sandbox Merchant Account To test SumUp APIs and tools without involving real money, use a sandbox merchant account. Create one from your Dashboard account as follows. 1. Log in to your SumUp account. 2. Open the drop-down menu between **Support** and your user panel. 3. Select **Sandbox Merchant Account**. Your merchant account is now in sandbox mode. With your sandbox merchant account, begin making API calls with real data. Sandbox merchant accounts **do not** process transactions with real funds. The sandbox merchant account has a different ID and displays a clear warning. Requests with a value of 11 (in any currency) always fail by design, to test failed transaction scenarios. When finished experimenting with the sandbox merchant account, switch back to a regular account for business purposes. ## Affiliate Keys All card-present integrations require an Affiliate Key. Read the [Affiliate Keys Guide](/tools/authorization/affiliate-keys/) for details. ## Industry SumUp merchants operate in various industry segments, and our card terminals accommodate a wide range of use cases and business approaches. The following outlines the most common segments and the key benefits merchants report: - Retail businesses and services - The hospitality industry, specifically restaurants, cafés, and bars - Transportation and delivery services - Booking for Health, Beauty, and Wellness Integration options through the [Payment SDK](/terminal-payments/sdks) and [API](/terminal-payments/payment-switch), plus the full [API reference](/api), support other industries' needs. ## Communication with the Terminal The SDK and API Switch handle all communication with SumUp’s Card Terminal(s) via Bluetooth (BLE 4.0). ## Security No sensitive data passes through or stores on the merchant’s phone. The card terminal encrypts all data and holds certifications from relevant payment industry groups (PCI, EMV I & II, Visa, MasterCard, and Amex). # Accept payments > A unified quickstart for accepting card-reader payments with the iOS or Android Terminal SDK. import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components'; This guide shows the core card-reader payment flow for both mobile SDKs. For platform-specific setup details, permissions, and advanced options, use the full documentation: - [iOS Terminal SDK](/terminal-payments/sdks/ios-sdk) - [Android Reader SDK](/terminal-payments/sdks/android-sdk) - [Android Tap-to-Pay SDK](/terminal-payments/sdks/android-ttp) (phone-based contactless payments without a separate reader) ## Prerequisites - A SumUp merchant account (or [sandbox merchant account](/terminal-payments/#getting-a-sandbox-merchant-account)). - An [Affiliate Key](/tools/authorization/affiliate-keys/) linked to your app. - A compatible card reader paired with the merchant account. ## Basic Payment Flow 1. Initialize the SDK with your Affiliate Key. 2. Log the merchant in. 3. Optionally prepare the reader connection before checkout. 4. Create a checkout request and start payment. 5. Handle the result in your app. ### 1. Initialize the SDK ```swift import SumUpSDK @main class AppDelegate: UIResponder, UIApplicationDelegate { func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil ) -> Bool { SumUpSDK.setup(withAPIKey: "sup_afk_abcqwerty") return true } } ``` ```java public class SampleApplication extends Application { @Override public void onCreate() { super.onCreate(); SumUpState.init(this); } } ``` ### 2. Authenticate ```swift SumUpSDK.presentLogin(from: self, animated: true) { success, error in if let error { print("Login error: \(error)") return } if success { print("Merchant logged in") } } ``` ```java SumUpLogin login = SumUpLogin.builder("sup_afk_abcqwerty").build(); SumUpAPI.openLoginActivity(this, login, 1); ``` ### 3. Prepare for Checkout (Optional) Use this when the merchant is about to charge, so the SDK can wake/reconnect the reader early. ```swift SumUpSDK.prepareForCheckout() ``` ```java SumUpAPI.prepareForCheckout(); ``` ### 4. Start a Payment ```swift guard let merchantCurrencyCode = SumUpSDK.currentMerchant?.currencyCode else { return } let request = CheckoutRequest( total: NSDecimalNumber(string: "12.34"), title: "Coffee", currencyCode: merchantCurrencyCode ) request.foreignTransactionID = UUID().uuidString SumUpSDK.checkout(with: request, from: self) { result, error in if let error { print("Checkout error: \(error)") return } if let result { print("Result: \(result.success), transactionCode: \(result.transactionCode ?? "-")") } } ``` ```java SumUpPayment payment = SumUpPayment.builder() .total(new BigDecimal("12.34")) .currency(SumUpPayment.Currency.EUR) .title("Coffee") .foreignTransactionId(UUID.randomUUID().toString()) .build(); SumUpAPI.checkout(this, payment, 2); ``` ### 5. Handle the Checkout Result ```swift // Handled in the completion block of SumUpSDK.checkout(...) // Use result.success, result.transactionCode, and error for your UI/state updates. ``` ```java @Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { super.onActivityResult(requestCode, resultCode, data); if (requestCode == 2 && data != null) { int code = data.getExtras().getInt(SumUpAPI.Response.RESULT_CODE); String message = data.getExtras().getString(SumUpAPI.Response.MESSAGE); String txCode = data.getExtras().getString(SumUpAPI.Response.TX_CODE); // Update your UI/state here. } } ``` ## Continue with Full SDK Guides - [iOS Terminal SDK full guide](/terminal-payments/sdks/ios-sdk) - [Android Reader SDK full guide](/terminal-payments/sdks/android-sdk) # Cloud API > Details on using Solo card readers and processing remote in-person payments via the Cloud API. import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components'; import Video from '@components/content/Video.astro'; import SoloScreen from '@components/content/SoloScreen.astro'; The Cloud API lets you start a transaction from a Point of Sale (POS) running on any platform (Windows, iOS, Linux, Android, Web-based, etc.) capable of sending HTTPS requests and complete that transaction via a Solo reader. Key advantages include: - Compatibility with any operating system and platform - Ability to process simultaneous transactions on multiple Solo card readers at once - No distance limitation between your POS device and the Solo card 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 installment transactions - Pairing multiple Solo card readers with any SumUp account - Naming each Solo card reader as desired to streamline checkout - Wi-Fi and mobile data connectivity (mobile data needs manual enabling by SumUp) ## Prerequisites - Your device must be authorized to use the Cloud API. [Refer to the authorization guide](/tools/authorization/) and implement the method that best fits your use case. An API key should be sufficient if you don’t plan to delegate access to third parties. - You must [create an Affiliate Key](/tools/authorization/affiliate-keys/) for your app, as SumUp Cloud API requires this key in checkout requests. - We strongly recommend keeping the Solo terminal plugged in when using the Cloud API. - If you want to use mobile data, ensure you are not connected to Wi-Fi. Disconnect from Wi-Fi if necessary—when both mobile data and Wi-Fi are available, the Solo reader will always use Wi-Fi. To disconnect Wi-Fi, navigate to **Connections** > **Wi-Fi** and disable Wi-Fi using the on-screen slider. ## Solo Virtual Terminal If you don’t have a Solo reader yet, you can try out the flow using the [Virtual Solo](https://virtual-solo.sumup.com) with a [SumUp sandbox merchant account](/online-payments/#getting-a-sandbox-merchant-account). Virtual Solo works like the real device but with some limitations. The following actions are not supported virtually: - Physical card insertion or tap simulation (since there is no physical Solo device) - Real funds transfer (sandbox merchant accounts only) - PIN entry simulation (always auto-approved) - Offline transactions - Custom receipt printing - Network configuration - Real device pairing (the simulator uses virtual device identifiers) ## Pairing Solo Reader via Cloud API The Cloud API acts as a bridge between your application and the Solo reader. It supports two main processes: - Pairing a Solo reader to your account - Taking in-person payments via Solo Once the Solo reader is paired to your SumUp account, your application 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 in real-time via webhooks. ```mermaid sequenceDiagram title: Cloud API Overview participant A as Solo Reader participant B as Cloud API participant C as Your Device autonumber A ->> A: generate pairing code C ->> B: Pair Reader using code B ->> C: Return Reader ID B ->> A: Display confirmation message C ->> B: Start Checkout on Reader B ->> A: Initiate Checkout A ->> A: Present Checkout to Customer ``` ### Log out of Solo The Cloud API pairing process is only available for logged-out users. If you're logged in to your merchant account, do the following: 1. Open the top-side menu on your Solo. 2. Select **Settings**. The **Device settings** menu opens. 3. Go to the **About** section. 4. Select **Log out**. Solo should now display the login screen. ### Generate Pairing Code To initiate a payment on the Solo card 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 device completes a pairing request using the Cloud API with that code. Both your application and Solo reader must be connected to the internet (not necessarily the same network). 1. Turn on the Solo card reader. 2. Make sure you're not logged in. [Log out from your Solo card reader](#log-out-of-solo) if you are. 3. Open the top menu drawer 4. Go to **Connections** and connect to Wi-Fi (connecting is skipped in the short video below). 5. Select **API**. 6. Click **Connect**. The pairing code is generated. 7. Copy the pairing code displayed on the Solo card reader screen. You will need this code to pair your Solo reader with your device.