• `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

**Availability:** [Visa](https://www.visa.com/) is one of the most widely accepted global card networks for online debit and credit card payments. **Availability:** [Visa Electron](https://www.visa.com/) is a Visa debit card product commonly used for consumer card payments in supported markets. **Availability:** [V Pay](https://www.visa.co.uk/pay-with-visa/find-a-card/v-pay.html) is Visa's European debit card scheme designed for regional card acceptance. **Availability:** [Mastercard](https://www.mastercard.com/) is a global card network used for both credit and debit card payments. **Availability:** [Maestro](https://www.mastercard.com/) is Mastercard's debit card brand for everyday consumer payments. **Availability:** [American Express](https://www.americanexpress.com/) is a global card network widely used for consumer and business card payments. **Availability:** [Discover](https://www.discover.com/) is an international card network that can be used for online card payments in supported markets. **Availability:** [JCB](https://www.global.jcb/en/) is a global card network originating in Japan and accepted for online payments in supported regions. **Availability:** [Elo](https://www.elo.com.br/) is a Brazilian card scheme supported for online payments in Brazil. Additional niche local card schemes may also be supported. ## Wallets Wallets provide a faster checkout experience by reusing saved payment details or wallet balances. Wallets are useful when you want faster checkout on mobile and supported browsers. Apple Pay and Google Pay can be offered through [Payment Widget](/online-payments/checkouts/card-widget/), through the [Swift Checkout SDK](/online-payments/checkouts/swift-checkout/), or through their dedicated direct integration guides. **Availability:** [Apple Pay](https://www.apple.com/apple-pay/) is Apple's wallet-based checkout experience for Safari and Apple devices. **Availability:** [Google Pay](https://pay.google.com/about/) is Google's wallet checkout option for supported browsers, devices, and Android surfaces. **Availability:** [PayPal](https://www.paypal.com/) lets customers authorize payments using their PayPal account instead of entering card details directly. **Availability:** [SumUp Pay](https://www.sumup.com/) is SumUp's own payment experience for returning customers within the SumUp ecosystem. **Availability:** [BANCOMAT Pay](https://www.bancomat.it/en/bancomat-pay/) is an Italian account-linked mobile payment method operated by BANCOMAT. ## Bank Redirects Bank redirect methods send the customer to their bank or local payment network to approve the payment. These methods usually require you to handle a pending status and send the customer through an additional authorization step. Payment Widget handles this checkout experience for the customer. **Availability:** [Bancontact](https://bancontact.com/en) is Belgium's domestic online payment method for redirect-based checkout. **Availability:** [Blik](https://blik.com/en) is a Polish payment method that lets customers confirm payments through their banking app. **Availability:** [EPS](https://www.eps-ueberweisung.at/) is an Austrian online bank redirect method commonly used for domestic ecommerce payments. **Availability:** [iDeal](https://www.ideal.nl/en/) is the Netherlands' most widely used online banking payment method for ecommerce. **Availability:** [MyBank](https://www.mybank.eu/) is a European online bank payment scheme that redirects customers to authorize the transaction with their bank. **Availability:** [Przelewy24](https://www.przelewy24.pl/en) is a Polish online bank redirect method and payment network for local ecommerce checkout. **Availability:** [TWINT](https://www.twint.ch/en/) is a Swiss mobile payment method that supports wallet-style and bank-linked payments. ## Bank Debits Bank debit methods collect funds directly from the customer's bank account. Bank debit methods can require additional customer details depending on the checkout flow. ## Real-Time Payments Real-time payment methods confirm funds immediately and are commonly used for local account-to-account payment flows. Some real-time methods return payment artifacts such as QR codes instead of using a browser redirect. **Availability:** [PIX](https://www.bcb.gov.br/estabilidadefinanceira/pix) is Brazil's instant payment system for real-time account-to-account transfers. **Availability:** [QR Code powered by PIX](https://www.bcb.gov.br/estabilidadefinanceira/pix) lets customers complete a PIX payment by scanning a generated QR code. ## Vouchers Voucher-based methods generate a payment artifact that the customer uses to complete the purchase. Voucher methods are asynchronous by nature and rely on a payment artifact that the customer uses to complete the payment. **Availability:** [Boleto](https://portal.febraban.org.br/pagina/3166/33/en/) is a Brazilian voucher-based payment method where the customer pays using a generated boleto document or barcode. :::tip Availability still depends on merchant setup, checkout product, and account configuration. For implementation details, see [Alternative Payment Methods](/online-payments/apm/) and the [Payment Widget](/online-payments/checkouts/card-widget/). ::: # Plugins > Overview of SumUp plugins for third-party platforms. import PluginsList from '@components/OnlinePayments/PluginsList'; These plugins enable quick SumUp payment integration on PrestaShop, Wix, WooCommerce, Medusa, and Vendure requiring only your API key and merchant information to start. Select a plugin of interest for further, detailed instructions. # Medusa > Accept SumUp payments in Medusa with the SumUp plugin for Medusa v2. import { LinkButton } from "@astrojs/starlight/components"; The [SumUp plugin for Medusa](https://github.com/sumup/sumup-plugin-medusa) adds SumUp as a payment provider for [Medusa v2](https://medusajs.com/). It lets your Medusa backend create and manage SumUp online checkouts while keeping your SumUp credentials on the server side. The plugin supports: - Hosted Checkout, where the customer is redirected to a SumUp-hosted payment page - Payment Widget, where your storefront mounts the SumUp Payment Widget using a checkout created by Medusa - Refunds through SumUp transactions - Medusa payment webhooks for asynchronous status updates :::note The plugin supports SumUp online payment flows only. It does not support terminal or other card-present integrations. ::: View Medusa Plugin Repository ## Prerequisites - Active [SumUp account](https://me.sumup.com) - SumUp [API key](/tools/authorization/api-keys/#create-an-api-key) - SumUp merchant code - Medusa `v2.15.x` - A Medusa backend with the payment module enabled Before going live, make sure your SumUp account is fully verified and your business model is supported according to our [allowed businesses article](https://help.sumup.com/en-GB/articles/3G8ZHjdgFZjmKWOmDWS52m). ## Install the Plugin Install the package in your Medusa project: ```bash yarn add @sumup/medusa-plugin ``` ## Configure Medusa Register the plugin and payment provider in `medusa-config.ts`: ```ts import { defineConfig } from "@medusajs/framework/utils"; export default defineConfig({ plugins: [ { resolve: "@sumup/medusa-plugin", options: {}, }, ], modules: [ { resolve: "@medusajs/medusa/payment", options: { providers: [ { resolve: "@sumup/medusa-plugin/providers/sumup", id: "sumup", options: { apiKey: process.env.SUMUP_API_KEY, merchantCode: process.env.SUMUP_MERCHANT_CODE, checkoutMode: "hosted", returnUrl: `${process.env.MEDUSA_BACKEND_URL}/hooks/payment/sumup_sumup`, redirectUrl: `${process.env.STOREFRONT_URL}/checkout/sumup/return`, }, }, ], }, }, ], }); ``` After your application starts, enable the provider for the relevant region in Medusa Admin. For the service identifier `sumup` and provider `id` `sumup`, the resulting Medusa payment provider identifier is `pp_sumup_sumup`. ## Configuration Options The plugin accepts the following provider options: | Option | Required | Description | | --- | --- | --- | | `apiKey` | Yes | SumUp API key or access token. Keep it server-side. | | `merchantCode` | Yes | SumUp merchant code that receives the payment. | | `checkoutMode` | No | Checkout mode: `hosted` or `widget`. Defaults to `hosted`. | | `returnUrl` | No | Backend webhook URL. For provider `id: "sumup"`, use `/hooks/payment/sumup_sumup`. | | `redirectUrl` | No | Storefront URL used after redirect or Strong Customer Authentication flows. | | `paymentDescription` | No | Default SumUp checkout description. | | `timeout` | No | SumUp SDK request timeout in milliseconds. | | `maxRetries` | No | SumUp SDK retry count. | You can also override `checkout_mode`, `description`, `return_url`, `redirect_url`, and `checkout_reference` per payment session through provider data. ## Choose a Checkout Flow ### Hosted Checkout With `checkoutMode: "hosted"`, the plugin creates a SumUp checkout with Hosted Checkout enabled and stores the returned `hosted_checkout_url` in the Medusa payment session. Your storefront should redirect the customer to that URL to complete the payment. Use your backend state as the source of truth. The redirect alone should not be treated as proof of a successful payment. ### Payment Widget With `checkoutMode: "widget"`, the plugin creates a SumUp checkout and stores the returned `checkout_id` in the payment-session data. Your storefront is then responsible for loading and mounting the SumUp widget and asking the backend to re-check the payment state after a successful widget response. If you need a lower-level widget implementation reference, see the [Payment Widget guide](/online-payments/checkouts/card-widget/). ## Webhooks Medusa provides a built-in webhook listener route for payment providers at: ```text /hooks/payment/[identifier]_[provider] ``` For this plugin, with service identifier `sumup` and provider `id` `sumup`, the webhook URL is: ```text https://your-medusa-backend.com/hooks/payment/sumup_sumup ``` The plugin receives the webhook payload, retrieves the checkout from SumUp, maps the result to a Medusa payment action, and returns the payment session reference back to Medusa. ## What the Plugin Stores The payment-session data returned by the provider includes: - `checkout_id` - `checkout_reference` - `checkout_mode` - `hosted_checkout_url` for hosted flows - `transaction_id` and `transaction_code` when available - `merchant_code` - `amount` and `currency` ## Sandbox Checklist Before enabling the plugin in production, verify the following in a sandbox environment: - One successful Hosted Checkout payment - One successful Payment Widget payment - At least one webhook-driven payment update - One full refund and one partial refund - SumUp's deliberate failure path with amount `11` - Expired or canceled checkouts mapping cleanly back into Medusa session state :::note Minimal storefront and Docker example projects are available in the plugin repository if you want a working reference implementation. ::: # PrestaShop > Accept SumUp payments with the PrestaShop plugin. import { LinkButton } from '@astrojs/starlight/components'; To use PrestaShop with SumUp, download the SumUp Payment module plugin, which requires configuration in your SumUp dashboard. Download PrestaShop Plugin ## Prerequisites You will need an active [SumUp account](https://me.sumup.com). As an authorized Payment Institution by the Central Bank of Ireland, SumUp must verify your identity and business ownership. Please make sure your [business model is supported by SumUp](https://help.sumup.com/en-GB/articles/3G8ZHjdgFZjmKWOmDWS52m). :::note Currently, Alternative Payment Methods (APMs) are not available in SumUp plugins. We are working to support APMs soon. ::: ## Installation 1. Follow [the register application guide](/tools/authorization/oauth/#register-an-oauth-application) to obtain the client credentials for your app. 2. Download the client credentials file. 3. Upload the JSON to the **Module Configuration** page in PrestaShop Backoffice. 4. After SumUp account verification, [contact us](/contact) to enable online payments scope for your PrestaShop online store.  Once you receive a confirmation from SumUp, you’re fully set-up! Note that minimum transaction amount is 1 EUR (or equivalent). :::note Still need help? Contact our [customer service](https://me.sumup.com/en-gb/support) for assistance. ::: # Vendure > Accept SumUp payments in Vendure with the SumUp plugin. import { LinkButton } from "@astrojs/starlight/components"; The [SumUp plugin for Vendure](https://github.com/sumup/sumup-plugin-vendure) adds SumUp as a payment integration for [Vendure](https://vendure.io/). It creates SumUp checkouts from Vendure's payment flow while keeping your SumUp credentials on the server side. The plugin supports: - Hosted Checkout, where the customer is redirected to a SumUp-hosted payment page - Widget-oriented storefront integrations that use a returned `checkoutId` - Webhook-driven payment updates through Vendure's payment flow :::note The plugin supports SumUp online payment flows only. It does not support terminal or other card-present integrations. ::: View Vendure Plugin Repository View Vendure Plugin Docs ## Prerequisites - Active [SumUp account](https://me.sumup.com) - SumUp [API key](/tools/authorization/api-keys/#create-an-api-key) - SumUp merchant code - Vendure `^3.6.4` - A Vendure server with payment methods enabled Before going live, make sure your SumUp account is fully verified and your business model is supported according to our [allowed businesses article](https://help.sumup.com/en-GB/articles/3G8ZHjdgFZjmKWOmDWS52m). ## Install the Plugin Install the package in your Vendure project: ```bash npm install @sumup/vendure-plugin ``` ## Configure Vendure Register the plugin and payment handler in your Vendure config: ```ts import { VendureConfig } from "@vendure/core"; import { SumUpPlugin, sumUpPaymentHandler, } from "@sumup/vendure-plugin"; export const config: VendureConfig = { plugins: [ SumUpPlugin.init({ apiKey: process.env.SUMUP_API_KEY!, merchantCode: process.env.SUMUP_MERCHANT_CODE!, checkoutMode: "hosted", returnUrl: "https://your-vendure.example/payments/sumup/webhook", redirectUrl: "https://storefront.example/checkout/sumup/return", }), ], paymentOptions: { paymentMethodHandlers: [sumUpPaymentHandler], }, }; ``` `returnUrl` should be a publicly reachable URL that SumUp can call with checkout status updates. In most setups that should be your Vendure server's `/payments/sumup/webhook` route. ## Create the Payment Method Create a payment method in the Vendure Admin UI with: - `Code`: `sumup` - `Handler`: `sumup` Optional handler arguments: - `merchantCode` - `checkoutMode` - `returnUrl` - `redirectUrl` - `paymentDescription` Global defaults can be defined in `SumUpPlugin.init()` and overridden per payment method when needed. ## Storefront Flow Once the order is in `ArrangingPayment`, call `addPaymentToOrder` with `method: "sumup"` and any SumUp-specific metadata you need: ```graphql mutation AddPaymentToOrder { addPaymentToOrder( input: { method: "sumup" metadata: { checkout_mode: "hosted" checkout_reference: "ORDER-1001" } } ) { ... on Order { id state payments { transactionId metadata } } ... on ErrorResult { errorCode message } } } ``` The plugin stores SumUp data on the Vendure payment and exposes a safe subset through `payments[].metadata.public`. ## Choose a Checkout Flow ### Hosted Checkout Use `checkout_mode: "hosted"` or set `checkoutMode: "hosted"` in the plugin or payment-method config. After `addPaymentToOrder`, redirect the shopper to: ```text payments[].metadata.public.hostedCheckoutUrl ``` Use your backend payment state as the source of truth. The redirect alone should not be treated as proof of a successful payment. ### Widget-Oriented Flow Use `checkout_mode: "widget"` if your storefront will mount SumUp's checkout UI itself. After `addPaymentToOrder`, read: ```text payments[].metadata.public.checkoutId ``` Use that `checkoutId` in your storefront's SumUp client integration. The plugin still treats the webhook callback or a later checkout lookup as the source of truth for the final payment state. If you need a lower-level widget implementation reference, see the [Payment Widget guide](/online-payments/checkouts/card-widget/). ## Webhooks The plugin exposes a notification endpoint at: ```text POST /payments/sumup/webhook ``` When SumUp calls this endpoint, the plugin re-fetches the checkout from SumUp and updates the matching Vendure payment from the checkout state. ## Public Payment Metadata The plugin exposes these fields in `payments[].metadata.public`: | Field | Description | | --- | --- | | `checkoutId` | SumUp checkout ID | | `checkoutReference` | Merchant checkout reference sent to SumUp | | `checkoutMode` | `hosted` or `widget` | | `hostedCheckoutUrl` | Hosted Checkout URL when SumUp returns one | | `redirectUrl` | Redirect URL associated with the checkout | ## Configuration Options | Option | Required | Description | | --- | --- | --- | | `apiKey` | Yes | SumUp API key or access token. Keep it server-side. | | `merchantCode` | Yes | SumUp merchant code that receives the payment. | | `defaultLanguageCode` | No | Language used for the handler description shown in Vendure. | | `checkoutMode` | No | Default checkout mode: `hosted` or `widget`. Defaults to `hosted`. | | `returnUrl` | No | Backend callback URL used by SumUp for checkout status updates. | | `redirectUrl` | No | URL the shopper is sent to after redirect-based payment flows. | | `paymentDescription` | No | Default SumUp checkout description. | | `timeout` | No | SumUp SDK request timeout in milliseconds. | | `maxRetries` | No | SumUp SDK retry count. | | `supportedCurrencies` | No | Override the built-in supported currency allowlist. | | `client` | No | Inject a custom SumUp client implementation. Useful for tests. | ## Payment State Mapping The plugin maps SumUp checkout state to Vendure payment state like this: - Successful transaction or `PAID` checkout -> `Settled` - `PENDING` -> `Authorized` - `FAILED` -> `Declined` - `EXPIRED` -> `Cancelled` - Anything else -> `Created` ## Sandbox Checklist Before enabling the plugin in production, verify the following in a sandbox environment: - One successful Hosted Checkout payment - One successful widget-oriented payment flow - At least one webhook-driven payment update - SumUp's deliberate failure path with amount `11` - Expired or canceled checkouts mapping cleanly back into Vendure payment state :::note The plugin does not add Admin UI extensions or extend Vendure's GraphQL schema. It uses the standard `addPaymentToOrder` payment metadata flow. ::: # Wix > Accept SumUp payments on your Wix online store. Connect your [Wix online store](https://wix.com) dashboard to SumUp for secure payment processing through our payment gateway, as explained in this guide. :::note New onboarding for the Wix integration has been temporarily paused since **March 2025**. If you’re already using the integration, you can continue processing payments. For updates or alternatives, contact us via the [contact form](/contact). ::: ## Prerequisites - Active [SumUp account](https://me.sumup.com). If you don't have one yet, sign up on [our website](https://me.sumup.com/signup). As an authorized Payment Institution by the Central Bank of Ireland, SumUp must verify your identity and business ownership. - Business model supported by SumUp, according to our [allowed businesses article](https://help.sumup.com/en-GB/articles/3G8ZHjdgFZjmKWOmDWS52m). - Wix online store. The Wix integration supports the following Alternative Payment Methods (APMs): iDeal (Netherlands), Bancontact (Belgium), P24 (Poland), EPS (Austria). Apple Pay and Google Pay are currently unavailable. ## Installation 1. First, create your secret API Key. [See this article](/tools/authorization/api-keys/#create-an-api-key) for details. Copy your key before proceeding. 2. In the Wix dashboard, go to **Settings** > **Accept payments**. 3. Select **SumUp**, paste your secret API Key in **Account Information**, and **Save**. That's it! You can now start accepting payments through SumUp on your Wix online store. If you have any questions or encounter any issues, contact our [customer service](https://me.sumup.com/en-gb/support) team. # WooCommerce > Accept SumUp payments with the WooCommerce plugin. import { LinkButton } from "@astrojs/starlight/components"; The [SumUp Payment Gateway for WooCommerce](https://wordpress.org/plugins/sumup-payment-gateway-for-woocommerce/) enables payments on WordPress sites without coding, enabling your customizations and providing your customers the convenience of securely buying products from your website without being redirected to other pages. The plugin supports major cards (Visa, Mastercard, Amex, Diners, Discover, JCB) via embedded forms. Transactions are processed through the SumUp payment platform with [transaction history provided in the SumUp Dashboard](https://me.sumup.com/sales/transactions). :::note The SumUp WooCommerce plugin is SCA ready and compliant with PCI standards. ::: Go to plugin page ## Prerequisites - Active [SumUp account](https://me.sumup.com). If you don't have one yet, sign up on [our website](https://me.sumup.com/signup). As an authorized Payment Institution by the Central Bank of Ireland, SumUp must verify your identity and business ownership. - [Review allowed businesses](https://help.sumup.com/hc/en-gb/articles/115008338707-Restricted-businesses) before [signing up](https://me.sumup.com). ## Installing the Plugin ### Automatic Installation The automatic installation is the easiest option, as WordPress handles the file transfer and you don't need to leave your web browser. 1. Install the plugin via the **Plugins** section in the WordPress Dashboard. 2. Click on **Add new** and search for **SumUp Payment Gateway for WooCommerce**. 3. Click on the **Install Now** button. 4. Click **Activate** to active the plugin. ### Manual Installation 1. [Download our plugin](https://wordpress.org/plugins/sumup-payment-gateway-for-woocommerce/). 2. Upload it to your web server using FTP. See [WordPress codex](https://wordpress.org/support/article/managing-plugins/#manual-upload-via-wordpress-admin) for details on how to do this. Before setting up the plugin, create your client credentials. ## Integration Options For plugin versions `2.5` or later, both a [simple](#simple-integration) and [advanced](#advanced-integration) integration flows are available. If you are using a plugin version below `2.5`, follow the steps in our [advanced integration guide](#advanced-integration). ### Simple Integration Available for plugin versions above `2.5`. 1. Click **Connect account** to initiate the lightweight integration flow (redirects to SumUp Dashboard). 2. In your SumUp Dashboard, click on **Start setup** to generate your production API keys. Once the flow is initiated, we will take care of generating live API keys for your SumUp account. When the flow completes successfully, they will become available to your WordPress shop. At this point, you can start accepting payments through SumUp on your WordPress shop. :::note The [Online Payments settings page](https://me.sumup.com/settings/online-payments) in the SumUp Dashboard, allows you to view your plugin connections and manage payment method settings. :::  ### Advanced Integration 1. Once the plugin is activated, click **Advanced version**. 2. [Create your API Key](/tools/authorization/api-keys/#create-an-api-key). 3. Enter SumUp credentials (API Key, email, and merchant code) and settings. ## Additional Configuration - Enable the SumUp Payment Gateway - Set customer-facing title/description - Apply an optional payment method description, visible by your customers - Match shop currency to SumUp account - Require ZIP code from your customers. **Mandatory for US merchants** - We recommend enabling the logging option for better troubleshooting should any issues occur (logs can be found in **WooCommerce** > **Status** > **Logs**) - Choose between popup or embedded payment form with the **Open Payment in modal?** option ### Update Your Website Before accepting payments through SumUp, your website should display the following information: - Business & product information - Delivery, cancellation & return/refund policy - Payment & billing process - All prices must have the respective currency prefix - Privacy policy - Security policy :::note We recommend configuring a "Thank You" page for successful checkouts, according to [WooCommerce official standards](https://docs.woocommerce.com/document/woocommerce-custom-thank-you-pages/). ::: ## Configuration for Legacy Plugin (Version Older than 2.5) ### Create Your Client Credentials To create client credentials you must have an active [SumUp account](https://me.sumup.com) with completed [account details](https://me.sumup.com/account). Your account has successfully completed the onboarding process, and you have received the `payments` scope activation. If you don't have the `payments` scope activated yet, [contact us](/contact) for assistance. :::caution SumUp aims to respond to all [contact queries](/contact) within 24 hours, Monday through Friday. ::: Once you ensure you've met the above requirements, you can proceed with our [Register application guide](/tools/authorization/oauth/#register-an-oauth-application) to set up your client credentials. ## Plugin Configuration Now that you have created your client credentials and installed the plugin, you can proceed with configuration. In WordPress Dashboard, go to **Plugins** `. **Settings** under the SumUp WooCommerce plugin. You will find the following customization options: - Enable the SumUp Payment Gateway - Apply custom title of the payment method, visible by your customers - Apply an optional payment method description, visible by your customers - Apply your shop currency corresponding to the one set in your SumUp account - **Client ID** and **Client Secret** of your application. Both are located in the JSON file you created in the [Create your client credentials step](#create-your-client-credentials), in the following key-value pair: ```json { "id": "CCCFAXYD", "name": "My Online Store Name", "client_id": "fOcmczrYtYMJ7Li5GjMLLcUeC9dN", "client_secret": "717bd571b54297494cd7a79b491e8f2c1da6189c4cc2d3481380e8366eef539c", "application_type": "web", "redirect_uris": ["https://mywebsite.com/callback"] } ``` - The email address of your SumUp merchant account - The merchant code associated with your SumUp account - Require ZIP code from your customers. **Mandatory for US merchants** - We recommend enabling logs for better troubleshooting, should any issues occur (Logs can be accessed in **WooCommerce** > **Status** > **Logs**) # 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 { Tabs, TabItem } from '@astrojs/starlight/components'; 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. ### 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 :::caution The backend doesn't process payments with Apple Pay and an error message will be displayed after attempting to pay with it. This is a known issue and a fix is being worked on. ::: #### 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', }, }); ``` # Testing > Learn how to test online payments using a sandbox merchant account and test cards with different 3D Secure flows. import { 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 [Developer Settings](https://me.sumup.com/settings/developer?tab=sandboxes). 3. In the **Sandboxes** tab, create a sandbox merchant account if you do not have one yet. :::note If you don't have a sandbox account yet, [sign up for a developer account](https://me.sumup.com/signup?signup_intent=developer). This starts you with a sandbox merchant account. ::: :::note Sandbox merchant accounts **do not** process transactions with real funds. All transactions are simulated for testing purposes only. ::: ## 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/30`) - **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 `11.00`, `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. Use the [Payment Widget](/online-payments/checkouts/card-widget/) to test card payments. It handles authentication screens and redirect behavior for you. ### 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 :::caution Remember to switch from your sandbox merchant account to your live merchant account before accepting real payments from customers. ::: [^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. 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. :::note After receiving a webhook call, your application must **always** verify if the event really took place, by calling a relevant SumUp's API. ::: 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 Authorized Token](/problem/not-authorised-token) - [Unauthorized](/problem/unauthorized) - [Forbidden](/problem/forbidden) - [Request Blocked](/problem/request-blocked) - [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 > Understand the SumUp API Bad Request response, common causes, and example payload for malformed requests. 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 > Understand the SumUp API Checkout Not Found response, common causes, and example payload for unknown checkout resources. 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 > Understand the SumUp API Forbidden response, common causes, and example payload for requests blocked by permissions. 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 > Understand the SumUp API Gateway Timeout response, common causes, and example payload for upstream timeout failures. 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 > Understand the SumUp API Internal Server Error response, common causes, and example payload for unexpected server failures. 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, "detail": "The service is temporarily unavailable.", "trace_id": "8cb5b380896b" } ``` When contacting support, include the `trace_id` or `ray_id` value from the response, whichever is available, so we can trace the failed request. # Invalid Parameter > Understand the SumUp API Invalid Parameter response, common causes, and example payload for requests with an invalid field value. 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 > Understand the SumUp API Invalid Token response, common causes, and example payload for malformed or unusable access tokens. 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 > Understand the SumUp API Missing Token response, common causes, and example payload for unauthenticated requests. 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 > Understand the SumUp API Multiple Invalid Parameters response, common causes, and example payload for requests with several invalid fields. 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 Authorized Token > Understand the SumUp API Not Authorised Token response, common causes, and example payload for invalid token authorization. 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 > Understand the SumUp API Not Found response, common causes, and example payload for missing resources. 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 > Understand the SumUp API Payment Method Not Allowed response, common causes, and example payload for unsupported payment methods. 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" } ``` # Request Blocked > Understand the SumUp API Request Blocked response, common causes, and example payload for requests blocked by security policy. Indicates that the request was blocked before it reached the SumUp API service. This can happen when a security policy, firewall rule, or traffic protection rule rejects the request. ## Common Causes - The request matched a security or firewall rule. - The request came from a blocked IP address, country, or network. - The request pattern looked automated, abusive, or otherwise unsafe. ```json { "type": "https://developer.sumup.com/problem/request-blocked", "title": "Request blocked.", "status": 403, "detail": "The request was blocked by security policy.", "trace_id": "8cb5b380896b" } ``` When contacting support, include the `trace_id` or `ray_id` value from the response, whichever is available, so we can trace the failed request. # Session Already Processed > Understand the SumUp API Session Already Processed response, common causes, and example payload for completed checkout sessions. 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 > Understand the SumUp API Session Can't Be Deactivated response, common causes, and example payload for non-cancellable sessions. 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 > Understand the SumUp API Session Expired response, common causes, and example payload for expired checkout sessions. 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 > Understand the SumUp API Unauthorized response, common causes, and example payload for invalid or expired credentials. 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 > Understand the SumUp API Unknown Payment Method response, common causes, and example payload for unrecognized payment methods. 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 > Understand the SumUp API Unprocessable Entity response, common causes, and example payload for semantically invalid requests. 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 > Understand the SumUp API Validation Failed response, common causes, and example payload for requests that do not pass validation. 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 > Learn how SumUp supports PSD2 Open Banking, including merchant impact, TPP access, and interface performance reports. 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 payment service 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 payment account information and initiate payments through authorized third-party payment service providers (TPPs). Users can control this through a dedicated interface where they manage access levels between the Account Information Service (AIS) and Payment Initiation Service (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) | | 1st January 2026 | to | 31st March 2026 | [UK](/open-banking-reports/REP026_Q1_UK_REP024.pdf) [IE](/open-banking-reports/REP026_Q1_EU_REP024.pdf) | | 1st April 2026 | to | 30th June 2026 | [UK](/open-banking-reports/REP026_Q2_UK_REP024.pdf) [IE](/open-banking-reports/REP026_Q2_EU_REP024.pdf) | # In-Person Payments > Understand SumUp's in-person payment integrations, supported readers, and how to choose between SDKs, Cloud API, and Payment Switch. import ReaderGallery from '@components/content/ReaderGallery.astro'; import Confirm from '@components/content/Confirm.astro'; SumUp's in-person payment products let you accept card payments face-to-face using physical card readers or Tap to Pay on a mobile device. You can integrate them into your own app or system using our [Reader SDKs](/terminal-payments/sdks/), [Cloud API](/terminal-payments/cloud-api/), or, for legacy app handoff flows, [Payment Switch](/terminal-payments/payment-switch/). This section helps you choose the right integration, understand reader compatibility, and get to your first payment quickly. Need device-specific details? Browse the [reader guides](/terminal-payments/readers/). ## How It Works Every in-person payment follows the same basic pattern: 1. Your app or system initiates a payment with the amount, currency, and optional metadata. 2. A reader, or the phone itself for Tap to Pay, presents the card interface to the customer. 3. The customer taps, inserts, or swipes their card. 4. SumUp processes the transaction and returns the result. How the payment is initiated and where the UI runs depends on the integration path you choose. ## Choose Your Integration There are three ways to integrate SumUp in-person payments: | | Cloud API | Reader SDKs | Payment Switch | | --------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | **What it does** | Trigger and manage payments on Solo or Go readers via HTTPS requests. | Embed payment acceptance directly in your Android or iOS app. Your app controls the reader over Bluetooth or uses Tap to Pay. | Hand off payment acceptance from your app to the SumUp app, then return to your app when the payment is done. | | **Best for** | Kiosk, POS, or web-based systems where the reader operates independently. | Mobile apps that need more control over the payment flow and user experience. | Quick integrations where you do not need to own the payment UI. | | **Platform** | Any server-capable platform | Android, iOS | Android, iOS | | **Reader connection** | Wi-Fi or cellular | Bluetooth from your app, or Tap to Pay on device | Bluetooth via the SumUp app | ## Feature Support by Integration Different integration paths support different features: | Feature | Android SDK | iOS SDK | Android Tap-to-Pay SDK | Cloud API | | --- | --- | --- | --- | --- | | **Card payments** | NFC and chip | Reader payments with NFC and chip, plus Tap to Pay on iPhone | NFC only | NFC and chip | | **Tipping** | | | | | | **Refunds** | Via SumUp API | Via SumUp API | Contact SumUp for current support details | | | **Receipts** | Via SumUp API | Via SumUp API | Contact SumUp for current support details | Via SumUp API | | **Offline transactions** | | | — | — | | **Reader status via API** | | | | | | **Multiple readers on one account** | — | — | — | | | **Webhooks for transaction status** | — | — | — | | ## Reader Compatibility Not every reader works with every integration: | Reader | Android SDK | iOS SDK | Android Tap-to-Pay SDK | Cloud API | Payment Switch | | --- | --- | --- | --- | --- | --- | | [**Solo Lite**](/terminal-payments/readers/solo-lite/) | | | — | — | | | [**Solo**](/terminal-payments/readers/solo/) | | | — | | | | [**Air**](/terminal-payments/readers/air/) | | | — | — | | | [**3G**](/terminal-payments/readers/3g/) | | | — | — | | | [**PIN+**](/terminal-payments/readers/pin-plus/) | | | — | — | | | [**Tap to Pay**](/terminal-payments/readers/tap-to-pay/) | — | | | — | — | | [**Go**](/terminal-payments/readers/go/) | — | — | — | | — | ## Market Availability Reader availability varies by region. Check the SumUp webshop in your country before planning a rollout. Once a reader processes its first transaction with a merchant account from a specific country, it is locked to that country. For example, if the first payment is processed with a French account, that reader can only be used with French accounts afterward. ## Next Steps - Ready to build? Start with the [Quickstart](/terminal-payments/quickstart/). - Building a native mobile app? Go to the [Reader SDKs](/terminal-payments/sdks/). - Building a server-driven or multi-platform POS? Use the [Cloud API](/terminal-payments/cloud-api/). - Only need an app-to-app handoff? Review [Payment Switch](/terminal-payments/payment-switch/). # Cloud API > Details on using Solo card readers and processing remote in-person payments via the Cloud API. import { 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. :::tip You can start building with the Cloud API before you order or receive a physical Solo reader. Use [Virtual Solo](https://virtual-solo.sumup.com) together with a [sandbox merchant account](/terminal-payments/quickstart/#sandbox-merchant-account) to test the pairing and checkout flow first, then switch to a physical reader later to validate hardware-specific behavior. See [Solo Virtual Terminal](#solo-virtual-terminal) for the supported limitations. ::: 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](/terminal-payments/quickstart/#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). :::note The pairing process has an expiration time of 5 minutes, if any issue occurs, the process must be restarted. ::: 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.