This is the full developer documentation for SumUp Developer
# Getting started
Welcome to the SumUp Developer Portal. Here you’ll find everything you need to integrate SumUp’s payment solutions into your product. The documentation is divided into several sections:
* **[Quick start](/docs/quickstart/)** – set up a test account and run through a first payment in minutes.
* **[Online Payments](/docs/online-payments/)** – accept card payments on the web or in mobile apps.
* **[Terminal Payments](/docs/terminal-payments/)** – use SumUp card readers to take in-person payments.
* **[Tools](/docs/tools/)** – explore our APIs, SDKs and other utilities.
Create a [test account](https://me.sumup.com) to experiment safely and then dive into the section that best fits your use case.
# Online Payments
> Get started with accepting online payments. The guide will take you through creating test profile to processing your first transaction in matter of minutes.
Online payments are an integral part of SumUp product portfolio. At SumUp, accepting online payments is possible through a number of different approaches, to cater every merchants’ use case. You can either use one of our out-of-the-box integrations, or build a complete and custom payments flow yourself using our APIs. Your app can communicate with SumUp via HTTP requests, all defined in our API Reference.
To get started, we will walk you through the options SumUp offers for managing online payments.
## Getting a test account
[Section titled “Getting a test account”](#getting-a-test-account)
To start testing SumUp APIs and tools without involving real money, you need to have a test account. You can create a test account from your account in the Dashboard as shown below.
1. Log in to your SumUp account.
2. Open the drop-down menu between Support and your user panel.
3. Select Test Account. Your merchant account is now switched to test mode.
A screenshot of the account selection dropdown in the SumUp dashboard with the test account highlighted with red circle
Once you have your test account you can begin making API calls with real data. Our test accounts **do not** process transactions with real funds. Test account has a different ID, and shows a clear warning. When you try to process a request with the value of 11 (in any currency), the test account will always fail - this is by design, to enable testing failed transactions.
A screenshot of the dashboard with test account selected
When you’re done experimenting with the test account, switch back to a regular account for business purposes.
## Authorization
[Section titled “Authorization”](#authorization)
All Online Payment products consume SumUp APIs, which requires a means of authorization - either an API Key or Access Token. Check the [Authorization Guide](/tools/authorization/authorization/) for details on the available authorization options in SumUp.
## Checkout Products
[Section titled “Checkout Products”](#checkout-products)
SumUp provides a range of checkout products for seamless integration with your website.
### SumUp Card Widget
[Section titled “SumUp Card Widget”](#sumup-card-widget)
For a quick and seamless integration, we’ve developed a sleek payment widget. Incorporating the [SumUp Card Widget](/online-payments/checkouts/card-widget/) only requires adding a single script to your payment page!
#### Alternative Payment Methods
[Section titled “Alternative Payment Methods”](#alternative-payment-methods)
The Card Widget supports [Alternative Payment Methods](/online-payments/apm) (APMs), which enable you to accept payments other than traditional card schemes (Visa or Mastercard). APMs can be accessed through the [SumUp Card Widget](/online-payments/checkouts/card-widget/). Request access by contacting us via our [contact form](/contact).
At SumUp you can make use of the following APMs:
* Apple Pay
* Bancontact
* Blik
* Boleto
* EPS
* Google Pay
* iDeal
* MyBank
* PIX
* Przelewy24
* Satispay
Tip
The APMs you can offer depend on the location your business is registered and operates in.
### SumUp Hosted Checkout
[Section titled “SumUp Hosted Checkout”](#sumup-hosted-checkout)
Hosted Checkout is an integration product that offers a complete checkout flow for payment collection. It aims at being easy to integrate and requires little to no code. The solution offers a summary of the checkout details and provides a complete flow for handling payment collection, covering the possible outcomes of payment attempts all the way to the success page.
See [Hosted Checkout Documentation](/online-payments/checkouts/hosted-checkout/) for more information.
### SumUp Swift Checkout SDK
[Section titled “SumUp Swift Checkout SDK”](#sumup-swift-checkout-sdk)
The Swift Checkout SDK enables you to offer a complete and fast checkout experience to your end users, allowing you to collect payment, address, and contact information with a click of a button.
See [Swift Checkout Documentation](/online-payments/sdks/swift-checkout/) for more information.
## Plugins
[Section titled “Plugins”](#plugins)
If you’re using Prestashop, Wix, or WooCommerce, good news! You can use one of our plugins to seamlessly get paid with SumUp. Please check the [Plugins section](/online-payments/plugins/) for details on each plugin.
## Custom Integrations
[Section titled “Custom Integrations”](#custom-integrations)
### SumUp APIs
[Section titled “SumUp APIs”](#sumup-apis)
SumUp provides REST API for most of its services like creating and executing payments, storing cards for future payments, issuing refunds among others. Our API uses either API Keys or [OAuth 2.0](http://tools.ietf.org/html/rfc6749) authorization standards to authenticate applications access to its services. We also support Cross-origin resource sharing (CORS) allowing web browsers securely to consume our API from a different domain origin.
The API receives requests and communicates responses mostly in [JSON](http://www.json.org) format, except for when the request needs to contain form encoded data. Typically, the requests are data objects consisting of name/value pairs sent to the SumUp API URI: **api.sumup.com**
### Receiving payments
[Section titled “Receiving payments”](#receiving-payments)
In order to receive payments, you need to [create a checkout](/online-payments/guides/single-payment/#1-create-a-checkout). Whether you would like to receive payments as a merchant directly, or initiate payments on a merchant’s behalf depends on the type of [authorization](/tools/authorization/authorization/) provided. Checkouts are created in a server-to-server communication. This ensures that you can keep your access token and client credentials secret and guarantees that sensitive checkout details, e.g. amount or recipient, cannot be changed.
[Completing checkouts](/online-payments/guides/single-payment/#2-complete-a-checkout) could be done via your web browser or mobile application, which guarantees you do not need to worry about sensitive data, like card data, ever hitting your servers and thus avoiding the need to be PCI DSS compliant.
Tip
A checkout can be completed in a browser only from a domain that is present as an authorized JavaScript origin when [creating your client credentials](/tools/authorization/register-app/#3-create-oauth-client-credentials).
SumUp provides flexibility to complete a checkout by offering a couple of integration approaches:
* You could build a [custom card form](/online-payments/guides/single-payment/#2-complete-a-checkout) that you must submit to the SumUp servers for processing
* You could use the [SumUp Card Widget](/online-payments/checkouts/card-widget/)
* You could process payments with [Alternative Payment Methods](/online-payments/apm), like Boleto, Bancontact & iDeal
* You could process [recurring payments](https://developer.sumup.com/online-payments/guides/recurring-payments)
Once you complete the checkout, you would have processed a payment successfully to a merchant’s SumUp account.
## Contact SumUp
[Section titled “Contact SumUp”](#contact-sumup)
Note
Do you have specific questions? Check out our [help page](/help) for the most frequently asked questions or [contact us here](/contact).
# 3-D Secure flow
> Learn about 3DS flow, SCA requirements, and how to handle 3DS when processing payments.
Caution
Affects all electronic payments accepted by merchants operating within the European Union.
SumUp is supporting 3-D Secure payments for an additional layer of security when it comes to online transactions.
EMVCo has developed 3D Secure 2, a new authentication protocol for payment card transactions, to meet the requirements of Strong Customer Authentication (SCA). This protocol will reduce fraud with its additional security layers, such as biometrics.
Note
The final deadline for implementing the SCA requirements was 31 December 2020.
[SCA (Strong Customer Authentication)](https://en.wikipedia.org/wiki/Strong_customer_authentication#cite_note-2) is an obligatory security measure that relies on two-factor authentication to verify the identity of the consumer in a payment transaction. As a result, these factors are strictly consumer-based. SCA can combine two of the following three factors, which must be strictly independent of each other:
* Something the customer knows (e.g. Password, PIN)
* Something the customer has (e.g. Phone, Token generator)
* Something the customer is (e.g. Fingerprint, Face ID)
Each of these elements must be independent from each other, to ensure the security of others is not compromised in the event of a security breach.
## How it works
[Section titled “How it works”](#how-it-works)
For the flow to be followed, both the merchant profile and the customer credit card issuer must support 3-D Secure.
The flow includes an additional step during checkout, that is shown depending on the card scheme and issuing bank.
## Integration for Single Payments
[Section titled “Integration for Single Payments”](#integration-for-single-payments)
To begin supporting the 3-D Secure flow, add the `redirect_url` parameter to your [create a checkout](/api/checkouts/create) request scheme. The parameter refers to a URL where the end user is redirected once the payment processing completes.
Proceed with [processing the checkout](/api/checkouts/process) which will return a response object (`next_step`) containing necessary details for the following **required** step for processing the payment.
Use the `next_step` content to redirect an end user to a challenge screen. The `next_step` object contains:
| Parameter | Value |
| -------------- | ----------------------------------------------------------------------------- |
| `method` | `POST` |
| `url` | `https://issuing-bank.com/acs?reqid=B69D8F090C031E959A3BB2C4D7DFE7F8F7C09B28` |
| `redirect_url` | `https://mysite.com/completed_purchase` |
| `mechanism` | `iframe` or `browser` |
| `payload` | `object` |
Caution
The **payload** object may contain zero or more key-value pairs, defining the payload request to be made. All provided parameters must be passed when redirecting an end-user.
As an example, the `payload` object may look like this:
```js
1
{
2
"arbitrary_param_name_1": "arbitrary_param_value_1",
3
"arbitrary_param_name_2": "arbitrary_param_value_2",
4
"arbitrary_param_name_3": "arbitrary_param_value_3",
5
"arbitrary_param_name_4": "arbitrary_param_value_4"
6
}
```
One approach for accomplishing the end user redirection is through a form:
```html
1
27
```
Once the form is submitted, the end user will be redirected to their issuer’s bank authentication screen, where the end-user must provide an additional authentication (e.g. a challenge token, SMS or other data). After submitting, SumUp completes the payment and the end user is redirected to the `redirect_url` appointed at the checkout creation, through a `GET` request with the corresponding `checkout_id` query parameter.
To confirm a checkout’s status, make a `GET` request to the [retrieve a checkout](/api/checkouts/get) endpoint.
# Alternative Payment Methods
> Learn about supported alternative payment methods, activation steps, and integration options.
Alternative Payment Methods (APMs) are forms of payments that are different from standard card schemes. They offer familiar and frictionless payment experiences to your customers, while making you stand out from your competitors offering only traditional payment experiences.
APMs have completely transformed how we once made online payments. For example, in the Netherlands more than half of the consumers use iDeal to pay online merchandise.
The types of APMs are prepaid cards, mobile payments, e-wallets, and “buy now, pay later” installment-based approaches.
## Supported Alternative Payment Methods
[Section titled “Supported Alternative Payment Methods”](#supported-alternative-payment-methods)
The APMs you can offer depend on the country your business is registered and operating in. Here’s a list of the currently available APMs at SumUp:
| APM | Country | |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - |
| Apple Pay | Austria, Belgium, Brazil, Bulgaria, Chile, Croatia, Cyprus, Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Hungary, Ireland, Italy, Latvia, Lithuania, Luxembourg, Malta, Netherlands, Norway, Poland, Portugal, Romania, Slovenia, Slovakia, Spain, Sweden, Switzerland, United Kingdom | |
| Bancontact | Belgium | |
| Blik | Poland | |
| Boleto | Brazil | |
| EPS | Austria | |
| Google Pay | Austria, Belgium, Brazil, Bulgaria, Chile, Croatia, Cyprus, Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Hungary, Ireland, Italy, Latvia, Lithuania, Luxembourg, Malta, Netherlands, Norway, Poland, Portugal, Romania, Slovenia, Slovakia, Spain, Sweden, Switzerland, United Kingdom | |
| iDeal | Netherlands | |
| MyBank | Greece, Italy, Spain | |
| PIX | Brazil | |
| Przelewy24 | Poland | |
| Satispay | Italy | |
## Enabling Alternative Payment Methods
[Section titled “Enabling Alternative Payment Methods”](#enabling-alternative-payment-methods)
As a **sole trader** APMs are automatically enabled in your profile after completing the regular registration steps and performing a test transaction with one of our remote payment products, such as [Payment Links](https://sumup.co.uk/payment-links/), [Invoices](https://sumup.co.uk/invoices) and [Online Store](https://sumup.co.uk/online-store/).
As with any other legal type, you must request the activation from our support team or via our [contact form here](/contact), providing us with your merchant ID (MXXXXX). Our team will onboard your profile and grant you access to the APMs applicable to your business location. Once your request is processed, APMs will instantly become available to you within [Payment Links](https://sumup.co.uk/payment-links/), [Invoices](https://sumup.co.uk/invoices) and [Online Store](https://sumup.co.uk/online-store/).
Note
At this time APMs are not available in our SumUp plugins.
## Integration
[Section titled “Integration”](#integration)
You can offer APMs through a number of approaches:
* Through the [SumUp Payment Widget](/online-payments/checkouts/card-widget). To make APM payments successful, you must always set a `redirect_url` upon [checkout creation](/api/checkouts/create). Beyond that step, the SumUp Payment Widget will handle the rest.
Note
Please note that Google Pay [Terms of Service](https://payments.developers.google.com/terms/sellertos) are applied to all Google Pay transactions via SumUp Payment Widget
* [API Integrations](/online-payments/apm/integration-guide/)
* Through the [Swift Checkout SDK](/online-payments/sdks/swift-checkout/)
* Direct Integration:
* [Apple Pay](/online-payments/apm/apple-pay)
* [Google Pay](/online-payments/apm/google-pay)
Caution
[Apple Pay](/online-payments/apm/apple-pay) and [Google Pay](/online-payments/apm/google-pay) direct integrations require domain verification in order to be implemented successfully.
# Apple Pay
> Learn how to integrate Apple Pay, including prerequisites, domain validation, and API calls.
In this guide, you will learn how to directly integrate Apple Pay with SumUp.
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
* You have a merchant profile with [SumUp](https://me.sumup.com/login) and have already filled in your [profile details](https://me.sumup.com/account).
* Get familiar with [Apple Pay on the Web guide](https://developer.apple.com/documentation/apple_pay_on_the_web).
* Offering Apple Pay requires registering with Apple on all web domains that will expose an Apple Pay button (includes TLD and subdomains). This is a requirement for production AND test environments.
* If you want to test payments without involving real funds, [create a test profile](/online-payments/#getting-a-test-account).
* Complete the domain onboarding setup steps described in your Dashboard under **Settings** > **For developers** > **Payment wallets**.
Screenshot of the dashboard Developer Settings, showing Payment wallets section that includes Apple Pay and Google Pay
## Accepting Apple Pay Payments With SumUp
[Section titled “Accepting Apple Pay Payments With SumUp”](#accepting-apple-pay-payments-with-sumup)
To begin your implementation, follow these steps:
1. [Create a checkout](https://developer.sumup.com/api/checkouts/create#create-a-checkout)
2. Create an [Apple Payment request](https://developer.apple.com/documentation/apple_pay_on_the_web/applepaypaymentrequest)
```js
1
const applePaymentRequest = {
2
currencyCode: "EUR",
3
countryCode: "DE",
4
merchantCapabilities: ["supports3DS"],
5
supportedNetworks: ["masterCard", "visa"],
6
total: {
7
label: "Demo",
8
amount: "0.00",
9
type: "final",
10
},
11
};
```
3. Initiate an [Apple Pay session](https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/2320659-applepaysession) and call the [begin method](https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/1778001-begin)
4. Listen for the `onvalidatemerchant` callback and collect the `validateUrl` property. Create the following payload
```json
1
{
2
"target": "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession",
3
"context": "your_domain_name"
4
}
```
and initiate a merchant session by calling
```http
1
PUT https://api.sumup.com/v0.1/checkouts/${checkoutId}/apple-pay-session
```
5. The response from the previous step is needed to complete the merchant validation with the [`completeMerchantValidation`](https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/1778015-completemerchantvalidation/) method
6. Submitting the payment dialogue triggers the `onpaymentauthorized` callback, this is when you need to [process the checkout](https://developer.sumup.com/api/checkouts/process#process-a-checkout). The process checkout request body needs to include a `payment_type` of `apple_pay` and an `apple_pay` object, containing the response from step 7
```json
1
{
2
"payment_type": "apple_pay",
3
"id": "9be2da07-a7bd-4877-bc0a-e16cd909a876",
4
"amount": 12,
5
"currency": "EUR",
6
"apple_pay": {
7
"token": {
8
"paymentData": {
9
"data": "si2xuT2ArQo689SfE-long-token",
10
"signature": "MIAGCSqGSIb3DQEHA-long-signature",
11
"header": {
12
"publicKeyHash": "PWfjDi3TSwgZ20TY/A7f3V6J/1rhHyRDCspbeljM0io=",
13
"ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEaBtz7UN2MNV0qInJVEEhXy10PU0KfO6KxFjXm93oKWL6lCsxZZGDl/EKioUHVSlKgpsKGin0xvgldfxeJVgy0g==",
14
"transactionId": "62e0568bc9258e9d0e059d745650fc8211d05ef7a7a1589a6411bf9b12cdfd04"
15
},
16
"version": "EC_v1"
17
},
18
"paymentMethod": {
19
"displayName": "MasterCard 8837",
20
"network": "MasterCard",
21
"type": "debit"
22
},
23
"transactionIdentifier": "62E0568BC9258E9D0E059D745650FC8211D05EF7A7A1589A6411BF9B12CDFD04"
24
}
25
}
26
}
```
Tip
Handling the responses from the API calls should be according to our public [API contract & guidelines](https://developer.sumup.com/api)
# Google Pay
> Learn how to integrate Google Pay, including domain registration, payment requests, and processing.
In this guide, you will learn how to directly integrate Google Pay with SumUp. This payment method is also available via the [SumUp Payment Widget](/online-payments/checkouts/card-widget/).
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
* You have a merchant profile with [SumUp](https://me.sumup.com/login) and have already filled in your [profile details](https://me.sumup.com/account).
* If you want to test payments without involving real funds, [create a test profile](/online-payments/#getting-a-test-account).
* Review [Google Pay API terms of service](https://payments.developers.google.com/terms/sellertos).
* Complete the domain onboarding setup steps described in your Dashboard under **Settings** > **For developers** > **Payment wallets**. You can read Google’s tutorial [Google Pay for Payments](https://developers.google.com/pay/api/web/guides/tutorial), which covers the requirements you’re expected to follow in order to successfully offer this payment method.
Screenshot of the dashboard Developer Settings, showing Payment wallets section that includes Apple Pay and Google Pay
## Accepting Google Pay Payments With SumUp
[Section titled “Accepting Google Pay Payments With SumUp”](#accepting-google-pay-payments-with-sumup)
Considering you’ve adhered to the prerequisites, the following steps will enable you to begin accepting Google Pay payments through SumUp:
1. Create a base payment request object, containing:
* `tokenizationSpecification` object with the following parameters:
* `gateway`- always equal to “sumup”
* `gatewayMerchantId`- your SumUp merchant code
* [`merchantInfo` object](https://developers.google.com/pay/api/web/reference/request-objects#MerchantInfo) with the following keys:
* `merchantId`- unique identifier provided to you by Google once you register your domain with them
* `merchantName`- your merchant name
```js
1
const baseRequest = {
2
apiVersion: 2,
3
apiVersionMinor: 0,
4
merchantInfo: {
5
merchantId: '123456789123456789'
6
merchantName: 'Example Merchant',
7
},
8
allowedPaymentMethods: [
9
{
10
type: 'CARD',
11
parameters: {
12
allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
13
allowedCardNetworks: ['MASTERCARD', 'VISA'],
14
},
15
tokenizationSpecification: {
16
type: 'PAYMENT_GATEWAY',
17
parameters: {
18
gateway: 'sumup',
19
gatewayMerchantId: 'exampleGatewayMerchantId',
20
},
21
},
22
},
23
],
24
};
```
2. Load the [Google Pay API JavaScript library](https://developers.google.com/pay/api/web/guides/tutorial#js-load) on the web page you will offer this payment method
3. Initialize a `PaymentsClient` object for the environment you are implementing
```js
1
const paymentsClient = new google.payments.api.PaymentsClient({
2
environment: 'TEST',
3
});
```
4. [Check readiness to pay](https://developers.google.com/pay/api/web/guides/tutorial#isreadytopay) with Google Pay API
5. [Launch the Google Pay button](https://developers.google.com/pay/api/web/guides/tutorial#add-button)
6. [Create a PaymentDataRequest](https://developers.google.com/pay/api/web/guides/tutorial#paymentdatarequest) using the baseRequest object and append the `transactionInfo` and `merchantInfo` objects. Your `PaymentDataRequest` should look like this:
```js
1
const paymentDataRequest = {
2
apiVersion: 2,
3
apiVersionMinor: 0,
4
merchantInfo: {
5
merchantName: 'Example Merchant',
6
},
7
allowedPaymentMethods: [
8
{
9
type: 'CARD',
10
parameters: {
11
allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
12
allowedCardNetworks: ['MASTERCARD', 'VISA'],
13
},
14
tokenizationSpecification: {
15
type: 'PAYMENT_GATEWAY',
16
parameters: {
17
gateway: 'sumup',
18
gatewayMerchantId: 'exampleGatewayMerchantId',
19
},
20
},
21
merchantInfo: {
22
merchantId: 'your_merchant_id',
23
merchantName: 'your_merchant_name',
24
},
25
transactionInfo: {
26
totalPriceStatus: 'FINAL',
27
totalPriceLabel: 'Total',
28
totalPrice: `${checkoutInfo.amount}`,
29
currencyCode: checkoutInfo.currency || 'EUR',
30
countryCode: 'DE',
31
},
32
},
33
],
34
};
```
7. [Create a checkout](/api/checkouts/create) with SumUp
8. [Call the `loadPaymentData`](https://developers.google.com/pay/api/web/reference/client#loadPaymentData) method and pass it the `PaymentDataRequest` as an argument. This method will respond in a Promise, where if resolved you will receive a `PaymentData` object
9. [Process the checkout](/api/checkouts/process). The process checkout request body needs to include a `payment_type` of `google_pay` and a `google_pay` object, containing the response from the previous step
```json
1
{
2
"payment_type": "google_pay",
3
"id": "6te2da07-a7bd-4877-bc0a-e16cd909a876",
4
"amount": 12,
5
"currency": "EUR",
6
"google_pay": {
7
"apiVersionMinor": 0,
8
"apiVersion": 2,
9
"paymentMethodData": {
10
"description": "Visa •••• 1111",
11
"tokenizationData": {
12
"type": "PAYMENT_GATEWAY",
13
"token": "token-data"
14
},
15
"type": "CARD",
16
"info": {
17
"cardNetwork": "VISA",
18
"cardDetails": "1111"
19
}
20
}
21
}
22
}
```
Note
Handling the responses from the API calls should be according to our public [API contract & guidelines](/api)
# Integration Guide
> Learn about the request parameters and flows required to process alternative payment methods.
### General
[Section titled “General”](#general)
Alternative Payment Methods, from now on referred to as APMs. APM checkouts are very similar to normal checkouts. The biggest difference is that the customer most of the time needs to take an additional action in order to finalize the payment. Please make sure that before you read this you familiarize yourself with how [card payments](/online-payments/introduction/) are done.
First, you need to know which payment methods are available to your merchant profile. To check this [create a checkout](/api/checkouts/create) and use the checkout id to fetch the list of available payment methods from the following endpoint `https://api.sumup.com/v0.1/checkouts/{checkout_id}/payment-methods`.
The response will look like this
```json
1
{
2
"items": [
3
{
4
"id": "card",
5
"name": "Credit Card"
6
},
7
{
8
"id": "blik",
9
"name": "Blik"
10
},
11
{
12
"id": "apple_pay",
13
"name": "Apple Pay"
14
}
15
]
16
}
```
Note here that this is not a static list and might change from checkout to checkout as payment methods are not offered for all currencies and amounts, and we are continuously introducing new APMs you can include in your list of payment options.
Our suggestion would be to handle the returned payment methods as an allowlist for this checkout, and then from this list pick all the payment methods you want/can offer. Do **not** display all methods returned if you can not handle their respective flows.
The customer chooses one of the payment methods from the returned values, which should be sent as part of the process checkout request under `payment_type`.
The currently available payment method ids are: `card`, `ideal`, `bancontact`, `boleto`, `eps`, `mybank`, `satispay`, `blik`, `p24`, `pix`, `qr_code_pix`, `apple_pay`, `paypal`, `google_pay`. *name* is just for display purposes.
APMs differ from the behaviour of cards. There are two possible flows, which we call `artifacts` or `redirect instructions`, explained in more detail below. APMs also require different input parameters which you need to gather from the customer. The required parameters to gather and the payment method flows are listed below:
| Payment method name | Parameters | Flow |
| ------------------- | --------------------------------------------------- | -------- |
| bancontact | First name, Last name, Country | Redirect |
| blik | First name, Last name, Country, Email | Redirect |
| boleto | First name, Last name, Country, Email, Address, CPF | Artifact |
| eps | First name, Last name, Country, Email | Redirect |
| ideal | First name, Last name, Country, Email | Redirect |
| myBank | First name, Last name, Country, Email | Redirect |
| p24 | First name, Last name, Country, Email | Redirect |
| satispay | First name, Last name, Country, Email | Redirect |
| pix | | Artifact |
| qr\_code\_pix | | Artifact |
The payload needs to be filled out like this:
```json
1
{
2
"payment_type": "#Payment method name",
3
"personal_details": {
4
"email": "#Email",
5
"first_name:": "#First Name",
6
"last_name": "#Last Name",
7
"tax_id": "#CPF",
8
"address": {
9
"country": "#Country",
10
"city": "#Address",
11
"line1": "#Address",
12
"postal_code": "#Address",
13
"state": "#Address"
14
}
15
}
16
}
```
### Redirect Flow
[Section titled “Redirect Flow”](#redirect-flow)
In the redirect flow when the checkout is processed you will receive the state “PENDING” and the response will include a `next_step` parameter, this means an additional action for the processing is needed. The response will look something like this:
```json
1
{
2
...
3
"status": "pending",
4
"next_step": {
5
"url": "https://apm-redirect-link",
6
"method": "POST",
7
"payload": {
8
"....": "..."
9
}
10
},
11
...
12
}
```
Most of the time this is a simple redirect to a 3rd party page, like Blik, where the customer can pay. But in this example, you can also see that this might be a POST request. For all calls, you should make sure that the payload is included and the appropriate method is used. Once the customer completes the necessary actions on the page they will be redirected to the `redirect_url` specified under the [create checkout request](/api/checkouts/create). Now you can retrieve the final status via a GET [checkout call](/api/checkouts/get/) request.
### Payment Method Artifacts
[Section titled “Payment Method Artifacts”](#payment-method-artifacts)
Payment method artifacts are images, pdfs etc. which the customer gets in order to pay. Currently, we have 3 payment methods which have artifacts: `boleto`, `pix` and `qr_code_pix`. Examples of the type of information to expect can be found below:
**boleto:**
```json
1
{
2
"boleto": {
3
"barcode": "23790001246004987209031123456704579990000010000",
4
"url": "https://api.sumup.com/v0.1/checkouts/19c11c6c-be1d-4dd6-b718-2798878117cb/boletos/1044833949",
5
"valid_until": "2022-02-01T17:57:10.442+00:00",
6
"artefacts": [
7
{
8
"name": "invoice",
9
"content_type": "application/pdf",
10
"location": "https://homolog.meiosdepagamentobradesco.com.br/apiboleto/Bradesco?token=bWJvYXpkc1hXRzdhRVkyUUFGZUV4T25NYjBVVEZrNG93Y3RKLzM4cTh5dWdDWEh5dDQyTXN6ZHl5NFdjaHBkZg..",
11
"created_at": "2022-01-21T17:57:10.443+00:00"
12
},
13
{
14
"name": "code",
15
"content_type": "text/plain",
16
"location": "https://api.sumup.com/v0.1/artefacts/5266b29e-625b-43c0-a74a-8985ea3acd8a/content",
17
"content": "23790001246004987209031123456704579990000010000",
18
"created_at": "2022-01-21T17:57:10.445+00:00"
19
}
20
]
21
}
22
}
```
**pix:**
```json
1
{
2
"pix": {
3
"artefacts": [
4
{
5
"name": "barcode",
6
"content_type": "image/jpeg",
7
"location": "https://api.sumup.com/v0.1/artefacts/ee69508f-1b16-4ead-8416-8d2085933e6f/content",
8
"created_at": "2021-10-12T22:06:46.327+00:00"
9
},
10
{
11
"name": "code",
12
"content_type": "text/plain",
13
"location": "https://api.sumup.com/v0.1/artefacts/1e1e5130-17d1-495a-8e36-2a50d40dacde/content",
14
"content": "00020126580014br.gov.bcb.pix0136a4fac492-d03b-45a8-bd43-c3f23d4bac68520400005303986540520.005802BR5916Priscila Manhaes6009Sao Paulo62290525SUMUP202110122206453822986304A61E",
15
"created_at": "2021-10-12T22:06:46.326+00:00"
16
}
17
]
18
}
19
}
```
**qr\_code\_pix:**
```json
1
{
2
"qr_code_pix": {
3
"artefacts": [
4
{
5
"name": "barcode",
6
"content_type": "image/jpeg",
7
"location": "https://api.sam-app.ro/v0.1/artefacts/ee69508f-1b16-4ead-8416-8d2085933e6f/content",
8
"created_at": "2021-10-12T22:06:46.327+00:00"
9
},
10
{
11
"name": "code",
12
"content_type": "text/plain",
13
"location": "https://localhost:3000/v0.1/artefacts/1e1e5130-17d1-495a-8e36-2a50d40dacde/content",
14
"content": "00020126580014br.gov.bcb.pix0136a4fac492-d03b-45a8-bd43-c3f23d4bac68520400005303986540520.005802BR5916Priscila Manhaes6009Sao Paulo62290525SUMUP202110122206453822986304A61E",
15
"created_at": "2021-10-12T22:06:46.326+00:00"
16
}
17
]
18
}
19
}
```
Note that the major difference between `qr_code_pix` and `pix` itself is that `pix` will be paid directly into the merchant’s SumUp bank account if they have one. `qr_code_pix` will be paid out with the normal payout process and incurs a fee.
For all artifact payments, you need to provide the customer with the artifact and wait for the checkout to eventually complete.
Once the user has paid, you can retrieve the final status via a GET [checkout call](/api/checkouts/get/).
# Payment Widget
> Explore the SumUp Payment Widget and how to mount and configure it on your site.
## About Payment Widget
[Section titled “About Payment Widget”](#about-payment-widget)
SumUp provides the Payment Widget for easier processing of checkouts on your website, solving multiple issues for you as a merchant, including PCI and PSD2 compliance, while offering a number of customization options.
The Payment Widget lets you collect card and alternative payment method information from your customers. For the card method, the Payment Widget dynamically recognizes the card brand and shows the respective brand icon.
A secure HTTPS connection is used to submit the payment information. To ensure an uninterrupted experience, without browser warnings on content being served through non-secure web pages, we highly recommend you serve your page containing the payment data form via HTTPS as well.
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
Payment Widget is available to all SumUp merchants and getting started with it is really easy!
The only requirement to use Payment Widget is the ability to create online checkouts [using SumUp checkout API](/api/checkouts/create). SumUp API requires authorization with an API Key or Access Token - see the [Authorization Guide](/tools/authorization/authorization/) for details.
## Compliance
[Section titled “Compliance”](#compliance)
### Payment Card Industry
[Section titled “Payment Card Industry”](#payment-card-industry)
By using SumUp’s Payment Widget for your business, you comply with the Payment Card Industry (PCI) standards and you do not need to worry about storing or sending sensitive information such as card details to our servers.
### Payment Services Directive 2
[Section titled “Payment Services Directive 2”](#payment-services-directive-2)
Strong Customer Authentication (SCA) is part of a Payment Services Directive (PSD) 2 regulation in Europe which requires changes to how customers authenticate online payments. To ensure that SCA requirements are met, card transactions need to use two-factor authentication like 3D Secure where customers are typically directed to their bank’s website to approve the payment, or a code is sent to their phone, or they need to confirm the payment through the banking app on their phone.
SumUp’s card widget is PSD2 SCA compliant and supports 3D Secure 2, provided the individual customers’ banks support it. In cases where they don’t, the authentication falls back to 3D Secure 1. Regardless of the version of 3D Secure, these additional security layers reduce fraud while ensuring a seamless checkout experience for customers.
## Integration
[Section titled “Integration”](#integration)
1. In order to integrate the Payment Widget on your website, you simply need to include the `sdk.js` script on your payment page.
```js
1
```
2. Once the script is loaded, you have access to a global variable `SumUpCard`, that has a `mount` method which renders the available payment methods.
3. [Create a checkout](/api/checkouts/create) and copy the returned `id`.
4. Pass the returned `id` from the checkout response to the widget component.
```html
1
2
6
```
The Payment Widget makes a request to execute the checkout and after the request is completed, you get a response based on the callback function configured. As a result of successful integration, you can see the following component:
You can experience the payment widget's functionality by using the interactive demo below (no real charges will occur)
## Configurations
[Section titled “Configurations”](#configurations)
The Payment Widget allows you to customize certain properties on the card display. Listed below are the available configuration properties. If you wish to override the default settings, add your own configuration property-value pairs to the `SumUpCard.mount` method.
```js
1
SumUpCard.mount({
2
checkoutId: "...",
3
// 'config-name': 'config-value'
4
});
```
| Property Name | Description | Value | Default Value | Required |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | -------- |
| checkoutId | The unique ID you receive once you [create a checkout](/online-payments/guides/single-payment/#1-create-a-checkout). | `string` | *no default value* | yes |
| onResponse | The callback function that will be called when you receive a response from the payment form. The first parameter is one of the following:- `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. | `function` | `null` | no |
| onLoad | The callback function that will be called when the card widget is loaded. | `function` | `null` | no |
| onPaymentMethodsLoad | The callback is called when the payment methods are loaded for the given `checkoutId`. Usually used for when the host page needs to change depending on the payment methods available. Payment methods can be filtered in order to limit those shown by the widget. `return` the list of payment methods for the widget to render as an *Array of Strings*. E.g. to show only Boleto, when available: `() => ['boleto']`; | `function` | `null` | no |
| onChangeInstallments\* | The callback function that will be called when the user changes the dropdown for installments. The first and only parameter will be the number of selected installments. (`showInstallments` must be enabled). | `function` | `null` | no |
| showSubmitButton | Displays or hides the form’s submit button. | `boolean` | `true` | no |
| showFooter | Displays or hides “Powered by SumUp” label. | `boolean` | `true` | no |
| showInstallments\* | Displays or hides a dropdown for choosing installments. Once enabled this overrides any value of the configuration `installments` and will not display `amount` on the submit button. | `boolean` | `false` | no |
| showZipCode\*\* | Displays or hides ZIP code input field. It is mandatory for merchant users from USA. | `boolean` | `false` | no |
| showEmail | Displays or hides email input field. At some time in the future it’ll be a mandatory field for every integrator because of the [SCA](https://en.wikipedia.org/wiki/Strong_customer_authentication). | `boolean` | `false` | no |
| email | Alternative way (to `showEmail`) to pass user’s email if for example you know it from a previous step in your application. This configuration doesn’t display additional input fields. If for some reason both `showEmail` and `email` are passed the `email` will have no effect over the displayed input field. | `string` | `null` | no |
| installments\* | The number of installments with which the transaction should be processed. | `number` \[1 .. 12] | `null` | no |
| maxInstallments\* | The maximum amount of installments in the selector displayed by the widget. | `number` \[1 .. 12] | `12` | no |
| id | `id` of the element that you wish to render the card widget in. *Example:* `` | `string` | `"sumup-card"` | no |
| donateSubmitButton | Changes the text of the submit button to “Donate”. | `boolean` | `false` | no |
| amount | The `amount` you want to be displayed on the submit button. *Requires* `currency` *and* `locale` *to take effect.* | `string` | `null` | no |
| currency | The `currency` for the `amount` you want to be displayed on the submit button. | One of: `"EUR"`, `"BGN"`, `"BRL"`, `"CHF"`, `"CZK"`, `"DKK"`, `"GBP"`, `"HUF"`, `"NOK"`, `"PLN"`, `"SEK"`, `"USD"` | `null` | no |
| locale | Translates all texts into the given locale. Also specifies the formatting of the `amount` and `currency`. | One of: `"bg-BG"`, `"cs-CZ"`, `"da-DK"`, `"de-AT"`, `"de-CH"`, `"de-DE"`, `"de-LU"`, `"el-CY"`, `"el-GR"`, `"en-GB"`, `"en-IE"`, `"en-MT"`, `"en-US"`, `"es-CL"`, `"es-ES"`, `"et-EE"`, `"fi-FI"`, `"fr-BE"`, `"fr-CH"`, `"fr-FR"`, `"fr-LU"`, `"hu-HU"`, `"it-CH"`, `"it-IT"`, `"lt-LT"`, `"lv-LV"`, `"nb-NO"`, `"nl-BE"`, `"nl-NL"`, `"pt-BR"`, `"pt-PT"`, `"pl-PL"`, `"sk-SK"`, `"sl-SI"`, `"sv-SE"` | `"en-GB"` | no |
| country | Sets the country where the user account is from. | One of: `"AT"`, `"BE"`, `"BG"`, `"BR"`, `"CH"`, `"CL"`, `"CO"`, `"CY"`, `"CZ"`, `"DE"`, `"DK"`, `"EE"`, `"ES"`, `"FI"`, `"FR"`, `"GB"`, `"GR"`, `"HR"`, `"HU"`, `"IE"`, `"IT"`, `"LT"`, `"LU"`, `"LV"`, `"MT"`, `"NL"`, `"NO"`, `"PL"`, `"PT"`, `"RO"`, `"SE"`, `"SI"`, `"SK"`, `"US"` | `null` | no |
| googlePay | Required for accepting payments with the widget via Google Pay: - **`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.For more details check [Google Pay **`merchantInfo`** documentation](https://developers.google.com/pay/api/web/reference/request-objects#MerchantInfo). | `{merchantId: string, merchantName: string}` | `null` | no |
*\* Installments are available only to merchant users in Brazil.*\
*\*\* ZIP code is required only for merchant users in the USA.*
## Methods
[Section titled “Methods”](#methods)
| Name | Description | Parameters | Return Type |
| ------- | ----------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mount` | Initializes and renders the payment form. | JSON object with a [configuration](#configurations). | Returns object that contains three methods: `submit`, `unmount` and `update`.- `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`. |
## Alternative Payment Methods
[Section titled “Alternative Payment Methods”](#alternative-payment-methods)
Depending on the country a merchant is registered in, [Alternative Payment Methods (APMs)](/online-payments/apm) are available for accepting payments from your customers. Please note, the `show*` configuration properties from the [widget configurations](#configurations) do not apply to APMs. The APMs will only render fields applicable to the respective payment method.
You can begin offering APMs to your customers, once you are onboarded as a merchant. Request assistance with getting onboarded for APMs through our [contact form](/contact).
Note
Instalments are not applicable to Alternative Payment Methods.
## Custom Styling
[Section titled “Custom Styling”](#custom-styling)
Custom styling to most of the SumUp Payment Card Widgets’ elements is enabled by querying the `data-sumup-id` attribute. To get all elements with the `data-sumup-id` attribute, query the DOM with `document.querySelectorAll('[data-sumup-id]')`.
Here’s an example of updating styles for one of the queryable elements:
```css
1
[data-sumup-id="widget__container"] {
2
color: red;
3
line-height: 18px;
4
}
```
You can also style child elements to those with the `data-sumup-id`, by chaining their tag or other uniquely identifiable attribute.
Elements like Payment Selector have some additional items you can query to extend your customisations. To style a specific Payment Selector, you need to appoint the `data-sumup-item=${payment.id}`.
```css
1
[data-sumup-id="payment_option"][data-sumup-item="blik"] {
2
display: none;
3
}
```
## Using your own submit button
[Section titled “Using your own submit button”](#using-your-own-submit-button)
If you need to use your own submit button you can achieve this by following the example below:
```html
1
2
```
## Handling strict Content Security Policies
[Section titled “Handling strict Content Security Policies”](#handling-strict-content-security-policies)
Pages with strict [Content Security Policies](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) (CSP), may experience issues with styles or images when rendering the SumUp Payment Widget. This section contains the necessary adjustments to render the Payment Widget properly.
To confirm your issue is related to CSP, check your browser’s console for an error message of this nature:
```text
1
Refused to apply inline style because it violates the following Content Security Policy directive: "style-src 'self' \*\*\* Either the 'unsafe-inline' keyword, a hash ('sha256-47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU='), or a nonce ('nonce-...') is required to enable inline execution.
```
### Required Configurations
[Section titled “Required Configurations”](#required-configurations)
In order to properly render the card widget with CSP in place, you must whitelist the following URLs for your application:
| Content Type | URL |
| ------------ | ------------------------------------- |
| SDK & API | ’https\://\*.sumup.com’ |
| Images | ’data:’, ‘’ |
Additionally to the above, `nonce` is required to make inline styles work on your host page. For more information view [the CSP docs](https://content-security-policy.com/nonce/).
Here’s an example implementation with nonce:
```js
1
const express = require("express");
2
const app = express();
3
const http = require("http");
4
const server = http.createServer(app);
5
6
const port = process.env.PORT || 4000;
7
8
const crypto = require("crypto");
9
10
// Resources
11
const apisToConnect = ["https://gateway.sumup.com", "https://api.sumup.com"];
12
13
const imagesResources = [
14
"data:", // inline icons
15
"https://static.sumup.com",
16
// For generated barcodes
17
18
"https://api.sumup.com",
19
];
20
21
const scriptsResources = [
22
"https://gateway.sumup.com",
23
// PLUS nonce-$HASH
24
];
25
26
const stylesResources = [
27
// nonce-$HASH
28
];
29
30
const framesResources = ["https://gateway.sumup.com"];
31
32
app.get("/", (req, res) => {
33
const nonce = crypto.randomBytes(16).toString("base64");
34
res.setHeader(
35
"Content-Security-Policy",
36
`default-src 'self';` +
37
` connect-src 'self' ${apisToConnect.join(" ")};` +
38
` img-src 'self' ${imagesResources.join(" ")};` +
39
` script-src 'self' ${scriptsResources.join(" ")} 'nonce-${nonce}';` +
40
` style-src 'self' 'nonce-${nonce}';` +
41
` frame-src 'self' ${framesResources.join(" ")};`,
42
);
43
44
//
45
res.send(`
46
61
`);
62
});
63
64
server.listen(port, () => {
65
console.log("listening on:", port);
66
});
```
If you continue to experience issues with rendering the Payment Widget, reach out to our support through this [contact form](/contact).
# Hosted Checkout
> Learn about Hosted Checkout and how configure the fully hosted payment experience.
## About Hosted Checkout
[Section titled “About Hosted Checkout”](#about-hosted-checkout)
Hosted Checkout is an integration product that offers a complete checkout flow for payment collection. It’s called “Hosted Checkout”, because SumUp renders and hosts the entire checkout UI, which your customers can access via URL returned by our checkout API. The hosted checkout page aims at being easy to integrate and requires little to no code, offering a summary of the checkout details and provides a complete flow for handling payment collection, covering the possible outcomes of payment attempts all the way to the success page. All SumUp payment methods are available in Hosted Checkout, according to availability per merchant.
A screenshot of the Hosted Checkout form showing available payment options, including Google Pay, Apple Pay, and card payment
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
Hosted Checkouts is available to all SumUp merchants and getting started with it is really easy!
The only requirement to access Hosted Checkout is the ability to create online checkouts [using SumUp checkout API](/api/checkouts/create), which returns the hosted checkout URL. SumUp API requires authorization with an API Key or Access Token - see the [Authorization Guide](/tools/authorization/authorization/) for details.
## Accessing Hosted Checkout
[Section titled “Accessing Hosted Checkout”](#accessing-hosted-checkout)
Once you’re able to create checkouts via API calls, you can opt-in for Hosted Checkout by providing an extra parameter to your POST request payload. The parameter name should be `hosted_checkout` and the value should be an object with the following structure: `{ "enabled": true }`.
The response should then include the Hosted Checkout properties:
* `hosted_checkout` is returned as provided in the request
* `hosted_checkout_url` provides the URL of the page handling the payment flow
1. Send a request with the `"hosted_checkout": { "enabled": true }` in the body.
```bash
1
curl -X POST https://api.sumup.com/v0.1/checkouts \
2
-H "Content-Type: application/json" \
3
-H "Authorization: Bearer $SUMUP_API_KEY" \
4
-d '{
5
"amount": 12.00,
6
"checkout_reference": "b50pr914-6k0e-3091-a592-890010285b3d",
7
"currency": "EUR",
8
"description": "A sample checkout",
9
"merchant_code": "MCXXXXXX",
10
"hosted_checkout": { "enabled": true }
11
}'
```
The response body contains the `hosted_checkout` and `hosted_checkout_url` parameters:
```json
1
{
2
"amount": 12,
3
"checkout_reference": "b50pr914-6k0e-3091-a592-890010285b3d",
4
"checkout_type": "checkout",
5
"currency": "EUR",
6
"date":"2000-01-01T12:49:24.899+00:00",
7
"description": "A sample checkout",
8
"id": "64553e20-3f0e-49e4-8af3-fd0eca86ce91",
9
"merchant_code": "MCXXXXXX",
10
"merchant_country": "DE",
11
"merchant_name": "Sample Shop",
12
"purpose": "CHECKOUT",
13
"status": "PENDING",
14
"transactions": [],
15
"hosted_checkout": { "enabled": true },
16
"hosted_checkout_url": "https://checkout.sumup.com/pay/8f9316a3-cda9-42a9-9771-54d534315676"
17
}
```
2. Use the payment page provided under `hosted_checkout_url` to complete the flow you’re building. See [Configuring Hosted Checkout](#configuring-hosted-checkout) for more information.
Note
Each Hosted Checkout session lasts for 30 minutes, after which end users are presented with a “not found” page upon access attempts.
## Configuring Hosted Checkout
[Section titled “Configuring Hosted Checkout”](#configuring-hosted-checkout)
### Redirecting users after successful payment
[Section titled “Redirecting users after successful payment”](#redirecting-users-after-successful-payment)
Hosted Checkout is meant to suit a broad range of use cases, from a simple self-contained payment solution, to a checkout step integrated within a longer flow. When creating a checkout, simply provide a `redirect_url` parameter to include a redirect link in the success page, under a “Redirect to merchant website” button.
Note
Differently from what’s stated in our [API docs](/api/checkouts/create), the absence of this parameter does not affect the availability of payment methods in Hosted Checkouts.
## Hosted Checkout status pages
[Section titled “Hosted Checkout status pages”](#hosted-checkout-status-pages)
With Hosted Checkout, your payment flow is covered from start to finish. All successful payments are presented with a success page, informing users of the completed payment. Hosted Checkout also accommodates other payment outcomes:
* Successful payments. This page will include the “Back to merchant website” button only if the `redirect_url` was provided at checkout creation.
![A screenshot of the Hosted Checkout payment successful confirmation form]()
A screenshot of the Hosted Checkout payment successful confirmation form
* Failed payments will include express checkout payment methods for a quick retry.
![A screenshot of the Hosted Checkout payment failed form]()
A screenshot of the Hosted Checkout payment failed form
* Expired session page will be shown for all unpaid checkouts after session expiration or checkout expiration (currently 30 minutes).
![A screenshot of the Hosted Checkout session expiry form]()
A screenshot of the Hosted Checkout session expiry form
* Not found page, for all URLs that do not match any existing session in our system
![A screenshot of the Hosted Checkout page not found form]()
A screenshot of the Hosted Checkout page not found form
Caution
Hosted Checkout is currently in beta and may be subject to change. We’re currently working on new features, so keep an eye on this page as we’ll continue to add features in the upcoming months!
Feel free to reach out with feature requests via our [contact form](/contact).
# Custom Integrations
> Introduces the custom integration guides and prerequisites for building with the SumUp SDKs and APIs.
Guides in this section will walk you through basic usage of SumUp APIs, which allow you to develop a custom integration in case SumUp integrations don’t fully support your use case.
## Getting a test account
[Section titled “Getting a test account”](#getting-a-test-account)
To start testing SumUp APIs and tools without involving real money, you need to have a test account. You can create a test account from your account in the Dashboard as shown below.
1. Log in to your SumUp account.
2. Open the drop-down menu between Support and your user panel.
3. Select Test Account. Your merchant account is now switched to test mode.
A screenshot of the account selection dropdown in the SumUp dashboard with the test account highlighted with red circle
Once you have your test account you can begin making API calls with real data. Our test accounts **do not** process transactions with real funds. Test account has a different ID, and shows a clear warning. When you try to process a request with the value of 11 (in any currency), the test account will always fail - this is by design, to enable testing failed transactions.
A screenshot of the dashboard with test account selected
When you’re done experimenting with the test account, switch back to a regular account for business purposes.
SumUp provides SDKs for [PHP](https://github.com/sumup/sumup-ecom-php-sdk) and [Go](https://github.com/sumup/sumup-go).
# Recurrent Payments
> Describes how to set up recurring payments with customer tokens, mandates, and 3DS-compliant flows.
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
* You have completed the [card tokenization](/online-payments/guides/tokenization-with-payment-sdk) for a customer
* You have an API Key. For more details see the [Authorization Guide](/tools/authorization/authorization/#api-keys).
* You have control over the backend server to retrieve data securely.
## Overview
[Section titled “Overview”](#overview)
To ease the subsequent payments event, an initial checkout is authenticated according to 3DS checks. All following checkouts refer to the initial one in terms of 3DS authentication.
You will go through the following steps:
1. [Set up a checkout session](#setting-up-checkout-session)
2. [Process checkout](#processing-checkout)
3. [Retrieve the checkout](#retrieving-checkout)
4. [Process future subsequent payments with a token](#processing-subsequent-payments)
## Setting up Checkout Session
[Section titled “Setting up Checkout Session”](#setting-up-checkout-session)
The flow is initiated with the `create a checkout` endpoint. It is important to pass the `customer_id` parameter in this step, for future linking to a payment instrument, ideal for quickly creating and processing later payments. Additionally, a `purpose` parameter is passed to indicate the payment type as **recurrent** and process an authorization charge of the checkout amount indicated, **which is instantly reimbursed**.
```json
1
{
2
...
3
"purpose": "SETUP_RECURRING_PAYMENT"
4
...
5
}
```
The initial checkout may be subject to the 3DS challenge, depending on multiple factors described briefly [here](/online-payments/features/3ds/).
Sample request available in our [API Reference](/api/checkouts/create).
```json
1
{
2
"checkout_reference": "CO746453",
3
"amount": 5,
4
"currency": "EUR",
5
"merchant_code": "ME7RMQN3",
6
"description": "Sample request",
7
"return_url": "http://example.com",
8
"customer_id": "DC000101",
9
"purpose": "SETUP_RECURRING_PAYMENT"
10
}
```
### Processing Checkout
[Section titled “Processing Checkout”](#processing-checkout)
A `mandate` object must be passed at checkout processing stage. This object indicates that a customer has given consent to store their payment details for recurrent payments. You need to handle consent, 3DS flow and PCI/DSS compliance yourself in case of recurring payments, and by passing the `mandate` object, you assert that you have done so.
Depending on the local region regulations, this request may result in a 3DS redirection step, which you will need to handle accordingly. If you want to test 3DS flow, you can request SumUp to enable 3DS on your test account.
```json
1
{
2
"payment_type": "card",
3
"installments": 1,
4
"card": {
5
"name": "FIRSTNAME LASTNAME",
6
"number": "4111111111111111",
7
"expiry_year": "2023",
8
"expiry_month": "01",
9
"cvv": "123",
10
"zip_code": "12345"
11
},
12
"mandate": {
13
"type": "recurrent",
14
"user_agent": "Chrome: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3865.90 Safari/537.36.",
15
"user_ip": "2001:0db8:85a3:0000:0a00:8a2e:0370:7300"
16
}
17
}
```
### Retrieving Checkout
[Section titled “Retrieving Checkout”](#retrieving-checkout)
If you have successfully processed the checkout, a token representing a payment instrument is created. You can [retrieve the checkout](/api/checkouts/get) to find the token within a `payment_instrument` object.
```json
1
{
2
"id": "cd36780e-f43d-4f22-1i9e-e32a1a1bafc8",
3
"checkout_reference": "0BYNWLYC7KV",
4
"amount": 3.51,
5
"currency": "EUR",
6
...
7
"payment_instrument": {
8
"token": "2fa27578-e765-5dbh-aa97-d45d3d6cdfbb"
9
}
10
}
```
### Processing Subsequent Payments
[Section titled “Processing Subsequent Payments”](#processing-subsequent-payments)
After following the above requests you can now process recurring payments by referencing the saved token and the associated customer. Both `token` and `customer_id` fields are required.
```json
1
{
2
"payment_type": "card",
3
"installments": 1,
4
"token": "{{CARD_TOKEN}}"
5
"customer_id": "DC000101",
6
}
```
# Refunds
> Walks through looking up transactions and issuing full or partial refunds.
In this guide, you will learn how to refund a transaction for a payment you have already processed. You will go through the following steps:
1. [Look up a transaction ID (Optional)](#1-look-up-a-transaction-id)
2. [Refund a transaction](#2-refund-a-transaction) by using one of the available options:
* [Option A: Make a full refund](#option-a-make-a-full-refund)
* [Option B: Make a partial refund](#option-b-make-a-partial-refund)
When you complete these steps, the payment you have previously processed through SumUp will be refunded either partially or in full.
## Before you begin
[Section titled “Before you begin”](#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 **test account** reach out to our support team through this [contact form](/contact).
* You have [registered your client application](/tools/authorization/register-app/) with SumUp.
* You have a valid access token obtained via the [Authorization code flow](/tools/authorization/authorization/#authorization-code-flow).
* You have processed successfully a payment checkout and you need to refund the transaction.
Note
Transactions are associated with active merchant user accounts. As a result, you *cannot* use an access token obtained via the [Client credentials flow](/tools/authorization/authorization/#client-credentials-flow) to complete the steps in this guide.
## Steps
[Section titled “Steps”](#steps)
### 1. Look up a transaction ID
[Section titled “1. Look up a transaction ID”](#1-look-up-a-transaction-id)
Note
If you already have the ID of the transaction you want to refund, you can skip this step and continue with [Step 2](#2-refund-a-transaction).
To look up the identifier of a transaction for a payment checkout you have already completed, make a GET request to the `https://api.sumup.com/v0.1/checkouts/{id}` endpoint, where the value of the `{id}` path parameter is the identifier of the checkout resource.
Following is a sample request for retrieving a checkout:
```bash
1
curl -X GET \
2
https://api.sumup.com/v0.1/checkouts/4ebc2ed7-bb8c-4d4d-a110-08fd31301bf2 \
3
-H "Authorization: Bearer $SUMUP_API_KEY"
```
```go
1
ctx := context.Background()
2
client := sumup.NewClient().WithAuth(os.Getenv("SUMUP_API_KEY"))
3
4
checkout, err := client.Checkouts.Get(ctx, "4ebc2ed7-bb8c-4d4d-a110-08fd31301bf2")
```
```php
1
$checkoutsService = $sumup->getCheckoutService();
2
$response = $checkoutsService->findById('4ebc2ed7-bb8c-4d4d-a110-08fd31301bf2');
3
$checkoutReference = $response->getBody()->checkout_reference;
4
$checkoutId = $response->getBody()->id;
```
* cURL
```bash
1
curl -X GET \
2
https://api.sumup.com/v0.1/checkouts/4ebc2ed7-bb8c-4d4d-a110-08fd31301bf2 \
3
-H "Authorization: Bearer $SUMUP_API_KEY"
```
* Go
```go
1
ctx := context.Background()
2
client := sumup.NewClient().WithAuth(os.Getenv("SUMUP_API_KEY"))
3
4
checkout, err := client.Checkouts.Get(ctx, "4ebc2ed7-bb8c-4d4d-a110-08fd31301bf2")
```
* PHP
```php
1
$checkoutsService = $sumup->getCheckoutService();
2
$response = $checkoutsService->findById('4ebc2ed7-bb8c-4d4d-a110-08fd31301bf2');
3
$checkoutReference = $response->getBody()->checkout_reference;
4
$checkoutId = $response->getBody()->id;
```
The response contains a JSON body with the full details of the processed checkout resource. You can find the transaction ID in the `id` attribute of the respective transaction resource (`664200af-2b62-4142-9c73-a2a505310d78` in the sample response below).
```json
1
{
2
"checkout_reference": "CO287866",
3
...
4
"id": "4ebc2ed7-bb8c-4d4d-a110-08fd31301bf2",
5
...
6
"transactions": [
7
{
8
"id": "664200af-2b62-4142-9c73-a2a505310d78",
9
...
10
}
11
]
12
}
```
### 2. Refund a transaction
[Section titled “2. Refund a transaction”](#2-refund-a-transaction)
You can use one the two available options for refunding a processed transaction:
* [Option A: Make a full refund](#option-a-make-a-full-refund)
* [Option B: Make a partial refund](#option-b-make-a-partial-refund)
#### Option A: Make a full refund
[Section titled “Option A: Make a full refund”](#option-a-make-a-full-refund)
To make a full refund for a processed transaction, make a POST request with an empty request body to the `https://api.sumup.com/v0.1/me/refund/{txn_id}` endpoint, where the value of the `{txn_id}` path parameter is the identifier of the transaction resource.
Following is a sample request for making a full refund for the transaction with identifier `664200af-2b62-4142-9c73-a2a505310d78`:
* cURL
```bash
1
curl -X POST \
2
https://api.sumup.com/v0.1/me/refund/19aa3cca-89f6-42d2-b462-463b0b53e959 \
3
-H "Authorization: Bearer $SUMUP_API_KEY"
```
* Go
```go
1
ctx := context.Background()
2
client := sumup.NewClient().WithAuth(os.Getenv("SUMUP_API_KEY"))
3
4
_, err := client.Transactions.Refund(ctx, "19aa3cca-89f6-42d2-b462-463b0b53e959", sumup.RefundTransactionBody{})
```
* PHP
```php
1
$transactionsService = $sumup->getTransactionService();
2
$response = $transactionsService->refund('19aa3cca-89f6-42d2-b462-463b0b53e959');
```
The response returns a 204 HTTP status code and contains no body.
#### Option B: Make a partial refund
[Section titled “Option B: Make a partial refund”](#option-b-make-a-partial-refund)
To make a partial refund for a processed transaction, make a POST request to the `https://api.sumup.com/v0.1/me/refund/{txn_id}` endpoint, where the value of the `{txn_id}` path parameter is the identifier of the transaction resource.
Unlike the option for a full refund, the request body for partial refunds should be a JSON object with the amount you want to refund for the transaction.
Following is a sample request for making a partial refund for the amount of 24.42 EUR:
* cURL
```bash
1
curl -X POST \
2
https://api.sumup.com/v0.1/me/refund/19aa3cca-89f6-42d2-b462-463b0b53e959 \
3
-H "Authorization: Bearer $SUMUP_API_KEY" \
4
-H 'Content-Type: application/json' \
5
-d '{"amount": 24.42}'
```
* Go
```go
1
ctx := context.Background()
2
client := sumup.NewClient().WithAuth(os.Getenv("SUMUP_API_KEY"))
3
4
amount := 12.24
5
client.Transactions.Refund(ctx, "sa", sumup.RefundTransactionBody{
6
Amount: &amount,
7
})
```
* PHP
```php
1
$transactionsService = $sumup->getCheckoutService();
2
$response = $transactionsService->refund('19aa3cca-89f6-42d2-b462-463b0b53e959', 24.42);
```
The response returns a 204 HTTP status code and contains no body.
## Result
[Section titled “Result”](#result)
You have successfully refunded a transaction (either partially or in full) for a payment you previously processed. The refunded amount will be credited to the same payment method the customer had used to pay with in the original transaction. The processing fees associated with the original transaction are not returned.
# Response Handling
> Explains how to interpret SumUp API responses.
Once an API call is submitted to SumUp, you will receive a response informing you if your request has been successful or not. In most cases the HTTP codes are accompanied by a response body in [JSON](https://json.org/) format.
Returned codes in the `2xx` range indicate success. Returned codes in the `4xx` range indicate errors where the information provided results in a failure. Returned codes in the `5xx` range are rare and indicate server-side errors.
## Successful requests
[Section titled “Successful requests”](#successful-requests)
Successfully processed requests return one of the following HTTP status codes: `200 OK`, `201 Created`, `202 Accepted`, `204 No Content`. Depending on the use case response bodies may not be present at all. A response body can look like this:
```json
1
{
2
"next_step": {
3
"url": "https://dummy-3ds-gateway.com/cap?RID=1233&VAA=A",
4
"method": "POST",
5
"redirect_url": "https://mysite.com/completed_purchase",
6
"mechanism": "iframe",
7
"payload": {
8
"PaReq": "eJxVUttu2zAM/RXDr4MjyY5dO6BVuE27FZuDZHGG9VGRmMSFb/..f16+jLt/gPhUvGGw==",
9
"MD": "b1a536c0-29b9-11eb-adc1-0242ac120002"
10
}
11
}
12
}
```
## Client-side issues
[Section titled “Client-side issues”](#client-side-issues)
`4xx` are occasions where you can take action to correct your application requests. Typically, these codes are returned upon user error, such as invalid API calls, incorrect values, missing parameters, etc. The response you receive will provide an indication to the root cause that triggered it. Here’s an example of a `4xx` response:
```json
1
{
2
"message": "Validation error",
3
"error_code": "MISSING",
4
"param": "merchant_code"
5
}
```
## Server-side issues
[Section titled “Server-side issues”](#server-side-issues)
`5xx` stand for server errors. Although rare, if you receive such code, we recommend retrying your request. Should the returned codes continue to be in the `5xx` range, [reach out to us](/contact).
# Accept a Payment
> Teaches how to create and complete a checkout for a one-off card payments.
In this guide, you will learn how to make a single payment with a payment card entered by a customer without associating it with a specific customer saved for the merchant user’s account. This type of payment is most useful for quick processing of payment checkouts in which you don’t store and manage any account data for your customers.
You will go through the following steps:
1. [Create a checkout](#1-create-a-checkout)
2. [Complete a checkout](#2-complete-a-checkout)
When you complete these steps, you will have processed a payment with a payment card entered by a customer.
## Before you begin
[Section titled “Before you begin”](#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 **test account** reach out to our support team through this [contact form](/contact).
* You have [registered your client application](/tools/authorization/register-app/) with SumUp.
* You have a valid access token obtained via one of the supported OAuth2 authorization flow, the [Authorization code flow](/tools/authorization/authorization/#authorization-code-flow) or [Client credentials flow](/tools/authorization/authorization/#client-credentials-flow).
Note
You can create and complete a payment checkout for any valid SumUp merchant user’s account. As a result, you *can* use an access token obtained either via the [Client credentials flow](/tools/authorization/authorization/#client-credentials-flow) or via the [Authorization code flow](/tools/authorization/authorization/#authorization-code-flow).
## Steps
[Section titled “Steps”](#steps)
### 1. Create a checkout
[Section titled “1. Create a checkout”](#1-create-a-checkout)
To create a new checkout resource, make a POST request to the `https://api.sumup.com/v0.1/checkouts` endpoint.
Caution
This request must be made in a server-to-server communication between your server and SumUp API.
The request body should be a JSON object with the following minimum details:
Note
The table below lists only the required parameters for the request. For a full list of the available parameters, see the [API Reference](/api/checkouts/create).
| Attribute name | Description |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| checkout\_reference | A unique string identifying the payment in your system. It must be unique for your application. |
| amount | The amount for which the payment is made. |
| currency | The three-letter [ISO4217](https://en.wikipedia.org/wiki/ISO_4217) code of the currency in which the payment is made. The value must match the currency registered for the specified merchant (see `merchant_code`). |
| merchant\_code | The code of the registered SumUp merchant the payment is made. |
Following is a sample request for creating a new checkout resource:
* cURL
```bash
1
curl -X POST \
2
https://api.sumup.com/v0.1/checkouts \
3
-H "Authorization: Bearer $SUMUP_API_KEY" \
4
-H 'Content-Type: application/json' \
5
-d '{
6
"checkout_reference": "CO746453",
7
"amount": 10,
8
"currency": "EUR",
9
"merchant_code": "ME7RMQN3",
10
"description": "Sample one-time payment"
11
}'
```
* Go
```go
1
ctx := context.Background()
2
client := sumup.NewClient().WithAuth(os.Getenv("SUMUP_API_KEY"))
3
4
checkout, err := client.Checkouts.Create(ctx, sumup.CreateCheckoutBody{
5
Amount: 19,
6
CheckoutReference: "CO746453",
7
Currency: "EUR",
8
MerchantCode: "MK0001",
9
})
```
* PHP
```php
1
$checkoutsService = $sumup->getCheckoutService();
2
$response = $checkoutsService->create(10, 'EUR', 'CO746453', 'docuser@sumup.com', 'Sample one-time payment');
3
$checkoutId = $response->getBody()->id;
```
The response contains a JSON body with the details of the created checkout resource. What you need to note in the response is the identifier of the resource - you will need it for all operations that you perform with the resource, such as completing it in the next step.
The resource identifier is returned in the `id` attribute, or `f14425c6-8bc1-4d02-957c-47573f762828` in the sample response below. The `status` attribute shows that the payment for this resource is pending and will be processed when you complete the checkout with the payment instrument details.
```json
1
{
2
"checkout_reference": "CO746453",
3
"amount": 10,
4
"currency": "EUR",
5
"merchant_code": "ME7RMQN3",
6
"description": "Sample one-time payment",
7
"id": "f14425c6-8bc1-4d02-957c-47573f762828",
8
"status": "PENDING",
9
"date": "2018-09-28T13:47:01.832Z",
10
"transactions": []
11
}
```
### 2. Complete a checkout
[Section titled “2. Complete a checkout”](#2-complete-a-checkout)
To complete the checkout and trigger the payment, make a PUT request to the `https://api.sumup.com/v0.1/checkouts/{id}` endpoint, where the value of the `{id}` path parameter is the identifier of the checkout resource.
Caution
This request must be made from your client, *not* from your server.
The request body should be a JSON object with the payment type (`card`) and the payment card details. For more information about the request, see the [API Reference](/api/checkouts/process).
Following is a sample request for completing the checkout from [Step 1](#1-create-a-checkout):
* cURL
```bash
1
curl -X PUT \
2
https://api.sumup.com/v0.1/checkouts/f14425c6-8bc1-4d02-957c-47573f762828 \
3
-H "Authorization: Bearer $SUMUP_API_KEY" \
4
-H 'Content-Type: application/json' \
5
-d '{
6
"payment_type": "card",
7
"card": {
8
"name": "Boaty McBoatface",
9
"number": "4200000000000042",
10
"expiry_month": "12",
11
"expiry_year": "23",
12
"cvv": "123"
13
}
14
}
```
* Go
```go
1
ctx := context.Background()
2
client := sumup.NewClient().WithAuth(os.Getenv("SUMUP_API_KEY"))
3
4
checkoutSuccess, err := client.Checkouts.Process(ctx, "f14425c6-8bc1-4d02-957c-47573f762828", sumup.ProcessCheckoutBody{
5
Card: &sumup.Card{
6
Cvv: "123",
7
ExpiryMonth: "12",
8
ExpiryYear: "23",
9
Name: "Boaty McBoatface",
10
Number: "4200000000000042",
11
},
12
PaymentType: sumup.ProcessCheckoutBodyPaymentTypeCard,
13
})
```
The response contains a JSON body with the details of the processed checkout resource in which the attributes related to the payment outcome are populated:
```json
1
{
2
"checkout_reference": "CO746453",
3
"amount": 10.0,
4
"currency": "EUR",
5
"merchant_code": "ME7RMQN3",
6
"description": "Sample one-time payment",
7
"id": "f14425c6-8bc1-4d02-957c-47573f762828",
8
"status": "PAID",
9
"date": "2018-09-28T13:47:01.832Z",
10
"transaction_code": "TFDCP3FLQ7",
11
"transaction_id": "19aa3cca-89f6-42d2-b462-463b0b53e959",
12
"transactions": [
13
{
14
"id": "19aa3cca-89f6-42d2-b462-463b0b53e959",
15
"transaction_code": "TFDCP3FLQ7",
16
"merchant_code": "ME7RMQN3",
17
"amount": 10.0,
18
"vat_amount": 0.0,
19
"tip_amount": 0.0,
20
"currency": "EUR",
21
"timestamp": "2018-09-28T13:48:28.768Z",
22
"status": "SUCCESSFUL",
23
"payment_type": "ECOM",
24
"entry_mode": "CUSTOMER_ENTRY",
25
"installments_count": 1,
26
"auth_code": "585388",
27
"internal_id": 24118507
28
}
29
]
30
}
```
## Result
[Section titled “Result”](#result)
You have made a payment with a payment card entered by a customer without associating it with a specific customer saved for a merchant user’s account. If the payment is successful, the funds will be transferred to the merchant user according to the configured account settings.
# Save Customer Cards
> Shows how to tokenize cards with the Payment Widget so you can save payment instruments for future charges.
## Overview
[Section titled “Overview”](#overview)
In this guide, you will learn how to use the payment widget to store card details for future use, for example to set up recurring payments. This feature is also known as **card on file** or **tokenization**.
You will go through the following steps:
1. [Create a customer](#creating-customer)
2. [Create checkout intended for card tokenization](#creating-checkout-to-save-card), where we specify it’s for tokenization purpose. This is where 3DS verification takes place. The transaction amount is instantly reimbursed.
3. [Process payment with the payment widget](#processing-request-with-payment-widget)
4. [Make subsequent payments with a payment instrument](#setting-up-recurring-payments)
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
* 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 **test account** reach out to our support team through this [contact form](/contact).
* You have an API Key. For more details see the [Authorization Guide](/tools/authorization/authorization/#api-keys).
* You have control over the backend server to retrieve data securely.
## Creating Customer
[Section titled “Creating Customer”](#creating-customer)
A customer resource is a representation of a person or business that is paying for a product or service. It contains personal information such as their name, contact details, postal address, as well as a unique identifier that is relevant to your business logic (`customer_id`).
To create a new customer resource, make a POST request to the `https://api.sumup.com/v0.1/customers` endpoint:
```bash
1
curl -X POST \
2
https://api.sumup.com/v0.1/customers \
3
-H "Authorization: Bearer $SUMUP_API_KEY" \
4
-H 'Content-Type: application/json' \
5
-d '{
6
"customer_id": "MYCUSTOMERID-123",
7
"personal_details": {
8
"address": {
9
"city": "Venice",
10
"state": "California",
11
"country": "US",
12
"line1": "606 Venezia Ave",
13
"line2": "Front",
14
"postal_code": "90291"
15
},
16
"birthdate": "1949-11-11",
17
"email": "thedude@example.com",
18
"first_name": "Jeffrey",
19
"last_name": "Lebowski",
20
"phone": "+1 310-555-1234"
21
}
22
}'
```
You should expect a standard `201 Created` response, with the customer details you passed. For more details see the [create a customer](/api/customers/create) endpoint. Having created the customer, we can now proceed to making a payment
## Creating Checkout to Save Card
[Section titled “Creating Checkout to Save Card”](#creating-checkout-to-save-card)
The checkout resource is a representation of a payment being made by the previously created customer. It contains information such as the amount, currency, and a unique `checkout_reference` identifier that is relevant to your business logic.
The flow is initiated with the `create a checkout` endpoint. It is important to pass the `customer_id` parameter in this step, for future linking to a payment instrument. Critically, a `purpose` parameter is passed to indicate the payment type as **recurring payment** and process an authorization charge of the checkout amount indicated, **which is instantly reimbursed**. Note that this doesn’t automatically imply further payments from this customer - at this point, we’re just tokenizing the card.
To create a new checkout resource, make a POST request to the `https://api.sumup.com/v0.1/checkouts` endpoint.
Example of such request:
```bash
1
curl -X POST \
2
https://api.sumup.com/v0.1/checkouts \
3
-H "Authorization: Bearer $SUMUP_API_KEY" \
4
-H 'Content-Type: application/json' \
5
-d '{
6
"checkout_reference": "MYCHECKOUT",
7
"amount": 100,
8
"currency": "EUR",
9
"merchant_code": "MDEERENR",
10
"description": "My checkout",
11
"customer_id": "MYCUSTOMERID-123",
12
"purpose": "SETUP_RECURRING_PAYMENT"
13
}'
```
You should expect a standard `201 Created` response, with the checkout reference and both merchant and customer information.
```json
1
{
2
"amount": 100,
3
"checkout_reference": "MYCHECKOUT",
4
"checkout_type": "checkout",
5
"currency": "EUR",
6
"customer_id": "MYCUSTOMERID-123",
7
"date": "2025-10-29T15:09:11.550+00:00",
8
"description": "My checkout",
9
"id": "7164c99b-13cb-42a1-8ba1-3c2c46a29de7",
10
"merchant_code": "MDEERENR",
11
"merchant_country": "PL",
12
"merchant_name": "Test Account",
13
"pay_to_email": "a8e019f9bb2f49159182e8bd61eb5ea6@developer.sumup.com",
14
"purpose": "SETUP_RECURRING_PAYMENT",
15
"status": "PENDING",
16
"transactions": []
17
}
```
For more information, see the [create a checkout](/api/checkouts/create) endpoint.
## Processing Request with Payment Widget
[Section titled “Processing Request with Payment Widget”](#processing-request-with-payment-widget)
The [SumUp’s Payment Widget](/online-payments/checkouts/card-widget/) is a JavaScript library that allows you to securely process checkouts and collect card details securely, handling consent collection and 3DS verification. These steps are mandatory due to legal requirements, which is why you should always process the checkout with the widget.
Once you have a checkout reference from the step above, you can mount the payment widget into your website and collect the card details. Pass the `checkout_reference` from above as the `checkoutId` here.
```html
1
2
6
```
Upon mounting the Payment Widget with a recurring purpose checkout, you should see the following screen:
Card on file with payment widget
The user is prompted to enter their card details, give consent to store their card details and complete the checkout. The widget uses the [Process Checkout endpoint](/api/checkouts/process) to securely process the checkout. We strongly recommend using the widget over direct integration, as the widget correctly handles all legal requirements for payments.
If the previous operation is successful, and the card is stored with the **Save for future payments option**, a `payment_instrument` object containing a `token` representing the card is created (AKA tokenized card) for this customer.
```json
1
"payment_instrument": {
2
"mandate_reference": "2078683",
3
"token": "6878cb7f-6515-47bf-bdd9-1408d270fdce"
4
}
```
At any time, you can fetch the list of tokenized cards of a customer by requesting them via [the list payment instruments](/api/customers/list-payment-instruments) endpoint.
```bash
1
curl -X GET \
2
"https://api.sumup.com/v0.1/customers/${CUSTOMER_ID}/payment-instruments" \
3
-H "Authorization: Bearer $SUMUP_API_KEY" \
4
-H "Content-Type: application/json;charset=UTF-8"
```
## Setting up Recurring Payments
[Section titled “Setting up Recurring Payments”](#setting-up-recurring-payments)
Having tokenized the customer’s card, we can use it to process recurring payments. For detailed information, read the [Recurring Payments](/online-payments/guides/recurring-payments) guide.
# Plugins
> Summarizes the SumUp plugins offering for third-party tools.
Plugins are dedicated solutions for a quick implementation of payments via SumUp on specific platforms, specifically Prestashop, Wix, and Woocomerce. They only require you to provide an API key and your merchant information to get started. For detailed information, select the plugin you want to use.
[Prestashop](/online-payments/plugins/prestashop/)
[Prestashop](/online-payments/plugins/prestashop/)
[](/online-payments/plugins/prestashop/)
[Wix](/online-payments/plugins/wix/)
[Wix](/online-payments/plugins/wix/)
[](/online-payments/plugins/wix/)
[Woocommerce](/online-payments/plugins/woocommerce/)
[Woocommerce](/online-payments/plugins/woocommerce/)
[](/online-payments/plugins/woocommerce/)
# PrestaShop
> Accept payments using SumUp with PrestaShop.
For PrestaShop you can use the SumUp Payment module plugin, which requires a few configurations in your SumUp dashboard.
[Download PrestaShop Plugin](https://addons.prestashop.com/en/payment-card-wallet/44630-sumup-payment.html)
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
1. To get started you will need an active [SumUp account](https://me.sumup.com). As an authorised Payment Institution by the Central Bank of Ireland, SumUp will require certain documents to verify you as the individual and owner of the business you’re registering with. Please make sure your business model is supported by SumUp, according to our [allowed businesses article](https://help.sumup.com/en-GB/articles/3G8ZHjdgFZjmKWOmDWS52m).
Note
Currently the Alternative Payment Methods (APMs) are not available in SumUp plugins. We are working on it and will soon be able to offer APMs in plugins.
## Installation
[Section titled “Installation”](#installation)
1. Follow the instructions described in [the register application guide](/tools/authorization/register-app) in order to obtain the client credentials for your app.
2. Download the client credentials JSON as described in the [access client credentials section](/tools/authorization/register-app/#4-access-the-client-credentials)
3. Upload the JSON to the “Module Configuration” page in your PrestaShop Backoffice.
4. Once your account is fully verified by SumUp, [contact us](/contact) to request enabling of the online payments scope for your PrestaShop online store.
Once you receive a confirmation from SumUp you’re fully set-up! Please note that the smallest amount that you can accept through SumUp is 1 EUR (or equivalent).
Note
Need help? Contact our [customer service](https://me.sumup.com/en-gb/support) for assistance.
# WIX
> Accept payments using SumUp with WIX.
This guide will help you set up SumUp as your payment provider on your [WIX online store](https://wix.com). By connecting your WIX dashboard to SumUp, you can accept payments through our secure and easy-to-use payment gateway.
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
Before you start, make sure you have:
1. An active [SumUp account](https://me.sumup.com). If you don’t have one yet, you can sign up on [our website](https://me.sumup.com/signup). As an authorized Payment Institution by the Central Bank of Ireland, SumUp will require certain documents to verify your identity and business ownership. Please make sure your business model is supported by SumUp, according to our [allowed businesses article](https://help.sumup.com/en-GB/articles/3G8ZHjdgFZjmKWOmDWS52m).
2. A WIX online store.
With this integration, the following Alternative Payment Methods (APMs) are available at checkout: iDeal (Netherlands), Bancontact (Belgium), P24 (Poland), EPS (Austria). Please note, that currently Apple Pay and Google Pay are not available.
## Installation
[Section titled “Installation”](#installation)
Here’s how you can connect SumUp to your WIX online store:
1. First, create your secret API Key. [See this article](/tools/authorization/authorization/#integration-via-api-keys) for full information on how to do it. Copy your key before proceeding.
2. Head over to your WIX dashboard.
3. Go to **Settings** and click on **Accept payments**.
4. Select **SumUp**, paste your secret API Key in the required field under **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, don’t hesitate to contact our [customer service](https://me.sumup.com/en-gb/support) team.
# WooCommerce
> Accept payments using SumUp with WooCommerce.
If you already have a WordPress website and would like to complete it with accepting payments, you can do so with the [SumUp Payment Gateway for WooCommerce plugin](https://wordpress.org/plugins/sumup-payment-gateway-for-woocommerce/). It will allow you to take payments in your online store with an easy and quick integration without any coding required.
The plugin is a lightweight integration option enabling your customizations and providing your customers the convenience of securely buying products from your website without being redirected to other pages. It accepts all major card schemes like VISA, MasterCard, American Express, Diners, Discover and JCB.
Transactions are processed through the SumUp payment platform allowing you to track your [transaction history through the SumUp Dashboard](https://me.sumup.com/sales/transactions).
Note
The SumUp WooCommerce plugin is SCA ready and compliant with PCI standards.
If you’re just getting started with SumUp, review our [allowed businesses list](https://help.sumup.com/hc/en-gb/articles/115008338707-Restricted-businesses) prior to [signing up](https://me.sumup.com).
[Go to plugin page](https://wordpress.org/plugins/sumup-payment-gateway-for-woocommerce/)
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
To get started you will need an active [SumUp account](https://me.sumup.com). As an authorized Payment Institution by the Central Bank of Ireland, SumUp will require certain documents to verify you as the individual and owner of the business you’re registering with. Please make sure your business model is supported by SumUp, according to our [allowed businesses article](https://help.sumup.com/en-GB/articles/3G8ZHjdgFZjmKWOmDWS52m).
## Installing the plugin
[Section titled “Installing the plugin”](#installing-the-plugin)
### Automatic Installation
[Section titled “Automatic Installation”](#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
[Section titled “Manual Installation”](#manual-installation)
The manual installation method involves downloading our plugin and uploading it to your web server via your favorite FTP application. The [WordPress codex](https://wordpress.org/support/article/managing-plugins/#manual-upload-via-wordpress-admin) contains instructions on how to do this.
Before setting up the plugin, you must create your client credentials. They will be used afterwards to configure the plugins.
## Integration Options
[Section titled “Integration Options”](#integration-options)
For plugin versions above `2.5` 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
[Section titled “Simple Integration”](#simple-integration)
This integration option is available to plugin versions above `2.5`.
1. Click on the **Connect account** button to initiate the lightweight integration flow. You will be redirected to your Online Payments settings in the SumUp Dashboard.
2. In your SumUp Dashboard, click on **Start setup** to begin the creation of 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.
You can now begin 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
[Section titled “Advanced Integration”](#advanced-integration)
1. Once the plugin is activated, click on **Advanced version** option.
2. [Create your API Key](/tools/authorization/authorization/#create-api-key)
3. Enter your credentials from your SumUp account (API Key, email and merchant code) and configure any settings as needed.
## Additional configuration
[Section titled “Additional configuration”](#additional-configuration)
* 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
* Requires 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 accessed in WooCommerce/Status/Logs)
* Choose between popup or embedded payment form with the “Open Payment in modal?” option
#### Update your website
[Section titled “Update your website”](#update-your-website)
Before you begin 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)
[Section titled “Configuration for legacy plugin (version older than 2.5)”](#configuration-for-legacy-plugin-version-older-than-25)
### Create your client credentials
[Section titled “Create your client credentials”](#create-your-client-credentials)
To create client credentials you must have an active [SumUp account](https://me.sumup.com) and have already filled in your [account details](https://me.sumup.com/account). It is important that your account has successfully completed the onboarding process and you have requested the `payments` scope activation. If you don’t have the `payments` scope activated, [message us](/contact) for assistance.
Create your credentials [here](https://developer.sumup.com/apps).
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/register-app/) to set up your client credentials. In that page you find information on how to register an app and your client credentials which are necessary for setting up the plugin in your Wordpress account.
## Plugin Configuration
[Section titled “Plugin Configuration”](#plugin-configuration)
Now that you have created your client credentials, you can proceed with configuring the SumUp WooCommerce plugin. Before you begin make sure you have the WooCommerce plugin installed.
Once in the WordPress Dashboard, navigate to the **Plugins** section and select **Settings** under the SumUp Woocommerce plugin. Descriptions of the setting page fields can be found below:
* 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
1
{
2
"id": "CCCFAXYD",
3
"name": "My Online Store Name",
4
"client_id": "fOcmczrYtYMJ7Li5GjMLLcUeC9dN",
5
"client_secret": "717bd571b54297494cd7a79b491e8f2c1da6189c4cc2d3481380e8366eef539c",
6
"application_type": "web",
7
"redirect_uris": ["https://mywebsite.com/callback"]
8
}
```
* The email address you sign into your SumUp merchant account with
* The merchant code associated to your SumUp account
* Requires ZIP code from your customers. **Mandatory for US merchants**
* We recommend enabling this option for better troubleshooting should any issues occur (Logs can be accessed in WooCommerce/Status/Logs)
# Online Payments SDKs
> Overview of the available SumUp SDKs for online payments.
SumUp provides the following Online Payment SDKs:
* [PHP SDK](/online-payments/sdks/php-sdk) - general purpose SDK for all endpoints
* [React Native SDK](/online-payments/sdks/react-native-sdk) - provides a payment sheet that is displayed on top of your app
* [Swift Checkout SDK](/online-payments/sdks/swift-checkout) - fast online checkout experience for Apple Pay and Google Pay
# PHP SDK
> Introduction to the SumUp PHP SDK and first steps to get you started.
SumUp provides a library that allows smoother integration into the [SumUp’s API](/api). It is written in [PHP](http://php.net/) as one of the most requested by developers programming language. It is designed to facilitate payment integrators, developers and other interested parties when building payment checkout experiences and provides easier access to other services like:
* managing merchant profiles
* managing checkouts
* managing customers
* managing payouts
* querying transactions
## Installation
[Section titled “Installation”](#installation)
The SumUp eCom PHP SDK can be installed with [Composer](https://getcomposer.org/). Run the following command:
```bash
1
composer require sumup/sumup-ecom-php-sdk
```
## Basic usage
[Section titled “Basic usage”](#basic-usage)
```php
1
try {
2
$sumup = new \SumUp\SumUp([
3
'app_id' => 'YOUR-CLIENT-ID',
4
'app_secret' => 'YOUR-CLIENT-SECRET',
5
'code' => 'YOUR-AUTHORIZATION-CODE'
6
]);
7
$checkoutService = $sumup->getCheckoutService();
8
$checkoutResponse = $checkoutService->create($amount, $currency, $checkoutRef, $payToEmail);
9
$checkoutId = $checkoutResponse->getBody()->id;
10
// pass the $chekoutId to the front-end to be processed
11
} catch (\SumUp\Exceptions\SumUpAuthenticationException $e) {
12
echo 'Authentication error: ' . $e->getMessage();
13
} catch (\SumUp\Exceptions\SumUpResponseException $e) {
14
echo 'Response error: ' . $e->getMessage();
15
} catch(\SumUp\Exceptions\SumUpSDKException $e) {
16
echo 'SumUp SDK error: ' . $e->getMessage();
17
}
```
## SDK documentation
[Section titled “SDK documentation”](#sdk-documentation)
For more information read the **[documentation](https://github.com/sumup/sumup-ecom-php-sdk)**.
# React Native Payment SDK
> Step-by-step guide for integrating the SumUp React Native Payment SDK, from prerequisites to checkout creation and mounting the payment sheet.
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.
Challenge screen
## Integration
[Section titled “Integration”](#integration)
### Before you begin
[Section titled “Before you begin”](#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 **test account** reach out to our support team through this [contact form](/contact).
* You have [registered your client application](/tools/authorization/register-app/) with SumUp.
* You have a valid access token obtained via the [Authorization code flow](/tools/authorization/authorization/#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 how to create a single payment [here](https://developer.sumup.com/online-payments/guides/single-payment/#before-you-begin).
### Create a checkout
[Section titled “Create a checkout”](#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:
* cURL
```bash
1
curl --request POST \
2
--url https://api.sumup.com/v0.1/checkouts \
3
--header "Authorization: Bearer $SUMUP_API_KEY" \
4
--header 'Content-Type: application/json' \
5
--data '{
6
"checkout_reference": "44ea5096-b83f-46e1-9323-fe82a8cb7eb5",
7
"currency": "SEK",
8
"amount": 9.99,
9
"description": "Order #1234",
10
"merchant_code": "MXXXXXXX",
11
"return_url": "https://example.com",
12
"redirect_url": "https://sumup.com"
13
}'
```
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
[Section titled “Set up SDK”](#set-up-sdk)
Install the npm module by one of the following commands:
* npm
```bash
1
npm i sumup-react-native-alpha
2
npm i react-native-webview
```
* yarn
```bash
1
yarn add sumup-react-native-alpha
2
yarn add react-native-webview
```
You need to install `react-native-localization` to automatically detect the user system language.
* npm
```bash
1
npm i react-native-localization
```
* yarn
```bash
1
yarn add react-native-localization
```
If you don’t need it, please provide the language field in the `initPaymentSheet` function.
```javascript
1
await initPaymentSheet({
2
checkoutId,
3
language: 'en',
4
});
```
Next, install the native modules.
```bash
1
cd ios
2
pod install
```
SDK should be initialized by wrapping your payment screen into SumUpProvider. This component requires an `apiKey` that can be created [here](/protected/api-keys/).
```javascript
1
import { SumUpProvider } from 'sumup-react-native-alpha';
2
3
export default function App() {
4
return (
5
6
7
8
);
9
}
```
## Provide payment details
[Section titled “Provide payment details”](#provide-payment-details)
Before showing the payment sheet, it needs to be initialized. Call `initPaymentSheet` with the parameters like in example below:
```js
1
import React, { useEffect } from "react";
2
import { View, Alert } from "react-native";
3
import { useSumUp } from "sumup-react-native-alpha";
4
5
export default function MainScreen() {
6
const { initPaymentSheet } = useSumUp();
7
8
const initSumUpPaymentSheet = async () => {
9
const { error } = await initPaymentSheet({
10
checkoutId: "...",
11
customerId: "...",
12
language: "en", // en or sv are supported
13
});
14
15
16
if (error) {
17
Alert.alert(
18
error.status,
19
error.status === "failure" ? error.message : undefined
20
);
21
} else {
22
Alert.alert("Payment Sheet was configured");
23
}
24
};
25
26
useEffect(() => {
27
initSumUpPaymentSheet();
28
}, []);
29
30
...
```
**Required** fields for `initPaymentSheet`:
* `checkoutId` - described in section [Create a checkout](/online-payments/sdks/react-native-sdk/#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
[Section titled “Show Payment Sheet”](#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
1
...
2
3
const showPaymentSheet = async () => {
4
const { error } = await presentPaymentSheet();
5
6
7
if (error) {
8
Alert.alert(
9
error.status,
10
error.status === "failure" ? error.message : undefined
11
);
12
} else {
13
Alert.alert("Payment successfully was processed");
14
}
15
};
16
17
18
return (
19
20
21
22
);
23
}
```
## Optional Integrations
[Section titled “Optional Integrations”](#optional-integrations)
### Save a card for future usage
[Section titled “Save a card for future usage”](#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:
* cURL
```bash
1
curl -L -X POST 'https://api.sumup.com/v0.1/customers' \
2
-H 'Content-Type: application/json' \
3
-H 'Accept: application/json' \
4
-H "Authorization: Bearer $SUMUP_API_KEY" \
5
--data-raw '{
6
"customer_id": "831ff8d4cd5958ab5670",
7
"personal_details": {
8
"first_name": "John",
9
"last_name": "Doe",
10
"email": "user@example.com",
11
"phone": "+491635559723",
12
"birthdate": "1993-12-31",
13
"address": {
14
"city": "Berlin",
15
"country": "DE",
16
"line1": "Sample street",
17
"line2": "ap. 5",
18
"postal_code": "10115",
19
"state": "Berlin"
20
}
21
}
22
}'
```
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
1
await initPaymentSheet({
2
// ...
3
customerId: '...',
4
});
```
### Use Google Pay
[Section titled “Use Google Pay”](#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
1
2
...
3
6
```
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
1
await initPaymentSheet({
2
// ...
3
googlePay: {
4
isProductionEnvironment: false,
5
},
6
});
```
### Use Apple Pay
[Section titled “Use Apple Pay”](#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
[Section titled “Register for an Apple Merchant ID”](#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
1
await initPaymentSheet({
2
// ...
3
applePay: {
4
merchantIdentifier: 'merchant.com.{{YOUR_APP_NAME}}',
5
label: 'Pay',
6
},
7
});
```
# Swift Checkout SDK
> Learn about the Swift Checkout SDK to offer Apple Pay and Google Pay on your website with minimal setup.
## About Swift Checkout SDK
[Section titled “About Swift Checkout SDK”](#about-swift-checkout-sdk)
The Swift Checkout SDK enables you to offer a complete and fast checkout experience to your end users, allowing you to collect payment, address, and contact information with a click of a button. Swift Checkout SDK allows for Google Pay and Apple Pay setup.
### Prerequisites
[Section titled “Prerequisites”](#prerequisites)
* Add a payment method to your browser or wallet. For example, you can save a card in Chrome, add a card to your Apple Wallet for Safari and iOS
* Serve your application over HTTPS. This is a requirement both in development and in production environments. One way to get up and running is to use a service like [ngrok](https://ngrok.com/)
Currently available payment methods through Swift Checkout SDK:
Caution
For pages that have a strict Content Security Policy (CSP) visit the [Handling CSP](/online-payments/checkouts/card-widget/#handling-strict-content-security-policies) instructions.
* [Apple Pay](#apple-pay-setup)
* [Google Pay](#google-pay-setup)
Note
Please note, that Swift Checkout SDK is in Alpha version, expect changes to be communicated in the future. For any feedbacks or questions, you can reach out to us through our [contact form](/contact).
## SumUp Swift Checkout SDK setup
[Section titled “SumUp Swift Checkout SDK setup”](#sumup-swift-checkout-sdk-setup)
Include the SDK.js in your page as shown below:
```html
1
2
3
4
5
```
Or with JavaScript:
```javascript
1
function injectScript() {
2
return new Promise((resolve) => {
3
var script = document.createElement('script');
4
script.type = 'text/javascript';
5
script.onload = function () {
6
resolve(window.SumUp);
7
};
8
script.src = 'https://js.sumup.com/swift-checkout/v1/sdk.js';
9
document.body.appendChild(script);
10
});
11
}
```
Once the script is loaded, a new SumUp object is injected into the window instance representing SumUp SDK namespace, which contains the SwiftCheckout client.
## Obtaining a public API key
[Section titled “Obtaining a public API key”](#obtaining-a-public-api-key)
To obtain a public API key navigate to your [Developer Settings Portal](https://developer.sumup.com/auth/login) and select **API keys** from the top right corner menu. Your public merchant key will be automatically generated with a `Private` label and a value such as `sup_pk_0x98lsJhJAs...u5kvg`.
## SumUp Swift Checkout client
[Section titled “SumUp Swift Checkout client”](#sumup-swift-checkout-client)
```javascript
1
const swiftCheckoutClient = new window.SumUp.SwiftCheckout('sup_pk_0x98lsJhJAs...u5kvg');
```
The client contains a set of objects to render a payment element UI, request payment authorization and process a payment using SumUp’s API.
### Payment request object
[Section titled “Payment request object”](#payment-request-object)
The payment request object requests payment authorizations made with various payment methods. It requires an argument that contains a set of details, information about the requested transaction to be processed, that will be presented to the user to authorize the payment later.
Payment request object arguments consist of:
* `countryCode`: Represents the country or region of the merchant’s principle place of business.
* `total`: Represents what is about to be paid by the user, E.g. a summary of an order. It requires a `label` and an `amount`. The `amount` value must be provided as a string in major unit and should use a period (`.`) as a decimal separator.\
More specifically, the `amount` value should match the following regex: `^[0-9]+(\.[0-9][0-9])?$`
Optional:
* `locale`: Represents the locale the text “Pay with {{payment method}}” will be displayed with in the buttons.
```js
1
const paymentRequest = swiftCheckoutClient.paymentRequest({
2
countryCode: 'DE',
3
locale: 'de-DE',
4
total: {
5
label: 'My goods',
6
amount: { currency: 'EUR', value: '65.00' },
7
},
8
});
```
* `shippingOptions`: Represents a collection of shipping methods the end user can select from to receive their purchased goods. The initial `shippingOptions` list can be later modified according to the shipping address the user selects in the payment dialog.
```js
1
const paymentRequest = swiftCheckoutClient.paymentRequest({
2
shippingOptions: [
3
{
4
id: 'post',
5
label: 'postal service',
6
amount: { currency: 'EUR', value: '0.00' },
7
description: 'free post',
8
},
9
],
10
});
```
This object is an analogue to the [PaymentRequest - Web APIs](https://developer.mozilla.org/en-US/docs/Web/API/PaymentRequest/PaymentRequest).
The payment request instance contains the logic related to **checking payment method availability and showing** the payment method dialogue once the user interacts with a **payment element**.
### Payment request interface
[Section titled “Payment request interface”](#payment-request-interface)
All methods in the payment request object are asynchronous. Listed below are the payment request methods and their usage:
#### `canMakePayment`
[Section titled “canMakePayment”](#canmakepayment)
Checks if the given merchant public key has access to at least one payment method and checks the payment method availability in the given environment (browser). Returns a promise that resolves in a `boolean`.
#### `availablePaymentMethods`
[Section titled “availablePaymentMethods”](#availablepaymentmethods)
Returns the available payment methods for a merchant. Returns a promise that resolves in an `array` of objects representing each available payment method.
#### `show`
[Section titled “show”](#show)
Shows the payment authorization dialogue for a given payment method. It requires an object containing a `paymentMethod`, which defines the selected payment method. This method is usually used along with the `PaymentElement`’s `onSubmit` event.
The `show` method resolves with a `AuthorizedPayment`, which contains the `details` shared by the user once they authorize the payment request. The property `details` contains `paymentMethod`, `contactInformation`, `shippingAddress` and may contain `shippingOptions`.
A `PaymentRequestCancelledError` will be thrown when the user rejects or cancels the transaction.
```js
1
paymentRequest
2
.show({ paymentMethod: 'apple_pay' })
3
.then(processCheckoutAttempt)
4
.then(handleResponse)
5
.catch((error) => {
6
if (
7
error instanceof SumUp.SwiftCheckout.Errors.PaymentRequestCancelledError
8
) {
9
console.log('Cancelled by the user');
10
} else {
11
throw error;
12
}
13
});
```
#### `abort`
[Section titled “abort”](#abort)
Terminates a payment request before it is processed. Once a payment request has been terminated using this method, the payment request will not be processed and the payment dialogue will be closed.
```js
1
if (someCustomCheck()) {
2
try {
3
await paymentRequest.abort(); // will throw an error.
4
console.log('Payment request aborted due to my custom reason.')
5
} catch(e) {
6
console.error(
7
'Unable to abort, because the user is currently in the process of paying.'
8
);
9
}
10
}
```
Note
The `abort` method should only be used if the payment request has not yet been processed. Attempting to cancel a payment request after it has been processed may result in unexpected behaviour.
#### `onShippingAddressChange`
[Section titled “onShippingAddressChange”](#onshippingaddresschange)
Allows adding an event handler which will be triggered every time the user changes their shipping address. The handler can optionally provide a return value to change the following in the payment dialog:
* `total`
* `shippingOptions`
```js
1
paymentRequest.onShippingAddressChange(async (newShippingAddress) => {
2
const { total, shippingOptions } = await someAsyncOperation(
3
newShippingAddress,
4
);
5
6
return {
7
total,
8
shippingOptions,
9
};
10
});
```
Note
To protect user privacy, browsers might hide non-essential and sensitive details from the shipping address, and only provide data required for shipping cost estimation. The extent of information provided can vary based on the chosen browser and payment method, leading to certain fields being absent. For example, the displayed shipping address might be limited to the city, state, country, and ZIP code.
The full shipping address is disclosed only in the `PaymentResponse` object after the payment is authorized by the account holder.
#### `onShippingOptionsChange`
[Section titled “onShippingOptionsChange”](#onshippingoptionschange)
Allows adding an event handler which will be triggered every time the user changes their shipping option choice. The handler can optionally provide a return value to change the following in the payment dialog:
* `total`
* `shippingAddress`
* `shippingOptions`
```js
1
paymentRequest.onShippingOptionsChange(async (selectedShippingOption) => {
2
const { newTotal, newShippingAddress, newShippingOptions } = await someAsyncOperation(
3
total
4
shippingOption,
5
);
6
7
return {
8
total,
9
shippingAddress,
10
shippingOptions,
11
};
12
});
```
### Payment element builder
[Section titled “Payment element builder”](#payment-element-builder)
In order to request a payment, you need to create a UI element. The SDK provides a built-in PaymentElement UI builder, which allows you to create and configure the payment buttons.
*Each payment button can be rendered individually as well.*
The Swift Elements Builder allows you to attach an `onSubmit` handler, which will be called once the user clicks on one of the buttons rendered by it. The `mount` method accepts a `paymentMethods` array, enabling you to filter the payment methods you want to offer. The arguments passed during `mount`, will render one or more buttons:
```js
1
const buttons = swiftCheckoutClient.elements();
2
buttons
3
.onSubmit((paymentEvent) => console.log(paymentEvent))
4
.mount({
5
paymentMethods: [
6
{ id: 'apple_pay' },
7
{ id: 'google_pay' }
8
// See `paymentRequest.availablePaymentMethods()` for all available payment methods
9
],
10
container: document.querySelector('#express-checkout-container'),
11
});
```
Note
You can create your own custom buttons, but we recommend using the built-in PaymentElement UI builder.
#### Rendering buttons for available payment methods
[Section titled “Rendering buttons for available payment methods”](#rendering-buttons-for-available-payment-methods)
Once the UI and Payment Request are configured, you have to check the availability of Swift payment methods and `mount` them into the page.
The SDK checks several factors to determine if a given payment method is available:
* Is the payment method available for the given merchant?
* Is the payment method available on the browser?
* Is the wallet/card ready to accept payment requests?
After checking if making payments is possible, render the payment element into a given placeholder as shown below:
```js
1
paymentRequest.canMakePayment().then((isAvailable) => {
2
if (isAvailable) {
3
paymentRequest.availablePaymentMethods().then((paymentMethods) => {
4
buttons.mount({
5
paymentMethods,
6
container: document.querySelector('#express-checkout-container'),
7
});
8
});
9
} else {
10
console.error('No payment method available!');
11
}
12
});
```
### Requesting payment authorization
[Section titled “Requesting payment authorization”](#requesting-payment-authorization)
The authorization dialogue is where the user will review the payment requested, select a payment card and a shipping address. Finally, they can authorize the payment request to be **processed**.
Using the payment element builder, configure it to `show` the payment authorization dialogue from the Payment Request instance upon the `onSubmit` event. Once the user authorizes the payment the `show` method will resolve a `PaymentResponse` containing details about the payment authorization.
```js
1
buttons.onSubmit((paymentMethodEvent) => {
2
paymentRequest
3
.show(paymentMethodEvent)
4
.then((paymentResponse) => console.log(paymentResponse));
5
});
```
To understand more about the PaymentResponse objects see Mozilla’s official [PaymentResponse - Web APIs](https://developer.mozilla.org/en-US/docs/Web/API/PaymentResponse) documentation.
### Processing an authorized payment request
[Section titled “Processing an authorized payment request”](#processing-an-authorized-payment-request)
To process a payment, the SumUp API requires you to create a checkout for a given amount. The checkout creation requires an authenticated request. Thus, we recommend implementing an endpoint on your backend that will authenticate with our API, create a checkout and return a `checkoutId`.
Once you obtain a `checkoutId`, call the `processCheckout` method from the SwiftCheckout client with the `checkoutId` and the `PaymentResponse`, which was received in the previous step, to start the processing the checkout.
```js
1
paymentRequest
2
.show(paymentMethodEvent)
3
.then((paymentResponse) => {
4
console.log(paymentResponse.details); // contactInfo, shippingAddress, etc.
5
// here you create your order and a sumup checkout
6
const checkoutId = 'c463bf5e-d397-4bca-9d2e-a4e04f668b1c';
7
8
return swiftCheckoutClient.processCheckout(checkoutId, paymentResponse);
9
})
10
.then(console.log)
11
.catch(console.error);
```
### The complete implementation
[Section titled “The complete implementation”](#the-complete-implementation)
```js
1
const swiftCheckoutClient = new window.SumUp.SwiftCheckout(
2
'fOcmczrYtYMJ7Li5GjMLLcUeC9dN',
3
);
4
5
const paymentRequest = swiftCheckoutClient.paymentRequest({
6
total: {
7
label: 'One Shoe',
8
amount: {
9
value: '100.0',
10
},
11
},
12
shippingOptions: [
13
{
14
id: 'post',
15
label: 'postal service',
16
amount: { currency: 'EUR', value: '0.00' },
17
description: 'free post',
18
},
19
],
20
});
21
22
const buttons = swiftCheckoutClient.elements();
23
buttons.onSubmit((paymentMethodEvent) => {
24
paymentRequest
25
.show(paymentMethodEvent)
26
.then((paymentResponse) => {
27
console.log(paymentResponse.details);
28
29
// Create your order and a checkout
30
const checkoutId = 'c463bf5e-d397-4bca-9d2e-a4e04f668b1c';
31
32
return swiftCheckoutClient.processCheckout(checkoutId, paymentResponse);
33
})
34
.then((result) => {
35
if (result.status === 'PAID') {
36
window.location.href = '/thankyou';
37
} else {
38
console.error(
39
'It was not possible to process the checkout',
40
result.message,
41
);
42
}
43
})
44
.catch((error) => {
45
if (
46
error instanceof SumUp.SwiftCheckout.Errors.PaymentRequestCancelledError
47
) {
48
console.error('Cancelled by the user');
49
} else {
50
throw error;
51
}
52
});
53
});
54
55
paymentRequest.canMakePayment().then((isAvailable) => {
56
if (isAvailable) {
57
paymentRequest.availablePaymentMethods().then((paymentMethods) => {
58
buttons.mount({
59
paymentMethods,
60
container: document.querySelector('#express-checkout-container'),
61
});
62
});
63
} else {
64
console.error('No payment method is available.');
65
}
66
});
```
## Error handling
[Section titled “Error handling”](#error-handling)
The Swift Checkout SDK returns a series of Errors depending on the event that has taken place. You can use the errors to customise the user experience and communicate error causes as you see fit.
* `PaymentRequestCancelledError` is thrown when the end user closes the open payment dialog or presses the button `esc`.
* `PaymentRequestInvalidActionError` is thrown when the end user has submitted the payment dialog and then attempted to cancel the payment. Once the payment form is submitted the payment can no longer be cancelled.
* `PaymentRequestInternalError` is thrown when attempting to handle the payment request in a forbidden manner. Reasons that you may receive include the following codes, available in the `code` field of the Error object:
* `SHIPPING_CONTACT_SELECTION`
* `SHIPPING_ADDRESS_SELECTION`
* `SHIPPING_METHOD_SELECTION`
* `INTERNAL_VALIDATION`
* `COMPLETE_PAYMENT`
* `UNKNOWN`
## Apple Pay Setup
[Section titled “Apple Pay Setup”](#apple-pay-setup)
### Prerequisites
[Section titled “Prerequisites”](#prerequisites-1)
* [Verify your domain with Apple Pay](#verify-your-domain-with-apple-pay), both in development and production
* For Apple Pay [additional configurations](#apple-pay-setup) are required, including macOS 10.12.1+ or iOS 10.1+
### Verify your domain with Apple Pay
[Section titled “Verify your domain with Apple Pay”](#verify-your-domain-with-apple-pay)
To use Apple Pay, you need to register with Apple on all of your web domains which will show an Apple Pay button.
Apple’s documentation for Apple Pay on the Web describes their process of “merchant validation”, which SumUp handles for you behind the scenes. You don’t need to create an Apple Merchant ID, CSR and so on, as described in their documentation. Instead, follow the steps in this section:
1. Request the domain association file through our [contact form](https://developer.sumup.com/contact/) and host it at `https://[YOUR_DOMAIN_NAME]/.well-known/apple-developer-merchantid-domain-association`.
2. Once hosted, request assistance from our integration specialists through the form, to register your domain with Apple.
## Google Pay Setup
[Section titled “Google Pay Setup”](#google-pay-setup)
### Prerequisites
[Section titled “Prerequisites”](#prerequisites-2)
* [Request production access](https://pay.google.com/business/console/) to Google Pay for your domain name
* Adhere to the [Google Pay requirements](https://developers.google.com/pay/api/web/guides/setup#get-started)
* Review [Google Pay API terms of service](https://payments.developers.google.com/terms/sellertos)
### Google Pay specific parameters
[Section titled “Google Pay specific parameters”](#google-pay-specific-parameters)
Google Pay’s base payment request object requires a few unique parameters:
* [`merchantInfo` object](https://developers.google.com/pay/api/web/reference/request-objects#MerchantInfo) with the following keys:
* `merchantId`- unique identifier provided to you by Google once you [register your domain](https://pay.google.com/business/console/) with them
* `merchantName`- your merchant name
Here’s an example of how the merchantInfo object is included in a Google Pay payment request:
```js
1
const paymentRequest = sumUpClient.paymentRequest({
2
methodData: [
3
{
4
supportedMethods: 'google_pay',
5
data: {
6
merchantInfo: {
7
merchantId: '123456789123456789',
8
merchantName: 'Example Merchant',
9
},
10
},
11
},
12
],
13
});
```
### Validating your domain with Google Pay
[Section titled “Validating your domain with Google Pay”](#validating-your-domain-with-google-pay)
In order to use Google Pay you need to validate your domain with Google. This process requires rendering a non-functional Google Pay button on your website and providing them with screenshots of your checkout flow.
To render a Google Pay button on your shop in demo mode, you need to add the `#sumup:google-pay-demo-mode` hash to the page’s URL.
Once the hash has been applied you can proceed with the domain validation steps:
1. Create an account in the [Google Pay console](https://pay.google.com/business/console)
2. Go to the **Google Pay API** tabitem in your Google Pay console
3. Navigate to the **Integrate with your website** and click on **+ Add website**
4. Fill out the form with the requested information (domain name, buyflow screenshots, etc.)
5. At the top of the page click on **Submit for approval**
# 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 favourite 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
[Section titled “Events”](#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
[Section titled “Handling a webhook”](#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
1
{
2
"event_type": "CHECKOUT_STATUS_CHANGED",
3
"id": "id-of-the-changed-checkout"
4
}
```
## Retries
[Section titled “Retries”](#retries)
When an erroneous response is received, a webhook delivery is retried with the following delays:
* 1 minute
* 5 minutes
* 20 minutes
* 2 hours
# 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 authorised 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
[Section titled “Impact on SumUp Merchants”](#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
[Section titled “Interface Availability & Performance Data”](#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) |
# In-Person Payments
> Quickstart for terminal payments, covering prerequisites, hardware options, and affiliate key requirements.
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/tools/sdk) or you can approach a lightweight integration with our [API](/terminal-payments/payment-switch), using the SumUp app to execute payments.
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
* Before you integrate either the [Native SDK](/terminal-payments/tools/sdk/) or the [Payment API Switch](/terminal-payments/payment-switch), you need to create a SumUp account in the [SumUp Dashboard](https://me.sumup.com). Alternatively, you can [create a test account](#getting-a-test-account).
* Once you have an account, you need to [create an Affiliate Key](/tools/authorization/affiliate-keys/) for your app and [provide means of authorization](/tools/authorization/authorization/).
Caution
The Affiliate Key and Application ID coming from your app must match those obtained from the [Developers](https://me.sumup.com/developers) page.
The Card Terminal(s) allow complete flexibility as they are not assigned to individual accounts. Once connected to a merchant account, the card terminal(s) lock to countries and currencies. This includes test accounts, which are intended for testing integrations and do not process any transactions.
You are now ready to start integrating the SumUp payment capabilities in your app, provided you have also received 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 test account
[Section titled “Getting a test account”](#getting-a-test-account)
To start testing SumUp APIs and tools without involving real money, you need to have a test account. You can create a test account from your account in the Dashboard as shown below.
1. Log in to your SumUp account.
2. Open the drop-down menu between Support and your user panel.
3. Select Test Account. Your merchant account is now switched to test mode.
A screenshot of the account selection dropdown in the SumUp dashboard with the test account highlighted with red circle
Once you have your test account you can begin making API calls with real data. Our test accounts **do not** process transactions with real funds. Test account has a different ID, and shows a clear warning. When you try to process a request with the value of 11 (in any currency), the test account will always fail - this is by design, to enable testing failed transactions.
A screenshot of the dashboard with test account selected
When you’re done experimenting with the test account, switch back to a regular account for business purposes.
## Affiliate Keys
[Section titled “Affiliate Keys”](#affiliate-keys)
All card-present integrations require an Affiliate Key. Read the [Affiliate Keys Guide](/tools/authorization/affiliate-keys/) for details.
## Industry
[Section titled “Industry”](#industry)
SumUp merchants operate in various industry segments and we have made sure our card terminals are fit to accommodate a wide range of use cases and business approaches. We have outlined our merchants’ most favoured ones, along with what they find most beneficial from our services:
* [Retail classified businesses and services](/terminal-payments/industry/retail/)
* [The hospitality industry and more specifically Restaurants, Cafés and Bars](/terminal-payments/industry/hospitality/)
* [Transportation and delivery services](/terminal-payments/industry/transport/)
* [Booking for Health, Beauty and Wellness](/terminal-payments/industry/bookings/)
In order to fulfil other industries’ business needs, you are offered a range of integration options through the [Payment SDK](/terminal-payments/tools/sdk) and the [API](/terminal-payments/payment-switch) sections, and also a full list of available services through the [API reference](/api) section.
## Communication with the terminal
[Section titled “Communication with the terminal”](#communication-with-the-terminal)
The SDK and API Switch handle all communication with SumUp’s Card Terminal(s) via Bluetooth (BLE 4.0).
## Security
[Section titled “Security”](#security)
No sensitive data will ever be passed through or stored on the merchant’s phone. All data is encrypted by the card terminal which is certified by the relevant payment industry groups (PCI, EMV I & II, Visa, MasterCard and Amex).
# Cloud API
> Details how to use Solo card readers and run remote in-person payments via the Cloud API.
## About Payments with Cloud API
[Section titled “About Payments with Cloud API”](#about-payments-with-cloud-api)
The Cloud API allows you to start a transaction from a Point of Sales (POS) running on any platform (Windows, iOS, Linux, Android, Web-based etc.) capable of sending HTTPS requests and complete said transaction via a Solo reader.
The main advantages of this integration are:
* Suitability for any operating system and platform.
* Can process simultaneous transactions to multiple Solo card readers at a time.
* No distance limitation between your POS device and the Solo card reader. You can even send transactions remotely.
* No Bluetooth connection required.
* PCI Compliance, ensuring secure and compliant transactions.
The Cloud API integration supports:
* Debit, credit and installment transactions
* The pairing of multiple Solo card readers to any SumUp account
* Naming each Solo card reader as you see fit to guarantee a smooth checkout
* Wi-Fi and mobile data connectivity (the latter needs to be enabled manually by SumUp)
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
* Your device must be authorized to use the Cloud API. [Read the authorization guide](/tools/authorization/authorization/) and implement a method that best fits your use case. The API key should be sufficient if you do not intend to delegate access to third parties.
* You need to [create an Affiliate Key](/tools/authorization/affiliate-keys/) for your app. SumUp Cloud API requires the Affiliate Key to be present in checkout requests.
* We strongly recommend keeping the Solo terminal plugged-in when using Cloud API.
* If you want to use mobile data, make sure that you’re not connected to a Wi-Fi network. Disconnect if you are - in case both mobile data and Wi-Fi is available, Solo reader will always use Wi-Fi.
To disconnect Wi-Fi, go to **Connections** > **Wi-Fi** and disable Wi-Fi using the on-screen slider.
## Solo Virtual Terminal
[Section titled “Solo Virtual Terminal”](#solo-virtual-terminal)
If you don’t have the Solo reader yet, you can still try out the flow using [the Virtual Solo](https://virtual-solo.sumup-vercel.app) with a [SumUp test account](/online-payments/#getting-a-test-account)!
Virtual Solo works just like the real device, with certain limitations. The following actions are not supported virtually:
* Physical card insertion/tap simulation (since there’s no physical Solo involved)
* Real funds transfer (test accounts only)
* PIN entry simulation (always auto-approved)
* Offline transactions
* Custom receipt printing
* Network configuration
* Real device pairing (simulator uses virtual device identifiers)
## Pairing Solo Reader via Cloud API
[Section titled “Pairing Solo Reader via Cloud API”](#pairing-solo-reader-via-cloud-api)
The Cloud API works as bridge between your application and the Solo reader. The Cloud API has two key processes:
1. Pairing a Solo reader to your account.
2. Taking an in-person payment via Solo.
Once the Solo is paired to your SumUp account, you can initiate a request to charge a card from your application and SumUp handles the rest. Your customer goes through a seamless payment experience where all card data is encrypted from end-to-end. Once the payment has been processed the transaction result is available in real time via webhooks.
```
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
[Section titled “Log Out of Solo”](#log-out-of-solo)
Cloud API pairing process is only available for logged-out users. If you’re logged in to your merchant account, do as follows:
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
[Section titled “Generate Pairing Code”](#generate-pairing-code)
In order to initiate a payment on the Solo card reader, the device must be enrolled with the merchant account. This enrollment process is what we call reader pairing. The pairing process starts on the card reader side by generating the pairing code, and finishes when the target device successfully completes a pairing request using the Cloud API, providing the code. Both your application and the Solo card reader need to be connected to the internet (it doesn’t have to be 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.
[Your browser does not support videos.](/img/guides/pair_solo.mp4)
### Pair the Card Reader With Pairing Code
[Section titled “Pair the Card Reader With Pairing Code”](#pair-the-card-reader-with-pairing-code)
1. Send a request to the [Create Reader endpoint](/api/readers/create).
2. Verify pairing confirmation on the reader screen. It appears for a short while, after which the reader returns to the idle screen.
Solo device API pairing confirmation screen.
## Using Paired Reader
[Section titled “Using Paired Reader”](#using-paired-reader)
Cloud API provides the possibility to manage transactions using the connected reader(s), as well as reader management endpoints. For details, check the section below.
### Initiate Transaction
[Section titled “Initiate Transaction”](#initiate-transaction)
This process is asynchronous, and the actual transaction may take some time to be stared on the device.
There are some caveats when using this endpoint:
* The target device must be online, otherwise checkout won’t be accepted
* After the checkout is accepted, the system has 60 seconds to start the payment on the target device. During this time, any other checkout for the same device will be rejected.
* You need to send the Affiliate Key in the request.
Read the [Create Checkout API endpoint documentation](/api/readers/create-checkout) for details on the API request, examples, and parameter descriptions.
### Terminate Transaction
[Section titled “Terminate Transaction”](#terminate-transaction)
Stops the current transaction on the target device. This process is asynchronous, and the actual termination may take some time to be performed on the device.
There are some caveats when using this endpoint:
* The target device must be online, otherwise termination won’t be accepted.
* This action is only possible if the device is waiting for cardholder action: waiting for card, waiting for PIN, etc. There is no confirmation of the termination.
* If a transaction is successfully terminated and `return_url` has been provided on Checkout, the transaction status is sent as failed to the provided URL.
Read the [Terminate Checkout API endpoint documentation](/api/readers/terminate-checkout) for details on the API request, examples, and parameter descriptions.
### List Connected Readers
[Section titled “List Connected Readers”](#list-connected-readers)
List all readers connected to your merchant account.
Read the [List API endpoint documentation](/api/readers/list) for details on the API request, examples, and parameter descriptions.
### Check Reader Status
[Section titled “Check Reader Status”](#check-reader-status)
Check the status of a specific reader.
Read the [Retrieve a Reader endpoint documentation](/api/readers/get) for details on the API request, examples, and parameter descriptions.
### Update Reader
[Section titled “Update Reader”](#update-reader)
Update the data of a specific reader.
Check the [Update a Reader endpoint documentation](/api/readers/update) for details on the API request, examples, and parameter descriptions.
### Delete Reader
[Section titled “Delete Reader”](#delete-reader)
Delete a reader from the Cloud API. After doing this, you also need to physically disconnect the reader using its menu.
Check the [Delete a Reader endpoint documentation](/api/readers/delete) for details on the API request, examples, and parameter descriptions.
## Unpairing Solo Reader
[Section titled “Unpairing Solo Reader”](#unpairing-solo-reader)
In order to unpair a reader from the merchant account, two steps are required:
1. [Delete Reader](#delete-reader) from the Merchant account (via Readers API).
2. [Disconnect Reader](#diconnect-reader) (manually via Solo).
### Disconnect Reader Physically
[Section titled “Disconnect Reader Physically”](#disconnect-reader-physically)
1. Open the menu drawer on your Solo.
2. Go to **Connections**.
3. Select **API** from the menu.
4. Tap on **Disconnect**.
Your Solo device is now disconnected.
## What’s Next?
[Section titled “What’s Next?”](#whats-next)
For other integration possibilities, check the [SDK Integration Documentation](/terminal-payments/sdks/).
# API Payment Switch
> Describes the lightweight Payment Switch flow that hands off to the SumUp app to collect in-person payments.
SumUp API Payment Switch is a light integration where your app will open the SumUp app to request and execute a payment. This integration approach is the go-to solution for web аpplications.
## How does it work?
[Section titled “How does it work?”](#how-does-it-work)
Your app initiates a request to charge a card, opens the SumUp app on the merchant’s mobile device, and we handle the rest. Once the payment has been processed the transaction result is communicated back, and the merchant is returned to your app.
The API integration also allows the possibility to pre-fill the checkout amount and card holder information, and to send a receipt via SMS or email. You can use the cash option, which is not available in our SDK version, for better reporting and management of your funds in the SumUp dashboard.
Activate the [mandatory authorization scopes](/tools/authorization/authorization/#authorization-scopes) for a smooth performance. They will require obtaining an access token for your client application that will authenticate it with the SumUp REST API and authorize it to access server resources.
## API documentation
[Section titled “API documentation”](#api-documentation)
You can find additional documentation for the different mobile platforms below:
* Integrate the [iOS API](https://github.com/sumup/sumup-ios-url-scheme)
* Integrate the [Android API](https://github.com/sumup/sumup-android-api)
# Overview
> An overview of the native Terminal Payment SDKs for iOS and Android and how they drive the checkout UI.
SumUp’s Terminal Payment Native SDK allows a smoother user experience and more control from the merchant app. The SDK supports iOS and Android, being directly integrated into your app which offers greater flexibility and customizations.
## How does it work?
[Section titled “How does it work?”](#how-does-it-work)
The SDK provides all user interface screens to guide merchants and customers through the checkout process within your app, including selecting a terminal, presenting a card, entering the PIN or providing a signature. The checkout process is triggered from within the merchant app, where the checkout result will be returned with all relevant data at the end of the transaction.
In addition to handling the payment and all communication with the terminal, you can update the checkout preferences, like adding a tip, and more.
# Android SDK
> Guides you through integrating the Android SDK, prerequisites, and embedding the checkout flow within your app.
## About Android SDK
[Section titled “About Android SDK”](#about-android-sdk)
This guide provides a step-by-step documentation for SumUp’s native Android SDK, that enables you to integrate our proprietary card terminal(s) and its payment platform to accept credit and debit card payments (incl. VISA, MasterCard, American Express and more). The SDK communicates transparently to the card terminal(s) via Bluetooth (BLE 4.0). Upon initiating a checkout, the SDK guides your user using appropriate screens through each step of the payment process. As part of the process, SumUp provides also the card terminal setup screen, along with the cardholder signature verification screen. The checkout result is returned with the relevant data for your records.
No sensitive card data is ever passed through to or stored on the merchant’s phone. All data is encrypted by the card terminal, which has been fully certified to the highest industry standards (PCI, EMV I & II, Visa, MasterCard & Amex).
Note
SumUp also provides the [Android Tap to Pay SDK](/terminal-payments/sdks/android-ttp) as a separate package for handling tap-to-pay payments via smartphone.
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
* Registered for a merchant account via SumUp’s [country websites](https://sumup.com/) (or created a test account)
* Received SumUp card terminal: Solo, Air, Air Lite or PIN+ Terminal
* Generated an [Affiliate Key](/tools/authorization/affiliate-keys)
* Downloaded the [Android SDK Repository](https://github.com/sumup/sumup-android-sdk)
* SumUp SDK requires `minSdkVersion` 26 or later
* SumUp SDK ensures support for
* `targetSDK` 31 or later
* AGP 7.3.0 or later
* Kotlin version 1.7.21 or later
* Java 11 and later
## Getting a test account
[Section titled “Getting a test account”](#getting-a-test-account)
To start testing SumUp APIs and tools without involving real money, you need to have a test account. You can create a test account from your account in the Dashboard as shown below.
1. Log in to your SumUp account.
2. Open the drop-down menu between Support and your user panel.
3. Select Test Account. Your merchant account is now switched to test mode.
A screenshot of the account selection dropdown in the SumUp dashboard with the test account highlighted with red circle
Once you have your test account you can begin making API calls with real data. Our test accounts **do not** process transactions with real funds. Test account has a different ID, and shows a clear warning. When you try to process a request with the value of 11 (in any currency), the test account will always fail - this is by design, to enable testing failed transactions.
A screenshot of the dashboard with test account selected
When you’re done experimenting with the test account, switch back to a regular account for business purposes.
## Compatibility
[Section titled “Compatibility”](#compatibility)
Starting with firmware version 1.0.1.84, Air card readers with serial numbers starting with 108, 109 or later require SDK version 4.0.0 and later. Please update to the latest SDK version if you need to support these readers.
## Integrate the SumUp SDK
[Section titled “Integrate the SumUp SDK”](#integrate-the-sumup-sdk)
You can use the sample app provided in the repository as a reference.
### Adding Dependencies
[Section titled “Adding Dependencies”](#adding-dependencies)
1. Add the SumUp maven repository to your Gradle project dependencies build file:
```groovy
1
allprojects {
2
repositories {
3
maven { url 'https://maven.sumup.com/releases' }
4
}
5
}
```
2. Add the SDK dependency to your app module build file:
```groovy
1
implementation 'com.sumup:merchant-sdk:5.0.3'
```
3. Sync your project.
### Initializing SumUp Components
[Section titled “Initializing SumUp Components”](#initializing-sumup-components)
Initialize the SumUp components in your app:
```java
1
public class SampleApplication extends Application {
2
3
@Override
4
public void onCreate() {
5
super.onCreate();
6
SumUpState.init(this);
7
}
8
}
```
### Logging Merchant In and Out
[Section titled “Logging Merchant In and Out”](#logging-merchant-in-and-out)
Before calling any features of the SumUp SDK, a registered SumUp merchant account needs to be logged in. Use the Affiliate Key by entering the application ID of your app. (e.g. com.sumup.sdksampleapp)
```java
1
SumUpLogin sumupLogin = SumUpLogin.builder(mAffiliateKey).build();
2
SumUpAPI.openLoginActivity(MainActivity.this, sumupLogin, 1);
```
Login screen
Note
It is also possible to login an account with a token, without the user entering their SumUp login credentials in the SDK. Please refer to section [Transparent Authentication](#transparent-authentication)
To log Merchant out, call:
```java
1
SumUpAPI.logout();
```
### Making Payments
[Section titled “Making Payments”](#making-payments)
Once logged in, you can start using the SumUp SDK to accept card payments. If no account is logged in, `SumUpAPI.Response.ResultCode.ERROR_NOT_LOGGED_IN` will be returned.
```java
1
SumUpPayment payment = SumUpPayment.builder()
2
// mandatory parameters
3
.total(new BigDecimal("1.12")) // minimum 1.00
4
.currency(SumUpPayment.Currency.EUR)
5
// optional: to be used only if the card reader supports the feature, what can be checked with `SumUpApi.isTipOnCardReaderAvailable()`
6
.tipOnCardReader()
7
// optional: include a tip amount in addition to the total, ignored if `tipOnCardReader()` is present
8
.tip(new BigDecimal("0.10"))
9
// optional: add details
10
.title("Taxi Ride")
11
.receiptEmail("customer@mail.com")
12
.receiptSMS("+3531234567890")
13
// optional: Add metadata
14
.addAdditionalInfo("AccountId", "taxi0334")
15
.addAdditionalInfo("From", "Paris")
16
.addAdditionalInfo("To", "Berlin")
17
// optional: foreign transaction ID, must be unique!
18
.foreignTransactionId(UUID.randomUUID().toString()) // can not exceed 128 chars
19
// optional: skip the success screen
20
.skipSuccessScreen()
21
// optional: skip the failed screen
22
.skipFailedScreen()
23
.build();
24
25
SumUpAPI.checkout(MainActivity.this, payment, 2);
```
Payment screen
### Handling Payment Result
[Section titled “Handling Payment Result”](#handling-payment-result)
```java
1
@Override
2
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
3
if (requestCode == 2 && data != null) {
4
// Handle the response here
5
}
6
}
```
### Connecting Reader
[Section titled “Connecting Reader”](#connecting-reader)
## Additional Features
[Section titled “Additional Features”](#additional-features)
### Response Fields
[Section titled “Response Fields”](#response-fields)
Several response fields are available when the callback activity is called:
| Property | Type | Description / Possible Values |
| ----------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **SumUpAPI.Response.RESULT\_CODE** | int | Possible Values: - SUCCESSFUL = 1 - ERROR\_TRANSACTION\_FAILED = 2 - ERROR\_GEOLOCATION\_REQUIRED = 3 - ERROR\_INVALID\_PARAM = 4 - ERROR\_INVALID\_TOKEN = 5 - ERROR\_NO\_CONNECTIVITY = 6 - ERROR\_PERMISSION\_DENIED = 7 - ERROR\_NOT\_LOGGED\_IN = 8 - ERROR\_DUPLICATE\_FOREIGN\_TX\_ID = 9 - ERROR\_INVALID\_AFFILIATE\_KEY = 10 - ERROR\_ALREADY\_LOGGED\_IN = 11 - ERROR\_INVALID\_AMOUNT\_DECIMALS = 12 - ERROR\_API\_LEVEL\_TOO\_LOW = 13 - ERROR\_CARD\_READER\_SETTINGS\_OFF = 14 - ERROR\_UNKNOWN\_TRANSACTION\_STATUS = 15 |
| **SumUpAPI.Response.MESSAGE** | String | A human readable message describing the result of the payment |
| **SumUpAPI.Response.TX\_CODE** | String | The transaction code associated with the payment |
| **SumUpAPI.Response.TX\_INFO** | Parcelable (com.sumup.merchant.Models.TransactionInfo) | Transaction info object containing information about the transaction: - Transaction Code - Merchant Code - Amount (including tip amount and VAT) - Tip amount - VAT - Currency (e.g. EUR) - Payment Status (PENDING \| SUCCESSFUL \| CANCELLED \| FAILED) - Payment Type (CASH \| POS \| ECOM \| UNKNOWN \| RECURRING \| BITCOIN \| BALANCE) - Entry Mode (e.g. CHIP) - Number of Installments - Card Type (e.g. MASTERCARD) - Last four digits of the card - Product information |
| **SumUpAPI.Response.RECEIPT\_SENT** | boolean | true if a receipt was issued to the customer, false otherwise |
The response flags are provided within the Bundle that is passed back to the callback activity:
```java
1
int resultCode = getIntent().getExtras().getInt(SumUpAPI.Response.RESULT_CODE);
```
### Card Reader Page
[Section titled “Card Reader Page”](#card-reader-page)
When a merchant is logged in, you can open this activity to access all the settings and options related to the card reader.
* This activity mainly offers
* To be able to connect to a new card reader.
* To be able to see the reader attributes when previously connected i.e. Battery percentage, Serial number, Last three digits of serial number, Software version.
* Connect to the last saved reader if it is inactive.
* Update firmware of the reader if available.
* Visual illustration of the saved reader with it’s current connectivity status and name.
```java
1
SumUpAPI.openCardReaderPage(MainActivity.this, 4);
```
Card Reader Page
### Preparing the SumUp Card Terminal for Checkout
[Section titled “Preparing the SumUp Card Terminal for Checkout”](#preparing-the-sumup-card-terminal-for-checkout)
`prepareForCheckout()` offers the possibility to connect the card reader ahead of initiating the checkout which speeds up the overall checkout time.
To call this method, user needs to be logged in with a SumUp account and their card reader should already be setup. Next, call `prepareForCheckout()` before initiating a checkout.
```java
1
SumUpAPI.prepareForCheckout()
```
> Note: Air and Solo card readers remain connected via BLE after each transaction while `prepareForCheckout()` is used when the card reader becomes disconnected (e.g. the reader is out of range, the host app looses focus, or the reader is turned off).
### Additional Checkout Parameters
[Section titled “Additional Checkout Parameters”](#additional-checkout-parameters)
When setting up the `SumUpPayment` object, the following optional parameters can be included:
#### Tip amount
[Section titled “Tip amount”](#tip-amount)
A tip amount can be processed in addition to the `total` using the `tip` parameter. The tip amount will then be shown during the checkout process and be included in the response. Please note that a tip amount cannot be changed during/after the checkout.
##### Tip on card reader
[Section titled “Tip on card reader”](#tip-on-card-reader)
This allows the customer to add a tip directly on the card reader, rather than prompting for a tip amount on the Android device.
A tip amount can be prompted directly in the card reader by using `tipOnCardReader` parameter, if the card reader supports tipping. See example [here](https://github.com/sumup/sumup-android-sdk#4-make-a-payment) for the field `tipOnCardReader`.
Note
Not all card readers support this feature. To find out if the feature is supported for the last-saved card reader, you should always check `SumUpApi.isTipOnCardReaderAvailable()`. You must handle this case yourself in order to avoid no tip from being prompted. Please also note that if both `tip` and `tipOnCardReader` are called then only `tipOnCardReader` amount will be considered during checkout if available.
#### Retry Policy Configuration
[Section titled “Retry Policy Configuration”](#retry-policy-configuration)
The `configureRetryPolicy()` feature allows you to set custom retry parameters for transaction result retrieval, using `pollingInterval`, `maxWaitingTime`, and `disableBackButton`.
* Parameters: Both `pollingInterval` and `maxWaitingTime` should be provided in milliseconds, with default values of 2000 ms and 60000 ms, respectively. Setting `disableBackButton` to true disables the back button during retries.
* Timeout: If `maxWaitingTime` elapses with no result, the SDK returns `SumUpAPI.ResultCode.ERROR_UNKNOWN_TRANSACTION_STATUS`. Pressing the back button (if enabled) during retries will also trigger this error.
* Adjustments: If `pollingInterval` exceeds `maxWaitingTime`, `maxWaitingTime` will automatically be adjusted to match. Negative values for either parameter default to 0.
* Default: If `configureRetryPolicy()` is not used, the SDK defaults to returning `SumUpAPI.ResultCode.ERROR_TRANSACTION_FAILED`.
##### Querying the Transaction Status
[Section titled “Querying the Transaction Status”](#querying-the-transaction-status)
When using the SumUp payment as shown below:
```java
1
SumupPayment.builder()
2
...
3
.foreignTransactionId(UUID.randomUUID().toString())
4
.configureRetryPolicy(2000, 60000, true)
5
.build();
```
If there are connectivity issues and the transaction status can not be retrieved, the API will return `ERROR_UNKNOWN_TRANSACTION_STATUS`. In such cases, you can query the transaction status by calling [SumUp transaction status API](https://developer.sumup.com/api/transactions/get) using the specified `foreignTransactionId`.
#### Transaction identifier
[Section titled “Transaction identifier”](#transaction-identifier)
The `foreignTransactionID` identifier will be associated with the transaction and can be used to retrieve details related to the transaction. See [API documentation](https://developer.sumup.com/rest-api/#tag/Transactions) for details. Please make sure that this ID is unique within the scope of the SumUp merchant account and sub-accounts. It must not be longer than 128 characters. The foreignTransactionID is available when the callback activity is called: `SumUpAPI.Param.FOREIGN_TRANSACTION_ID`
#### Skip success screen
[Section titled “Skip success screen”](#skip-success-screen)
To skip the success screen shown at the end of a successful transaction, the `skipSuccessScreen` parameter can be used. When using this parameter, your application is responsible for displaying the transaction result to the customer. In combination with the Receipts API your application can also send your own receipts, see [API documentation](https://developer.sumup.com/rest-api/#tag/Receipts) for details. Please note success screens will still be shown when using the SumUp Air Lite readers.
#### Skip failed screen
[Section titled “Skip failed screen”](#skip-failed-screen)
To skip the failed screen shown at the end of a failed transaction, the `skipFailedScreen` parameter can be used. When using this parameter your application is responsible for displaying the transaction result to the customer. Please note failed screens will still be shown when using the SumUp Air Lite readers.
### Transparent Authentication
[Section titled “Transparent Authentication”](#transparent-authentication)
To authenticate an account without the user typing in their SumUp credentials each time, you can generate an access token using OAuth2.0 and use it to transparently login to the SumUp SDK.
```java
1
SumUpLogin sumupLogin = SumUpLogin.builder(mAffiliateKey).accessToken("MY_ACCESS_TOKEN").build();
2
SumUpAPI.openLoginActivity(MainActivity.this, sumupLogin, 1);
```
For information about how to obtain a token, please see the [Authorization Documentation](/tools/api/authorization).
If the token is invalid, `SumUpAPI.Response.ResultCode.ERROR_INVALID_TOKEN` is returned.
### Retrieve Data of the Active Merchant Account
[Section titled “Retrieve Data of the Active Merchant Account”](#retrieve-data-of-the-active-merchant-account)
If a merchant account is currently logged in, it is possible to retrieve the data for this account.
```java
1
if (!SumUpAPI.isLoggedIn()) {
2
// no merchant account currently logged in
3
} else {
4
Merchant currentMerchant = SumUpAPI.getCurrentMerchant();
5
}
```
### Enable ProGuard
[Section titled “Enable ProGuard”](#enable-proguard)
```groovy
1
buildTypes {
2
release {
3
// All ProGuard rules required by the SumUp SDK are packaged with the library
4
minifyEnabled true
5
proguardFiles getDefaultProguardFile('proguard-android.txt')
6
}
7
}
```
### Use Google Location Services
[Section titled “Use Google Location Services”](#use-google-location-services)
The SDK supports Google Location Services, to improve location accuracy and reduce power consumption.
In order to use it you need to add the dependency in `build.gradle` file
```groovy
1
implementation "com.google.android.gms:play-services-location:19.0.1"
```
If the GLS dependency is not added to the project or Google Play Services are not installed on the mobile device, the SumUp SDK will determine the location with the default Location Service provided by Android.
Note
Using GLS version 19.0.1 is recommended.
## Sample App
[Section titled “Sample App”](#sample-app)
SumUp provides a sample app which implements main SDK components. You can find the app under [App directory](https://github.com/sumup/sumup-android-sdk/tree/master/app) of the repository.
## Out of Scope
[Section titled “Out of Scope”](#out-of-scope)
The following functions are handled by the [SumUp APIs](/api/):
* [Refunds](/api/transactions/refund/)
* [Transaction history](/api/transactions/list/)
* [Receipts](/api/receipts/get/)
* [Account management](/api/merchant/)
* [Online Payments](/online-payments/)
## Community
[Section titled “Community”](#community)
* **Questions?** Get in contact with our integration team by sending an email to [](mailto:integration@sumup.com).
* **Found a bug?** [Open an issue](https://github.com/sumup/sumup-android-sdk/issues/new). Please provide as much information as possible.
## Changelog
[Section titled “Changelog”](#changelog)
See [SumUp Changelog](/changelog/).
## License
[Section titled “License”](#license)
See [SumUp Android SDK License](https://github.com/sumup/Android-MerchantSDK/blob/master/LICENSE.md).
# Android Tap-to-Pay SDK
> Integrate with Android Tap to Pay SDK to process contactless payments on a phone.
## About Tap to Pay on Android SDK
[Section titled “About Tap to Pay on Android SDK”](#about-tap-to-pay-on-android-sdk)
Tap to Pay on Android SDK enables your mobile app to accept card-present contactless payments with a smartphone only, without the need for any additional hardware. This guide explains how you can integrate this functionality into your Android mobile app.
* Used for live, customer-facing operations.
* The SDK is not debuggable. Additionally, **Attestation & Monitoring** is enabled. If a device doesn’t meet our threat policy (for example, if debug mode is enabled or the device is rooted) then payment operations will not be available.
* For testing purposes, use dedicated developer credentials to prevent actual card charges. You can request access by contacting .
* For latest information, please check the [Android Tap-to-Pay Changelog](/changelog/tap-to-pay).
### Prerequisites
[Section titled “Prerequisites”](#prerequisites)
* Kotlin version: 1.9.22 or later
* `minSDK`: 30 or later
* `targetSDK`/`compileSDK`: 34 or later
* Android Gradle Plugin: 7.3.0 or later
* Java 17 or later
* maven repository credentials (to access the SDK repository, can be requested by sending an email to ).
* a Secret API key, in case you don’t intend to use the OAuth2 authentication process. You can generate a Secret API key in the [SumUp Dashboard](https://developer.sumup.com/online-payments/introduction/authorization#api-keys).
* Access to Android Tap-to-Pay GitHub repository (can be requested by sending an email to ).
### Hardware Requirements
[Section titled “Hardware Requirements”](#hardware-requirements)
* NFC-enabled Android device (emulators are not supported)
* Android 11 or later
## Integration
[Section titled “Integration”](#integration)
You can use the sample app provided in the GitHub repository as a reference.
Note
If your app shuts down immediately upon start, try disconnecting your phone and launching the app from your phone and not your IDE.
### Dependencies
[Section titled “Dependencies”](#dependencies)
1. Add the following to the Gradle dependencies:
```kotlin
1
allprojects {
2
repositories {
3
maven {
4
url = uri("https://maven.sumup.com/releases")
5
}
6
maven {
7
url = uri("https://tap-to-pay-sdk.fleet.live.sumup.net/")
8
credentials {
9
username = "your_username" // The maven credentials are provided by SumUp
10
password = "your_password"
11
}
12
}
13
google()
14
mavenCentral()
15
}
16
}
```
2. Add the dependency to a module `build.gradle`:
Production dependency:
```kotlin
1
implementation("com.sumup.tap-to-pay:utopia-sdk:1.0.1")
```
Testing dependency:
```kotlin
1
implementation("com.sumup.tap-to-pay:utopia-sdk-dev-protected:1.0.1")
```
### Authentication
[Section titled “Authentication”](#authentication)
Tap to Pay on Android SDK uses the transparent authentication approach. It means that the SDK is not responsible for the authentication process. The authentication process is handled by the consuming app. The SDK provides the `init` [method](#1-initialization) with the `AuthTokenProvider` interface as a parameter. The `AuthTokenProvider` interface is responsible for providing the access token to the SDK.
```kotlin
1
interface AuthTokenProvider {
2
fun getAccessToken(): String
3
}
```
There are several ways for a consumer app to provide the access token to the SDK.
1. Using the OAuth2 [flow](https://developer.sumup.com/tools/authorization/authorization#integration-via-oauth-20): The consumer app can implement the OAuth2 flow to get the access token and provide it to the SDK. The SDK provides the `AuthTokenProvider` interface that should be implemented by the consumer app. The implementation of the `getAccessToken` method should return the access token. This way is preferable and recommended because it provides a more secure way to authenticate the user.
2. Using API Key: You can use an API Key as an auth token. Generate the key in the [SumUp Dashboard](https://developer.sumup.com/tools/authorization/authorization#create-api-key) and provide it to the SDK through `AuthTokenProvider.getAccessToken()` method.
> ⚠️ **Important:** The API keys should be stored securely and should not be hardcoded in the app. Instead, they should be stored in the secure storage and provided to the SDK when needed. Do not share your secret API keys in publicly accessible places such as GitHub repositories, client-side code, etc.
### Using API
[Section titled “Using API”](#using-api)
The `TapToPay` interface provides methods to interact with the SDK. To get an implementation of the `TapToPay` interface, call:
```kotlin
1
val tapToPay = TapToPayApiProvider.provide(applicationContext)
```
where `applicationContext` is the context of a consumer application.
The `TapToPay` interface has the following methods:
#### 1. Initialization
[Section titled “1. Initialization”](#1-initialization)
```kotlin
1
suspend fun init(authTokenProvider: AuthTokenProvider): Result
```
The `init` method initializes the session. The `AuthTokenProvider` interface is responsible for providing the access token to the SDK (see [here](#Authentication)). Please, note that the `init` method should be called only once during the app lifecycle. The `init` method should be called as soon as possible after the app starts.
The `init` function returns a `Result` object that can be either a `Result.Success` if the initialization was successful. The function can also return `Result.Failure` with one exception from the list of exceptions mentioned [here](#Exceptions).
#### 2. Start Payment
[Section titled “2. Start Payment”](#2-start-payment)
```kotlin
1
suspend fun startPayment(
2
checkoutData: CheckoutData,
3
skipSuccessScreen: Boolean
4
): Flow
```
The `startPayment` method initiates the payment process. It returns a `Flow` that emits `PaymentEvent` or throws an exception with an error message.
The list of possible events:
* `CardRequested` - the SDK is trying to detect a card, waiting for the cardholder to tap/present their card.
* `CardPresented` - a card is detected.
* `CVMRequested` - a CVM (Cardholder Verification Method) is requested. This event is fired when the card is detected and the SDK is waiting for the cardholder to enter the PIN.
* `CVMPresented` - a CVM was entered by the cardholder. This event is fired upon completion of the CVM regardless if it was successful or not.
* `TransactionDone(val paymentOutput: PaymentOutput)` - transaction was completed. `PaymentOutput` param is:
```kotlin
1
data class PaymentOutput(
2
val txCode: String,
3
val serverTransactionId: String,
4
val cardType: String? = null,
5
val lastFour: String? = null,
6
val merchantCode: String? = null,
7
val cardScheme: String? = null
8
)
```
* `TransactionFailed(val paymentOutput: PaymentOutput?, val tapToPayException: TapToPayException?)` - transaction failed. It might happen due to many reasons, like attestation error, backend error, card reader error, and so on. The full list of errors is described in the [Exceptions](#Exceptions) section. `PaymentOutput` param might be null if the transaction failed before reaching the backend.
* `TransactionCanceled(val paymentOutput: PaymentOutput?)` - transaction was cancelled by the user.
* `TransactionResultUnknown(val paymentOutput: PaymentOutput?)` - transaction result is unknown. This might happen on remote calls, when there is no response due to timeout.
* `PaymentFlowClosedSuccessfully(val paymentOutput: PaymentOutput?, val shouldDisplayReceipt: Boolean)` - after a successful transaction, users see the successful screen with two buttons: **Send receipt** and **Done**. Once the user clicks on any button, the screen closes and fires the `PaymentClosed` event.
##### Parameters
[Section titled “Parameters”](#parameters)
`checkoutData` - The checkout data object.
`skipSuccessScreen` - A boolean value that controls whether the user is redirected to a built-in success screen after a successful payment.
```kotlin
1
data class CheckoutData(
2
val totalAmount: Long,
3
val tipsAmount: Long?,
4
val vatAmount: Long?,
5
val clientUniqueTransactionId: String,
6
val customItems: List?,
7
val priceItems: List?,
8
val products: List?,
9
val processCardAs: ProcessCardAs?,
10
val affiliateData: AffiliateModel?
11
) : Serializable
```
Where:
* `totalAmount` - The amount expressed in the minor unit of the currency. Total amount includes tip amount and VAT amount.
* `tipsAmount` - The amount of tips expressed in the minor unit of the currency. Please, note that the tip amount is included in the total amount. Ignored if null.
* `vatAmount` - The amount of VAT expressed in the minor unit of the currency. Please, note that the VAT amount is included in the total amount. Ignored if null.
* `clientUniqueTransactionId` - This should be a unique identifier for the transaction. A random UUID is can be used.
* `customItems` - The list of custom items. Set null if not used.
* `priceItems` - The list of price items. Set null if not used.
* `products` - The list of product items. Set null if not used.
* `processCardAs` - The type of the card processing. The default value is `null`. The possible values are `ProcessCardAs.Credit(val instalments: Int)` and `ProcessCardAs.Debit`, where `instalments` is the number of instalments. This parameter is optional and only applicable to some markets, such as Brazil, where the card type selection and instalments are supported.
* `affiliateData` - The affiliate data refers to tracking and attributing transactions to specific affiliates, integrators, or referral sources.
**Note:** The amounts shall be provided in minor unit of the currency according to the list below.\
Currencies with exponent 2 : `AUD, BGN, BRL, CHF, CLP, COP, CZK, DKK, EUR, GBP, HRK, HUF, NOK, PEN, PLN, RON, SEK, USD`.
For example, an amount of `$12.34` corresponds to a value of `1234`, `$11.00` corresponds to a value of `1100`.
**Note 2:** Some currencies (Hungarian Forint `HUF`, Chilean Peso `CLP` and Colombian Peso `COP`) are displayed to the merchant and cardholder without minor unit of the currency but still require it.
For these specific currencies, the amount shall still be multiplied by 100 (exponent 2). For example, `Ft100` should be provided as `10000`.
The `AffiliateModel` data type has the following parameters:
```kotlin
1
data class AffiliateModel(
2
val key: String,
3
val foreignTransactionId: String? = null,
4
val tags: Map? = null
5
) : Serializable
```
Where:
* `key` - The primary identifier for the affiliate or integrator partner.
* `foreignTransactionId` - An optional reference to an external transaction ID (from the integrator’s system).
* `tags` - Flexible key-value pairs for additional metadata about the transaction or affiliate.
The required minimum to make the transaction looks like:
```kotlin
1
fun startPayment() {
2
tapToPay.startPayment(
3
checkoutData = CheckoutData(
4
totalAmount = 1234, // 12.34 EUR
5
clientUniqueTransactionId = "123",
6
tipsAmount = null,
7
vatAmount = null,
8
customItems = null,
9
priceItems = null,
10
processCardAs = null,
11
),
12
skipSuccessScreen = false
13
).collectLatest {
14
Log.d("Payment event: $it")
15
}
16
}
```
#### 3. Tear Down
[Section titled “3. Tear Down”](#3-tear-down)
```kotlin
1
suspend fun tearDown(): Result
```
The `tearDown` function logs out the user, cleans up keys and other sensitive data, and closes the session. The `tearDown` method should be called when the app is closed or when the user logs out. It returns a `Result` object that can be either a `Result.Success` if the teardown was successful or a `Result.Failure` if there was an error during the teardown.
#### Exceptions
[Section titled “Exceptions”](#exceptions)
The SDK may return a `Result.Failure` containing an exception when one of its methods is called. Every exception belongs to one of the base types. The base types are listed below, and each of these is further divided into more specific exception types.
* `CommonException` - These exceptions cover scenarios such as initialization issues, registration problems, authentication failures, and required updates, providing a consistent and predictable way to handle errors across the system.
* `NetworkException` - These exceptions represent network-related and communication errors encountered during SDK operation. They include issues such as interrupted connections, authentication problems, and server/client-side failures.
* `PaymentException` - These exceptions represent errors related to the payment transaction flow, covering everything from preprocessing to final charge attempts. They include issues such as invalid payment actions, timeouts, incorrect amounts, unsupported card technologies, and unexpected states during card reading.
* `PaymentPreparationException` - These exceptions relate to the preparation and availability of the payment process. They indicate failures such as the unavailability of the payment function, issues during kernel setup, missing security-related data, and general checkout failures. These errors typically occur before or at the start of a transaction and prevent it from proceeding.
* `AttestationException` - These exceptions represent errors related to the attestation process, which is crucial for ensuring the security and integrity of the payment environment. They include issues like enabled USB debugging, non secure device or network.
* `TapToPayException.Unknown` - The Unknown exception represents an internal error that cannot be exposed externally. It acts as a fallback for unexpected or unclassified issues that occur within the SDK, ensuring sensitive or implementation-specific details are not leaked.
#### Error Codes
[Section titled “Error Codes”](#error-codes)
| **Base Type** | **Exception Type** | **Error Code** | **Description** |
| ------------------------------- | --------------------------- | -------------- | --------------------------------------------------------- |
| **CommonException** | Parsing | 101 | Error occurred during parsing. |
| | Environment | 102 | Environment-related issue. |
| | NotRegisteredTerminal | 103 | Terminal is not registered. |
| | AuthTokenProvider | 105 | Authentication token issue. |
| | Update | 106 | Update is required. |
| | SDKIsAlreadyInitialized | 107 | SDK is already initialized. |
| | SDKIsNotInitialized | 108 | SDK is not initialized. |
| | SDKTearDown | 109 | SDK teardown process. |
| | TerminalRegistration | 110 | Terminal registration issue. |
| | MissingResult | 111 | Missing result error. |
| **NetworkException** | NetworkConnection | 201 | General network error. |
| | Authentication | 202 | Authentication failure. |
| | Server | 204 | Server-related issue. |
| | Client | 205 | Client-related issue. |
| | NetworkSecurity | 206 | Secure network (mTLS) issue. |
| **PaymentException** | InvalidPaymentAction | 1001 | Invalid payment action. |
| | UncertainTransaction | 1002 | Transaction status is uncertain. |
| | Timeout | 1003 | Payment process timed out. |
| | Preprocessing | 1005 | Error during preprocessing. |
| | CombinationSelection | 1006 | Error in combination selection. |
| | Transaction | 1007 | Transaction-related issue. |
| | ExtractPAN | 1008 | Error extracting PAN. |
| | UnknownCVM | 1009 | Unknown Cardholder Verification Method. |
| | IncorrectAmount | 1010 | Incorrect amount specified. |
| | UnsupportedCardTechnology | 1011 | Unsupported card technology. |
| | UnexpectedCardReadState | 1012 | Unexpected card read state. |
| | UnexpectedOutcome | 1013 | Unexpected transaction outcome. |
| | IncorrectFormat | 1014 | Card read process failed. |
| | ReadEMVTagsException | 1015 | Error reading EMV tags. |
| | TechnoPollingStopped | 1016 | Techno polling process stopped. |
| | CancelationFailed | 1017 | Cancelation process failed. |
| | ChargeFailed | 1018 | Charge process failed. |
| | UnsupportedOnlinePin | 1020 | Unsupported online PIN. |
| | UnsupportedSignatureRequest | 1021 | Unsupported signature request. |
| | ErrorAction | 1022 | Error in payment action. |
| | TransactionInterrupted | 1023 | Transaction was interrupted. |
| | CardReadFailed | 1024 | Card read failed. |
| | DeclinedOutcome | 1025 | Card declined. |
| | EmptyCandidatesList | 1026 | No candidates available. |
| | UnknownKernel | 1027 | Unknown kernel error. |
| **PaymentPreparationException** | PaymentAvailability | 1101 | Payment availability issue. |
| | KernelPreparation | 1102 | Error during kernel preparation. |
| | EmptyAntireplayData | 1103 | Antireplay data is empty. |
| | CheckoutFailed | 1104 | Checkout process failed. |
| **AttestationException** | UsbDebuggingEnabled | 301 | USB debugging enabled. Disable USB debugging. |
| | AppDebuggable | 302 | App is build as debuggable. Rebuild it as non debuggable. |
| | AdbSessionActive | 303 | There is an active ADB session. |
| | DeviceSecurity | 305 | The device is not secure. |
| | NetworkSecurity | 304 | The network is not secure. |
| **TapToPayException** | Unknown | 0 | An internal error that cannot be exposed externally |
### Testing the SDK
[Section titled “Testing the SDK”](#testing-the-sdk)
Before testing in production, make sure of the following:
1. The app is not debuggable. Making the build debuggable will cause the attestation to fail and the payments will not work.
```kotlin
1
buildTypes {
2
release {
3
isDebuggable = false
4
}
5
}
```
2. You have USB debugging disabled on your device. Even if you install the app through a cable, disable the USB debugging after installation.
3. You have Developer Mode disabled on your device. Even if you install the app through a cable, disable the Developer Mode after installation.
On some devices (e.g. Samsung), you still have to disable USB debugging before disabling the Developer Mode. It is still possible to have a USB debugging enabled and Developer Mode disabled, but it depends on the device manufacturer.
### Testing in Specific Regions
[Section titled “Testing in Specific Regions”](#testing-in-specific-regions)
#### Brazil and Chile
[Section titled “Brazil and Chile”](#brazil-and-chile)
To test Tap to Pay on Android in Brazil and Chile, you should set `processCardAs` for each transaction. For example:
```kotlin
1
tapToPay.startPayment(
2
CheckoutData(
3
totalAmount = amount,
4
clientUniqueTransactionId = UUID.randomUUID().toString(),
5
tipsAmount = null,
6
vatAmount = null,
7
customItems = null,
8
products = null,
9
priceItems = null,
10
processCardAs = ProcessCardAs.Credit(instalments = 5), // or ProcessCardAs.Debit
11
affiliateData = null
12
)
13
)
```
Additionally, each transaction in Brazil and Chile should be verified by PIN. However, the PIN entry screen will appear only if *Developer Options* are *disabled* on the device - otherwise, the transaction will fail with an error.
# iOS SDK
> Explains how the iOS SDK works, required setup, and how it delivers card-present and Tap to Pay experiences.
## About SumUp iOS SDK
[Section titled “About SumUp iOS SDK”](#about-sumup-ios-sdk)
SumUp provides a [native iOS SDK](https://github.com/sumup/sumup-ios-sdk) that enables you to integrate SumUp’s proprietary card terminal(s) and its payment platform to accept credit and debit card payments (incl. VISA, MasterCard, American Express and more) as well as Tap-to-Pay payments on iPhones. SumUp’s SDK communicates transparently to the card terminal(s) via Bluetooth. Upon initiating a checkout, the SDK guides your user using appropriate screens through each step of the payment process. As part of the process, SumUp also provides the card terminal setup screen, along with the cardholder signature verification screen. The checkout result is returned with the relevant data for your records.
No sensitive card data is ever passed through to or stored on the merchant’s phone. All data is encrypted by the card terminal, which has been fully certified to the highest industry standards (PCI, EMV I & II, Visa, MasterCard & Amex).
SumUp iOS SDK is provided as an Objective C binary. However, when you use the SDK in Swift projects, Xcode uses automatic bridging to generate Swift-friendly interfaces from the Objective-C headers. For that reason, code samples in this guide are provided both in Swift and Objective C.
The iOS SDK includes a [Sample App](https://github.com/sumup/sumup-ios-sdk/tree/master/SampleApp/SumUpSDKSampleApp), which you can run out-of-the-box to immediately test the implementation in practice.
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
* Registered for a merchant account via SumUp’s [country websites](https://sumup.com/) (or created a test account).
* Received SumUp card terminal: Solo Lite, Solo, Air, 3G, PIN+.
* Requested an Affiliate (Access) Key via [SumUp Dashboard](https://me.sumup.com/developers) for Developers.
* Deployment Target iOS 14.0 or later.
* Recommended to use on Xcode 14.3.1 and iOS SDK 16 or later.
* iPhone or iPad.
* If your device is managed by an organization, make sure app installation is permitted.
## Getting a test account
[Section titled “Getting a test account”](#getting-a-test-account)
To start testing SumUp APIs and tools without involving real money, you need to have a test account. You can create a test account from your account in the Dashboard as shown below.
1. Log in to your SumUp account.
2. Open the drop-down menu between Support and your user panel.
3. Select Test Account. Your merchant account is now switched to test mode.
A screenshot of the account selection dropdown in the SumUp dashboard with the test account highlighted with red circle
Once you have your test account you can begin making API calls with real data. Our test accounts **do not** process transactions with real funds. Test account has a different ID, and shows a clear warning. When you try to process a request with the value of 11 (in any currency), the test account will always fail - this is by design, to enable testing failed transactions.
A screenshot of the dashboard with test account selected
When you’re done experimenting with the test account, switch back to a regular account for business purposes.
### Compatibility
[Section titled “Compatibility”](#compatibility)
* From version 4.4.0 of the SDK, iOS 14 or later is required
* The SDK supports all device orientations on iPad and portrait on iPhone. Feel free to support other orientations on iPhone but please keep in mind that the SDK’s UI will be presented in portrait on iPhone. See `UISupportedInterfaceOrientations` in the sample app’s `Info.plist` or the “General” tab in Xcode’s Target Editor.
### Match Affiliate Key to App Bundle ID
[Section titled “Match Affiliate Key to App Bundle ID”](#match-affiliate-key-to-app-bundle-id)
iOS SDK uses the Affiliate Key from your merchant account to authenticate your app.
1. Log in to SumUp with your merchant account and open the [Affiliate Key page](https://developer.sumup.com/affiliate-keys).
2. Create an Affiliate Key if you don’t have one yet.
3. Add your app’s *Bundle ID* in the SumUp portal’s *Application ID* field. This way, your app will be able to call SumUp APIs, which require the Affiliate Key.
### Add Property List Keys to Project
[Section titled “Add Property List Keys to Project”](#add-property-list-keys-to-project)
The SumUp iOS SDK requires access to the user’s location and Bluetooth peripherals. If your app has not asked for the user’s permission, the SumUp iOS SDK will ask at the time of the first login or checkout attempt. Please add the following keys to your `info.plist` file and set some values:
```txt
1
NSLocationWhenInUseUsageDescription
2
NSBluetoothAlwaysUsageDescription
3
NSBluetoothPeripheralUsageDescription (unless your deployment target is at least iOS 13)
```
Check the [Sample App property list](https://github.com/sumup/sumup-ios-sdk/tree/master/SampleApp/SumUpSDKSampleApp/SumUpSDKSampleApp-Info.plist) for reference.
Note
You can provide localization by providing a localized [InfoPlist.strings](https://github.com/sumup/sumup-ios-sdk/tree/master/SampleApp/SumUpSDKSampleApp/en.lproj/InfoPlist.strings) file.
```txt
1
/* Localized versions of Info.plist keys */
2
3
"NSLocationWhenInUseUsageDescription" = "To provide a secure payment service, we need to know your location.\nWithout location information, you cannot accept payments using this app.";
4
5
"NSBluetoothPeripheralUsageDescription" = "The app needs to connect to Bluetooth peripherals to detect the SumUp Card Terminal correctly. Please confirm with \"OK\" as you cannot use your card reader otherwise.";
6
7
"NSBluetoothAlwaysUsageDescription" = "The app needs to connect to Bluetooth peripherals to detect the SumUp Card Terminal correctly. Please confirm with \"OK\" as you cannot use your card reader otherwise.";
```
For further information, see the iOS Developer Library on [location usage on iOS 8 and later](https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW26), [Bluetooth peripheral usage](https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW20).
## Fast-track Implementation
[Section titled “Fast-track Implementation”](#fast-track-implementation)
If you want to dive straight into implementation, carry out the following steps:
### Card Reader Flow
[Section titled “Card Reader Flow”](#card-reader-flow)
1. [Install the SDK](#installing-and-setting-up-ios-sdk).
2. [Import the SDK into your project file](#importing-the-sdk).
3. [Initialize the SDK with an Affiliate Key](#initialization).
4. [Log the user in](#logging-the-user-in).
5. [Prepare user’s device for checkout](#prepare-for-checkout).
6. [Allow the user to select a card reader](#present-checkout-preferences).
7. Finally, [implement the full checkout](#implement-full-checkout).
### Tap-to-Pay Flow
[Section titled “Tap-to-Pay Flow”](#tap-to-pay-flow)
Please consider the following when building Tap-to-Pay solutions, as Apple reviews them with high scrutiny:
* Follow the [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/tap-to-pay-on-iphone) to save time when Apple reviews your app.
* Also consider [Apple’s marketing guidelines](https://developer.apple.com/tap-to-pay/marketing-guidelines/) and use standard assets where possible.
1. [Install the SDK](#installing-and-setting-up-ios-sdk).
2. [Import the SDK into your project file](#importing-the-sdk).
3. [Initialize the SDK with an Affiliate Key](#initialization).
4. [Log the user in](#logging-the-user-in).
5. Follow steps under [Implementing Tap-to-Pay](#implementing-tap-to-pay).
## Integrating iOS SDK
[Section titled “Integrating iOS SDK”](#integrating-ios-sdk)
### Adding SDK Framework to Project
[Section titled “Adding SDK Framework to Project”](#adding-sdk-framework-to-project)
The SumUp iOS SDK is provided as an XCFramework `SumUpSDK.xcframework` that contains the headers and bundles containing resources such as images and localizations. You can add the SDK binary manually or use a package manager such as Swift Package Manager, Cocoapods, or Carthage. Please follow the relevant instructions below to prepare your project:
* Swift Package Manager
The latest Swift Package Manager version added support to [distribute binary frameworks as Swift Packages](https://developer.apple.com/documentation/swift_packages/distributing_binary_frameworks_as_swift_packages).
If you’re using Xcode 12.3 or later, this should work out of the box.
Unfortunately, Xcode 12 releases before that had an issue, (), that added the framework as a static library, not as an embedded dynamic framework.
Follow this workaround to manage SumUp iOS SDK versions via Swift PM in those cases:
1. Add the package dependency to the repository `https://github.com/sumup/sumup-ios-sdk` (*File > Swift Packages > Add Package Dependency…*) with the version `Up to Next Major: 4.0.0`
2. Leave the checkbox unchecked for the SumUpSDK at the integration popup (*Add Package to …:*)
3. From the Project Navigator, drag and drop the `SumUpSDK/Referenced Binaries/SumUpSDK.xcframework` to your Xcode project’s “Frameworks, Libraries, and Embedded Content” on the General settings tab.
4. Make sure the [required Info.plist keys](#add-property-list-keys-to-project) are present.
To learn more about adding Swift Package dependencies, please refer to the [official documentation](https://developer.apple.com/documentation/xcode/adding_package_dependencies_to_your_app).
* Use XCFramework directly
1. Drag and drop the `SumUpSDK.xcframework` to your Xcode project’s “Frameworks, Libraries, and Embedded Content” on the project General Settings tab.
2. Make sure the [required Info.plist keys](#add-property-list-keys-to-project) are present.
* Cocoapods
```ruby
1
target '' do
2
pod 'SumUpSDK', '~> 6.0'
3
end
```
* Carthage
Distributing XCFrameworks with the latest Carthage version (0.35.0) is not yet available. There is an open issue ([#2799](https://github.com/Carthage/Carthage/issues/2799)) to solve this. Once that issue is fixed, we expect Carthage to work again.
The SumUp iOS SDK can be integrated with Carthage by following the steps below:
1. Add the following line to your `Cartfile`:
```txt
1
github "sumup/sumup-ios-sdk"
```
2. Run `carthage update sumup-ios-sdk`
3. Drag and drop the `Carthage/Build/iOS/SumUpSDK.xcframework` to your Xcode project’s “Frameworks, Libraries, and Embedded Content” on the General settings tab.
4. Make sure the [required Info.plist keys](#add-property-list-keys-to-project) are present.
To learn more about setting up your project for Carthage, please refer to the [official documentation](https://github.com/Carthage/Carthage#if-youre-building-for-ios-tvos-or-watchos).
### Importing SDK
[Section titled “Importing SDK”](#importing-sdk)
To import the SDK in Objective-C source files, you can use `#import `. If module support is enabled in your project, you can use `@import SumUpSDK;` instead.
In Swift, use `import SumUpSDK`. You do not have to add any headers to your bridging header.
### Initialization
[Section titled “Initialization”](#initialization)
Before calling any additional feature of the SumUp iOS SDK, you are required to set up the SDK with your Affiliate Key. Call on the main thread. You may wish to defer calling `setupWithAPIKey:` until after app launch, as it requests the user’s location permission.
Login screen
* Swift
```swift
1
import SumUpSDK
2
import UIKit
3
4
@UIApplicationMain
5
class AppDelegate: UIResponder, UIApplicationDelegate {
6
var window: UIWindow?
7
8
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
9
10
/*
11
* This will setup the SumUpSDK.
12
*
13
* You might consider moving this to a later point in your application's lifecycle,
14
* as this will start updating for locations.
15
*
16
* Also remember to provide the necessary usage descriptions in your info.plist
17
* and to properly localize it, see the
18
* Add Property List Keys to Project section.
19
*
20
* Ensure to add the Bundle Identifier of your iOS app to your
21
* Affiliate Key's Application identifiers in the SumUp developer portal.
22
*/
23
SumUpSDK.setup(withAPIKey: "sup_afk_abcqwerty")
24
return true
25
}
26
27
}
```
* Objective-C
```objc
1
#import "SUSAppDelegate.h"
2
#import
3
4
@implementation SUSAppDelegate
5
6
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
7
/*
8
* This will setup the SumUpSDK.
9
*
10
* You might consider moving this to a later point in your application's lifecycle,
11
* as this will start updating for locations.
12
*
13
* Also remember to provide the necessary usage descriptions in your info.plist
14
* and to properly localize it, see the
15
* Add Property List Keys to Project section.
16
*
17
* Ensure to add the Bundle Identifier of your iOS app to your
18
* API Key's Application identifiers in the SumUp developer portal.
19
*/
20
[SMPSumUpSDK setupWithAPIKey:@"sup_afk_abcqwerty"];
21
return YES;
22
}
```
### Authentication - Component Definitions
[Section titled “Authentication - Component Definitions”](#authentication---component-definitions)
SumUp iOS SDK supports either the OAuth 2.0 Authorization Code Flow login with Access Token or a modally presented login from a View Controller (as you can see implemented in the Sample App). We strongly recommend the OAuth 2.0 approach for new integrations, due to support for MFA, better overall security, and possible deprecation of the View Controller in the future.
* Login Access Token (OAuth 2.0)
```objc
1
/**
2
* Logs in a merchant with an access token acquired via https://developer.sumup.com/docs/authorization/.
3
* You must implement the "Authorization code flow", the "Client credentials flow" is not supported.
4
* Make sure that no user is logged in already when calling this method.
5
*
6
* @param aToken a user-scoped access token
7
* @param block a completion block that will run after login has succeeded/failed
8
*/
9
+ (void)loginWithToken:(NSString *)aToken completion:(nullable SMPCompletionBlock)block;
```
* Login View Controller
```objc
1
/**
2
* Presents the login modally from the given view controller.
3
*
4
* The login is automatically dismissed if login was successful or cancelled by the user.
5
* If error is nil and success is NO, the user cancelled the login.
6
* Errors are handled internally and usually do not need any display to the user.
7
* Does nothing if merchant is already logged in (calls completion block with success=NO, error=nil).
8
*
9
* @param fromViewController The UIViewController instance from which the login should be presented modally.
10
* @param animated Pass YES to animate the transition.
11
* @param block The completion block is called after each login attempt.
12
*/
13
+ (void)presentLoginFromViewController:(UIViewController *)fromViewController
14
animated:(BOOL)animated
15
completionBlock:(nullable SMPCompletionBlock)block;
```
* Logout
```objc
1
/**
2
* Performs a logout of the current merchant and resets the remembered password.
3
*
4
* @param block The completion block is called once the logout has finished.
5
*/
6
+ (void)logoutWithCompletionBlock:(nullable SMPCompletionBlock)block;
```
### Implementing Authentication with OAuth 2.0
[Section titled “Implementing Authentication with OAuth 2.0”](#implementing-authentication-with-oauth-20)
SumUp can issue Access Tokens in accordance with the OAuth 2.0 Authorization Code Flow, which is our recommended authorization approach (Client Credentials Flow is not supported by this SDK). See the [Authorization Documentation](/tools/authorization/authorization#integration-via-oauth-20) for more details.
### Implementing Authentication with View Controller
[Section titled “Implementing Authentication with View Controller”](#implementing-authentication-with-view-controller)
If you want to use the View Controller embedded in the SDK, this section explains how to do it. Please note that OAuth 2.0 Authorization Code Flow is supported and recommended, and the View Controller may become deprecated in the future.
#### Logging the user in
[Section titled “Logging the user in”](#logging-the-user-in)
Following app authentication, a registered SumUp merchant account needs to be logged in. Present a login screen from your UIViewController:
Login screen
* Swift
```swift
1
private func presentLogin() {
2
// present login UI and wait for completion block to update button states
3
SumUpSDK.presentLogin(from: self, animated: true) { [weak self] (success: Bool, error: Error?) in
4
print("Did present login with success: \(success). Error: \(String(describing: error))")
5
6
guard error == nil else {
7
// errors are handled within the SDK, there should be no need
8
// for your app to display any error message
9
return
10
}
11
12
self?.updateCurrency()
13
self?.updateButtonStates()
14
}
15
}
```
* Objective C
```objc
1
- (IBAction)buttonLoginTapped:(id)sender {
2
[SMPSumUpSDK presentLoginFromViewController:self
3
animated:YES
4
completionBlock:^(BOOL success, NSError *error) {
5
if (error) {
6
// errors are handled within the SDK, there should be no need
7
// for your app to display any error message
8
}
9
10
[self updateButtonState];
11
}];
12
}
```
#### Logging the user out
[Section titled “Logging the user out”](#logging-the-user-out)
Similarly, you can log the user out.
* Swift
```swift
1
fileprivate func requestLogout() {
2
SumUpSDK.logout { [weak self] (success: Bool, error: Error?) in
3
print("Did log out with success: \(success). Error: \(String(describing: error))")
4
self?.updateButtonStates()
5
}
6
}
```
* Objective C
```objc
1
- (IBAction)buttonLogoutTapped:(id)sender {
2
[SMPSumUpSDK logoutWithCompletionBlock:^(BOOL success, NSError *error) {
3
[self updateButtonState];
4
}];
5
}
```
### Payment Checkout Definitions
[Section titled “Payment Checkout Definitions”](#payment-checkout-definitions)
* In order to prepare a SumUp card terminal for checkout, `prepareForCheckout` can be called in advance. A registered SumUp merchant account needs to be logged in, and the card terminal must already be setup. You should use this method to let the SDK know that the user is most likely starting a checkout attempt soon; for example when entering an amount or adding products to a shopping cart. This allows the SDK to take appropriate measures, like attempting to wake a connected card terminal.
* When logged in you can let merchants check and update their checkout preferences. Merchants can select their preferred card terminal and set up a new one if needed. The preferences available to a merchant depend on their respective account settings.
* Present Checkout View is the main checkout request definition.
Check these methods and included comments before moving on to implementation below.
* Prepare for Incoming Checkout
```objc
1
/**
2
* Can be called in advance when a checkout is imminent and a user is logged in.
3
* You should use this method to let the SDK know that the user is most likely starting a
4
* checkout attempt soon, e.g. when entering an amount or adding products to a shopping cart.
5
* This allows the SDK to take appropriate measures, like attempting to wake a connected card terminal.
6
*/
7
+ (void)prepareForCheckout;
```
* Present Checkout Preferences
```objc
1
/**
2
* Presenting checkout preferences allows the current merchant to configure the checkout options and
3
* change the card terminal. Merchants can also set up the terminal when applicable.
4
* Can only be called when a merchant is logged in and checkout is not in progress.
5
* The completion block will be executed once the preferences have been dismissed.
6
* The success parameter indicates whether the preferences have been presented.
7
* If not successful an error will be provided, see SMPSumUpSDKError.
8
*
9
* @param fromViewController The UIViewController instance from which the checkout should be presented modally.
10
* @param animated Pass YES to animate the transition.
11
* @param block The completion block is called after the view controller has been dismissed.
12
*/
13
+ (void)presentCheckoutPreferencesFromViewController:(UIViewController *)fromViewController
14
animated:(BOOL)animated
15
completion:(nullable SMPCompletionBlock)block;
```
* Present Checkout View
```objc
1
/**
2
* Presents a checkout view with all necessary steps to charge a customer.
3
*
4
* @param request The SMPCheckoutRequest encapsulates all transaction relevant data such as total amount, label, etc.
5
* @param controller The UIViewController instance from which the checkout should be presented modally.
6
* @param block The completion block will be called when the view will be dismissed.
7
*/
8
+ (void)checkoutWithRequest:(SMPCheckoutRequest *)request
9
fromViewController:(UIViewController *)controller
10
completion:(nullable SMPCheckoutCompletionBlock)block;
```
### Adding Payment Checkout View
[Section titled “Adding Payment Checkout View”](#adding-payment-checkout-view)
In this step, we implement the payment checkout.
#### Prepare for Checkout
[Section titled “Prepare for Checkout”](#prepare-for-checkout)
* Objective C
```objc
1
- (BOOL)textFieldShouldReturn:(UITextField *)textField {
2
if (textField == self.textFieldTotal) {
3
// we assume a checkout is imminent
4
// let the SDK know to e.g. wake a connected terminal
5
[SMPSumUpSDK prepareForCheckout];
6
7
[self.textFieldTitle becomeFirstResponder];
8
} else if ([SMPSumUpSDK isLoggedIn]) {
9
[self buttonChargeTapped:nil];
10
} else {
11
[textField resignFirstResponder];
12
}
13
14
return YES;
15
}
```
* Swift
```swift
1
extension ViewController: UITextFieldDelegate {
2
func textFieldShouldReturn(_ textField: UITextField) -> Bool {
3
if textField == textFieldTotal {
4
// we assume a checkout is imminent
5
// let the SDK know to e.g. wake a connected terminal
6
SumUpSDK.prepareForCheckout()
7
8
textFieldTitle?.becomeFirstResponder()
9
} else if SumUpSDK.isLoggedIn {
10
requestCheckout()
11
} else {
12
textField.resignFirstResponder()
13
}
14
15
return true
16
}
17
}
```
#### Present Checkout Preferences
[Section titled “Present Checkout Preferences”](#present-checkout-preferences)
Provides the user a way to search for nearby Bluetooth card readers and select one to be used. The selected card reader will be saved to `UserDefaults` and used for subsequent checkouts. Using this screen is optional. If a checkout is started but no card reader has been saved, the checkout itself will automatically present the screen to search for and select a card reader, and this will be saved for next time.
Search Bluetooth
Terminal selection
* Swift
```swift
1
private func presentCheckoutPreferences() {
2
SumUpSDK.presentCheckoutPreferences(from: self, animated: true) { [weak self] (success: Bool, presentationError: Error?) in
3
print("Did present checkout preferences with success: \(success). Error: \(String(describing: presentationError))")
4
5
guard let safeError = presentationError as NSError? else {
6
// no error, nothing else to do
7
return
8
}
9
10
print("error presenting checkout preferences: \(safeError)")
11
12
let errorMessage: String
13
switch (safeError.domain, safeError.code) {
14
case (SumUpSDKErrorDomain, SumUpSDKError.accountNotLoggedIn.rawValue):
15
errorMessage = "not logged in"
16
17
case (SumUpSDKErrorDomain, SumUpSDKError.checkoutInProgress.rawValue):
18
errorMessage = "checkout is in progress"
19
20
default:
21
errorMessage = "general error"
22
}
23
24
self?.showResult(string: errorMessage)
25
}
26
}
```
* Objective C
```objc
1
- (IBAction)buttonOpenPreferencesTapped:(id)sender {
2
[SMPSumUpSDK presentCheckoutPreferencesFromViewController:self
3
animated:YES
4
completion:^(BOOL success, NSError *_Nullable error) {
5
if (!success || error) {
6
[self showResultsString:@"not logged in"];
7
}
8
}];
9
}
```
#### Present Checkout View
[Section titled “Present Checkout View”](#present-checkout-view)
Prepare a checkout request that encapsulates the information regarding the transaction.
Checkout screen
* Swift
```swift
1
SumUpSDK.checkout(with: request, from: self) { [weak self] (result: CheckoutResult?, error: Error?) in
2
if let safeError = error as NSError? {
3
print("error during checkout: \(safeError)")
4
5
if (safeError.domain == SumUpSDKErrorDomain) && (safeError.code == SumUpSDKError.accountNotLoggedIn.rawValue) {
6
self?.showResult(string: "not logged in")
7
} else {
8
self?.showResult(string: "general error")
9
}
10
11
return
12
}
```
* Objective C
```objc
1
[SMPSumUpSDK checkoutWithRequest:request fromViewController:self completion:^(SMPCheckoutResult *result, NSError *error) {
2
if ([error.domain isEqualToString:SMPSumUpSDKErrorDomain] && (error.code == SMPSumUpSDKErrorAccountNotLoggedIn)) {
3
[self showResultsString:@"not logged in"];
4
return;
5
}
```
* Error codes Objective C
```objc
1
NS_SWIFT_NAME(SumUpSDKErrorDomain)
2
extern NSString * const SMPSumUpSDKErrorDomain;
3
/**
4
* The error codes returned from the SDK
5
*/
6
typedef NS_ENUM(NSInteger, SMPSumUpSDKError) {
7
/// General error
8
SMPSumUpSDKErrorGeneral = 0,
9
/// The merchant's account is not activated
10
SMPSumUpSDKErrorActivationNeeded = 1,
11
/// General error with the merchant's account
12
SMPSumUpSDKErrorAccountGeneral = 20,
13
/// The merchant is not logged in to their account
14
SMPSumUpSDKErrorAccountNotLoggedIn = 21,
15
/// A merchant is logged in already. Call logout before logging in again.
16
SMPSumUpSDKErrorAccountIsLoggedIn = 22,
17
/// Generel checkout error
18
SMPSumUpSDKErrorCheckoutGeneral = 50,
19
/// Another checkout process is currently in progress.
20
SMPSumUpSDKErrorCheckoutInProgress = 51,
21
/// The currency code specified in the checkout request does not match that of the current merchant.
22
SMPSumUpSDKErrorCheckoutCurrencyCodeMismatch = 52,
23
/// The foreign transaction ID specified in the checkout request has already been used.
24
SMPSumUpSDKErrorDuplicateForeignID = 53,
25
/// The access token is invalid. Login to get a valid access token.
26
SMPSumUpSDKErrorInvalidAccessToken = 54,
27
/// The amount entered contains invalid number of decimals.
28
SMPSumUpSDKErrorInvalidAmountDecimals = 55,
29
/// Tap to Pay on iPhone payment method is not available for the current merchant. This may be
30
/// because the payment method is not available in their country.
31
SMPSumUpSDKErrorTapToPayNotAvailable = 100,
32
/// Tap to Pay on iPhone: activation is required. Call `presentTapToPayActivationFromViewController:animated:completionBlock:`.
33
SMPSumUpSDKErrorTapToPayActivationNeeded = 101,
34
/// Tap to Pay on iPhone: an unspecified error occurred
35
SMPSumUpSDKErrorTapToPayInternalError = 102,
36
/// Tap to Pay on iPhone requires an iPhone XS or later and does not work on iPads.
37
SMPSumUpSDKErrorTapToPayMinHardwareNotMet = 103,
38
/// Tap to Pay on iPhone requires a newer version of iOS; please check the documentation for the
39
/// minimum supported version.
40
SMPSumUpSDKErrorTapToPayiOSVersionTooOld = 104,
41
/// Tap to Pay on iPhone has some other (unspecified) requirement(s) that are not met.
42
SMPSumUpSDKErrorTapToPayRequirementsNotMet = 105,
43
} NS_SWIFT_NAME(SumUpSDKError);
```
* Error codes Swift
```swift
1
public enum SumUpSDKError : Int, @unchecked Sendable {
2
3
/// General error
4
case general = 0
5
6
/// The merchant's account is not activated
7
case activationNeeded = 1
8
9
/// General error with the merchant's account
10
case accountGeneral = 20
11
12
/// The merchant is not logged in to their account
13
case accountNotLoggedIn = 21
14
15
/// A merchant is logged in already. Call logout before logging in again.
16
case accountIsLoggedIn = 22
17
18
/// Generel checkout error
19
case checkoutGeneral = 50
20
21
/// Another checkout process is currently in progress.
22
case checkoutInProgress = 51
23
24
/// The currency code specified in the checkout request does not match that of the current merchant.
25
case checkoutCurrencyCodeMismatch = 52
26
27
/// The foreign transaction ID specified in the checkout request has already been used.
28
case duplicateForeignID = 53
29
30
/// The access token is invalid. Login to get a valid access token.
31
case invalidAccessToken = 54
32
33
/// The amount entered contains invalid number of decimals.
34
case invalidAmountDecimals = 55
35
36
/// Tap to Pay on iPhone payment method is not available for the current merchant. This may be
37
/// because the payment method is not available in their country.
38
case tapToPayNotAvailable = 100
39
40
/// Tap to Pay on iPhone: activation is required. Call `presentTapToPayActivationFromViewController:animated:completionBlock:`.
41
case tapToPayActivationNeeded = 101
42
43
/// Tap to Pay on iPhone: an unspecified error occurred
44
case tapToPayInternalError = 102
45
46
/// Tap to Pay on iPhone requires an iPhone XS or later and does not work on iPads.
47
case tapToPayMinHardwareNotMet = 103
48
49
/// Tap to Pay on iPhone requires a newer version of iOS; please check the documentation for the
50
/// minimum supported version.
51
case tapToPayiOSVersionTooOld = 104
52
53
/// Tap to Pay on iPhone has some other (unspecified) requirement(s) that are not met.
54
case tapToPayRequirementsNotMet = 105
55
}
```
### Handling Payment Checkout
[Section titled “Handling Payment Checkout”](#handling-payment-checkout)
Detailed information on the payment checkout.
#### Note on Tipping
[Section titled “Note on Tipping”](#note-on-tipping)
There are three modes for tipping:
1. No tipping. Leave `tipAmount` set to nil when creating the `SMPCheckoutRequest` object.
2. Programmatic tipping via the `tipAmount` property. Ask the user in your own UI for an appropriate tip amount and then set the `tipAmount` property on `SMPCheckoutRequest`. This will be added to the total amount, but will be displayed to the user separately during checkout.
3. Tip on Card Reader. TCR prompts the customer directly on the card reader’s display for a tip amount, rather than prompting for a tip amount on the iPhone or iPad display.
Caution
Not all card readers support this feature. To find out if the feature is supported for the last-used card reader, you should always check `SMPSumUpSDK.isTipOnCardReaderAvailable`. You must handle this case yourself in order to avoid no tip from being prompted. To do this:
Before calling `SMPSumUpSDK checkoutWithRequest:fromViewController:completion:`, check `SMPSumUpSDK.isTipOnCardReaderAvailable`:
* If NO, you should prompt the user for a tip amount yourself and set tipAmount on `SMPCheckoutRequest`
* If YES, you may set `tipOnCardReaderIfAvailable` on `SMPCheckoutRequest` to YES. Do not prompt the user for a tip amount or set tipAmount if you do this.
#### Definitions
[Section titled “Definitions”](#definitions)
You have an option to add the `paymentMethod` to checkout request, or skip it and let it default to Card Reader payment, as shown in the examples below. You can also familiarize yourself with the payment properties before moving on to implementation.
* Checkout Request with any Payment Method
```objc
1
/**
2
* Creates a new checkout request.
3
*
4
* Be careful when creating the NSDecimalNumber to not falsely use the NSNumber class creator methods.
5
*
6
* @param totalAmount The total amount to be charged to a customer. Cannot be nil.
7
* @param title An optional title to be displayed in the merchant's history and on customer receipts.
8
* @param currencyCode Currency Code in which the total should be charged (ISO 4217 code, see SMPCurrencyCode). Cannot be nil, has to match the currency of the merchant logged in. Use [[[SMPSumUpSDK currentMerchant] currencyCode] and ensure its length is not 0.
9
*
10
* @return A new request object or nil if totalAmount or currencyCode are nil.
11
*/
12
+ (SMPCheckoutRequest *)requestWithTotal:(NSDecimalNumber *)totalAmount
13
title:(nullable NSString *)title
14
currencyCode:(NSString *)currencyCode
15
paymentMethod:(SMPPaymentMethod)paymentMethod;
```
* Checkout Request with Card Reader Only
```objc
1
/**
2
* Creates a new checkout request using a card reader as the method of payment.
3
*
4
* Be careful when creating the NSDecimalNumber to not falsely use the NSNumber class creator methods.
5
*
6
* @param totalAmount The total amount to be charged to a customer. Cannot be nil.
7
* @param title An optional title to be displayed in the merchant's history and on customer receipts.
8
* @param currencyCode Currency Code in which the total should be charged (ISO 4217 code, see SMPCurrencyCode). Cannot be nil, has to match the currency of the merchant logged in. Use [[[SMPSumUpSDK currentMerchant] currencyCode] and ensure its length is not 0.
9
*
10
* @return A new request object or nil if totalAmount or currencyCode are nil.
11
*/
12
+ (SMPCheckoutRequest *)requestWithTotal:(NSDecimalNumber *)totalAmount
13
title:(nullable NSString *)title
14
currencyCode:(NSString *)currencyCode;
```
* Payment Properties
```objc
1
/**
2
* The total amount to be charged to a customer.
3
*
4
* @note Will not be nil if the instance was created using either
5
* requestWithTotal:title:currencyCode:paymentOptions: or
6
* requestWithTotal:title:currencyCode:
7
*/
8
@property (nonatomic, readonly, nullable) NSDecimalNumber *totalAmount;
9
10
/// A title to be displayed in the merchant's history and on customer receipts.
11
@property (nonatomic, readonly, nullable) NSString *title;
12
13
/**
14
* Currency code in which the total should be charged (ISO 4217 code, see SMPCurrencyCode).
15
*
16
* @note Will not be nil if the instance was created using either
17
* requestWithTotal:title:currencyCode:paymentOptions: or
18
* requestWithTotal:title:currencyCode:
19
*/
20
@property (nonatomic, readonly, nullable) NSString *currencyCode;
21
22
/**
23
* An (optional) ID to be associated with this transaction.
24
* See https://docs.sumup.com/rest-api/#tag/Transactions
25
* on how to retrieve a transaction using this ID.
26
* This ID has to be unique in the scope of a SumUp merchant account and its sub-accounts.
27
* It must not be longer than 128 characters and can only contain printable ASCII characters.
28
*/
29
@property (nonatomic, copy, nullable) NSString *foreignTransactionID;
30
31
/**
32
* An optional additional tip amount to be charged to a customer.
33
*
34
* @note This property will be ignored if the connected card reader supports the
35
* Tip on Card Reader (TCR) feature and if it is enabled by setting
36
* tipOnCardReaderIfAvailable to YES.
37
*
38
* Important: the customer may use a reader that does not support TCR.
39
* You must handle this case yourself in order to avoid no tip from being prompted.
40
*
41
* To do this:
42
*
43
* Before calling SMPSumUpSDK checkoutWithRequest:fromViewController:completion:,
44
* check SMPSumUpSDK.isTipOnCardReaderAvailable:
45
*
46
* - If NO, you should prompt the user for a tip amount yourself and set tipAmount
47
*
48
* - If YES, you may set tipOnCardReaderIfAvailable to YES.
49
* Do not prompt the user for a tip amount or set tipAmount if you do this.
50
*
51
* Will be added to the totalAmount. Must be greater than zero if set.
52
*/
53
@property (nonatomic, copy, nullable) NSDecimalNumber *tipAmount;
54
55
/**
56
* Enables Tip on Card Reader (TCR), if the feature is available.
57
*
58
* @note TCR prompts the customer directly on the card reader's display for a tip amount,
59
* rather than prompting for a tip amount on the iPhone or iPad display.
60
*
61
* Not all card readers support this feature. To find out if the feature is supported for the
62
* last-used card reader, check SMPSumUpSDK.isTipOnCardReaderAvailable.
63
*
64
* Setting this property to YES when the feature is not available will do nothing.
65
*/
66
@property (nonatomic) BOOL tipOnCardReaderIfAvailable;
67
68
/**
69
* An optional count for the display of the number of sale items throughout the checkout process.
70
* Default is zero which will hide the display of the item count.
71
* This value is currently not reflected in the merchant's history
72
* or the customer receipts.
73
*/
74
@property (nonatomic) NSUInteger saleItemsCount;
75
76
/**
77
* An optional flag to skip the confirmation screen in checkout.
78
* If set, the checkout will be dismissed w/o user interaction.
79
* Default is SMPSkipScreenOptionNone.
80
*/
81
@property (nonatomic) SMPSkipScreenOptions skipScreenOptions;
82
83
/**
84
* The method of payment to use during checkout; for example, a bluetooth-connected card reader, or Tap to Pay on iPhone.
85
*
86
* Defaults to `SMPPaymentMethodCardReader`.
87
*/
88
@property (nonatomic) SMPPaymentMethod paymentMethod;
```
#### Implement Full Checkout
[Section titled “Implement Full Checkout”](#implement-full-checkout)
In this step, we implement the checkout.
1. Verify that Merchant is logged in and using a valid currency code.
2. Define total amount to be charged. Please note that you need to pass an `NSDecimalNumber` as the total value. While `NSDecimalNumber` is a subclass of `NSNumber` it is not advised to use the convenience method of `NSNumber` to create an `NSDecimalNumber`.
3. Set up the request.
4. Add a tip if selected ([see the section about tipping](#tipping)).
5. Check if the option to skip receipt is enabled, if so, execute it.
6. Check for `foreignTransactionID`.
7. Execute the request with error handling and confirmation.
8. Verify that the checkout started correctly.
* Swift
```swift
1
fileprivate func requestCheckout() {
2
// ensure that we have a valid merchant
3
guard let merchantCurrencyCode = SumUpSDK.currentMerchant?.currencyCode else {
4
showResult(string: "not logged in")
5
return
6
}
7
8
guard let totalText = textFieldTotal?.text else {
9
return
10
}
11
12
// create an NSDecimalNumber from the totalText
13
// please be aware to not use NSDecimalNumber initializers inherited from NSNumber
14
let total = NSDecimalNumber(string: totalText)
15
guard total != NSDecimalNumber.zero else {
16
return
17
}
18
19
// setup payment request
20
let request = CheckoutRequest(total: total,
21
title: textFieldTitle?.text,
22
currencyCode: merchantCurrencyCode)
23
24
// add tip if selected
25
if let selectedTip = segmentedControlTipping?.selectedSegmentIndex,
26
selectedTip > 0,
27
tipAmounts.indices ~= selectedTip {
28
let tipAmount = tipAmounts[selectedTip]
29
request.tipAmount = tipAmount
30
}
31
32
// set screenOptions to skip if switch is set to on
33
if let skip = switchSkipReceiptScreen?.isOn, skip {
34
request.skipScreenOptions = .success
35
}
36
37
// the foreignTransactionID is an **optional** parameter and can be used
38
// to retrieve a transaction from SumUp's API. See -[SMPCheckoutRequest foreignTransactionID]
39
request.foreignTransactionID = "your-unique-identifier-\(ProcessInfo.processInfo.globallyUniqueString)"
40
41
SumUpSDK.checkout(with: request, from: self) { [weak self] (result: CheckoutResult?, error: Error?) in
42
if let safeError = error as NSError? {
43
print("error during checkout: \(safeError)")
44
45
if (safeError.domain == SumUpSDKErrorDomain) && (safeError.code == SumUpSDKError.accountNotLoggedIn.rawValue) {
46
self?.showResult(string: "not logged in")
47
} else {
48
self?.showResult(string: "general error")
49
}
50
51
return
52
}
53
54
guard let safeResult = result else {
55
print("no error and no result should not happen")
56
return
57
}
58
59
print("result_transaction==\(String(describing: safeResult.transactionCode))")
60
61
if safeResult.success {
62
print("success")
63
var message = "Thank you - \(String(describing: safeResult.transactionCode))"
64
65
if let info = safeResult.additionalInfo,
66
let tipAmount = info["tip_amount"] as? Double, tipAmount > 0,
67
let currencyCode = info["currency"] as? String {
68
message = message.appending("\ntip: \(tipAmount) \(currencyCode)")
69
}
70
71
self?.showResult(string: message)
72
} else {
73
print("cancelled: no error, no success")
74
self?.showResult(string: "No charge (cancelled)")
75
}
76
}
77
78
// after the checkout is initiated we expect a checkout to be in progress
79
if !SumUpSDK.checkoutInProgress {
80
// something went wrong: checkout was not started
81
showResult(string: "failed to start checkout")
82
}
83
}
```
* Objective C
```objc
1
- (IBAction)buttonChargeTapped:(id)sender {
2
// check total and currency code
3
NSString *total = [[self textFieldTotal] text];
4
NSString *currencyCode = [[SMPSumUpSDK currentMerchant] currencyCode];
5
6
if (([total doubleValue] <= 0) || ![currencyCode length]) {
7
[self showResultsString:@"not logged in"];
8
return;
9
}
10
11
SMPCheckoutRequest *request;
12
13
request = [SMPCheckoutRequest requestWithTotal:[NSDecimalNumber decimalNumberWithString:total]
14
title:self.textFieldTitle.text
15
currencyCode:currencyCode];
16
17
// Tip is optional. Default is no tip.
18
NSInteger selectedTipSegment = self.segmentedControlTipping.selectedSegmentIndex;
19
20
if (selectedTipSegment > 0) {
21
[request setTipAmount:[[self tipAmounts] objectAtIndex:selectedTipSegment]];
22
}
23
24
// Skip receipt screen if toggle is set to on
25
if (self.switchSkipReceiptScreen.isOn) {
26
[request setSkipScreenOptions:SMPSkipScreenOptionSuccess];
27
}
28
29
// the foreignTransactionID is an optional parameter and can be used
30
// to retrieve a transaction from SumUp's API. See -[SMPCheckoutRequest foreignTransactionID]
31
[request setForeignTransactionID:[NSString stringWithFormat:@"your-unique-identifier-%@", [[NSProcessInfo processInfo] globallyUniqueString]]];
32
33
[SMPSumUpSDK checkoutWithRequest:request fromViewController:self completion:^(SMPCheckoutResult *result, NSError *error) {
34
if ([error.domain isEqualToString:SMPSumUpSDKErrorDomain] && (error.code == SMPSumUpSDKErrorAccountNotLoggedIn)) {
35
[self showResultsString:@"not logged in"];
36
return;
37
}
38
39
NSMutableArray *strings = [NSMutableArray array];
40
[strings addObject:[NSString stringWithFormat:@"%@ - %@", result.success ? @"Thank you" : @"No charge", result.transactionCode ? : @"no transaction"]];
41
42
if (result.transactionCode) {
43
// get optional tip amount
44
NSNumber *tipAmount = result.additionalInfo[@"tip_amount"];
45
46
// display tip only if greater than zero
47
if ([tipAmount isKindOfClass:[NSNumber class]] && (tipAmount.doubleValue > 0)) {
48
[strings addObject:[NSString stringWithFormat:@"%@ (incl. %@ tip) %@", result.additionalInfo[@"amount"], tipAmount, result.additionalInfo[@"currency"]]];
49
} else {
50
[strings addObject:[NSString stringWithFormat:@"%@ %@ (no tip)", result.additionalInfo[@"amount"], result.additionalInfo[@"currency"]]];
51
}
52
}
53
54
[self showResultsString:[strings componentsJoinedByString:@"\n"]];
55
56
if (result.success) {
57
[self.textFieldTitle setText:nil];
58
}
59
}];
60
61
// something went wrong checkout was not started
62
if (![SMPSumUpSDK checkoutInProgress]) {
63
[self showResultsString:@"failed to start checkout"];
64
}
65
}
```
### Credit/debit selection (processAs property)
[Section titled “Credit/debit selection (processAs property)”](#creditdebit-selection-processas-property)
Some countries require the customer to select Credit or Debit at the beginning of the checkout. This is because a payment card may contain multiple applications linked with different accounts, making it necessary for the customer to specify which application should be used to process the transaction.
For countries that do not require credit/debit selection, you can set the `processAs` property of `SMPCheckoutRequest` to `SMPProcessAsNotSet`.
Caution
* For countries that require credit/debit selection, using `SMPProcessAsNotSet` will cause the transaction to fail.
* Not all countries support `processAs`. Setting `processAs` for unsupported countries may cause the transaction to fail. Currently supported countries are: Brazil, Chile and Colombia.
To tell if the current country requires `processAs` to be set to a value other than `SMPProcessAsNotSet`, check `SMPSumUpSDK.isProcessAsRequired`.
If needed, your app should set the `processAs` property of `SMPCheckoutRequest` to `SMPProcessAsCredit` or `SMPProcessAsDebit` after showing its own UI that prompts the customer to select Credit or Debit.
SDK 6.0 and earlier presented two screens during the checkout that prompted the user to select Credit or Debit, and if Credit, to also choose the number of installments. This functionality is now deprecated. However, it is still available if you need more time to migrate your app to use the above programmatic method. To keep the old behavior, set `processAs` to `SMPProcessAsPromptUser`.
#### Installments
[Section titled “Installments”](#installments)
When `SMPProcessAsCredit` is used, you should obtain the number of installments from the customer using your own UI. Assign the positive, non-zero value to `numberOfInstallments` on `SMPCheckoutRequest`.
### Implementing Tap-to-Pay
[Section titled “Implementing Tap-to-Pay”](#implementing-tap-to-pay)
With Tap to Pay on iPhone merchants can accept contactless card payments on their iPhone without needing a card reader.
To add Tap to Pay on iPhone to your app:
* Request the Tap to Pay on iPhone entitlement from Apple, receive approval, and then add the `com.apple.developer.proximity-reader.payment.acceptance` entitlement to your app. [Setting up the entitlement](https://developer.apple.com/documentation/proximityreader/setting-up-the-entitlement-for-tap-to-pay-on-iphone?language=objc).
* This feature requires an iPhone XS or later, running iOS 16.4 (iOS 16.7 starting July 8th) or later (ideally 17.5 or later.) The feature does not work on iPad.
* For debugging and testing you will need to be logged into an iPhone with a non-Sandbox Apple ID. Using a Sandbox Apple ID requires both Apple and SumUp implementations to connect to their respective non-production (test) backends, which the SDK does not support.
* **During testing use a SumUp test account**, to avoid transactions going to the acquirer and transferring real money.
In your code:
* Make a call to check feature availability: is the Tap to Pay on iPhone payment method available for the current merchant?
* Trigger activation if needed. Activation sets up the iPhone to receive payments, shows the merchant how to use the feature, and links the SumUp account and Apple ID.
* Start the checkout.
#### Check feature availability
[Section titled “Check feature availability”](#check-feature-availability)
* Call `checkTapToPayAvailability` on `SMPSumUpSDK` to check the availability of the Tap to Pay on iPhone payment method. This call, which requires the SDK to be in a logged-in state, may internally perform one or more network calls.
* If the feature is not available, your app could, as an example, hide or disable a button or menu item representing the Tap to Pay on iPhone payment method.
* The feature is generally available when the following criteria are fulfilled:
* the iPhone model and iOS version requirements are met
* the user logs in with a SumUp account registered in one of the countries where SumUp supports Tap to Pay on iPhone (temporarily with exception of Brazil)
#### Perform activation if needed
[Section titled “Perform activation if needed”](#perform-activation-if-needed)
* Activation must be completed before the first transaction can be performed. Activation means:
* the merchant links their Apple ID with their SumUp account
* the iPhone is prepared, which can take 45 seconds or longer
* This needs to be done once per merchant account, per device.
* In addition to determining feature availability, `checkTapToPayAvailability` also indicates whether Tap to Pay on iPhone has been activated yet for the current merchant.
* If it has not yet been activated then you should trigger activation by calling `presentTapToPayActivation` at a convenient time. Calling it more than once will still show the user education screens each time. Independently, the activation from the initial setup will remain valid.
#### Definitions
[Section titled “Definitions”](#definitions-1)
These methods handle Tap to Pay processing. Note that the SDK supports both Completion Block and async implementation.
* Swift
```swift
1
/**
2
* Checks whether the Tap to Pay on iPhone payment method is available for the current merchant and whether or
3
* not it requires activation to be performed via a call to
4
* `presentTapToPayActivationFromViewController:animated:completionBlock:`.
5
*
6
* For the merchant to be able to use this payment method the following must be true:
7
*
8
* - The feature must be available in the merchant's country
9
*
10
* - It must be activated. This is where the merchant's Apple ID is linked with their SumUp account and the
11
* iPhone is prepared to work as a card reader. As this can take a minute or so the first time, the
12
* merchant is shown a UI that introduces them to the feature as it initializes in the background.
13
*
14
* The merchant must be logged in before you call this method.
15
*
16
* @param availability YES if the feature is available for the current merchant and it's OK to start activation.
17
* @param isActivated YES if activation has already been done for this device and merchant account
18
*/
19
open class func checkTapToPayAvailability(completion block: @escaping (Bool, Bool, (any Error)?) -> Void)
20
21
/**
22
* Checks whether the Tap to Pay on iPhone payment method is available for the current merchant and whether or
23
* not it requires activation to be performed via a call to
24
* `presentTapToPayActivationFromViewController:animated:completionBlock:`.
25
*
26
* For the merchant to be able to use this payment method the following must be true:
27
*
28
* - The feature must be available in the merchant's country
29
*
30
* - It must be activated. This is where the merchant's Apple ID is linked with their SumUp account and the
31
* iPhone is prepared to work as a card reader. As this can take a minute or so the first time, the
32
* merchant is shown a UI that introduces them to the feature as it initializes in the background.
33
*
34
* The merchant must be logged in before you call this method.
35
*
36
* @param availability YES if the feature is available for the current merchant and it's OK to start activation.
37
* @param isActivated YES if activation has already been done for this device and merchant account
38
*/
39
open class func checkTapToPayAvailability() async throws -> (Bool, Bool)
40
41
/**
42
* Performs activation for Tap to Pay on iPhone. This prepares the device, introduces the merchant to the
43
* feature and links their Apple ID to their SumUp account (which will require confirmation from the merchant.)
44
*
45
* Call `checkTapToPayAvailability:` before calling this method to find out if this payment method is available
46
* and if activation is needed.
47
*
48
* The merchant must be logged in before you call this method.
49
*
50
* Tap to Pay on iPhone requirements:
51
*
52
* - The hosting app must have the `com.apple.developer.proximity-reader.payment.acceptance`
53
* entitlement.
54
*
55
* - The merchant must have an iPhone XS or later with iOS 16.4 or later (iOS 17 or later recommended.)
56
* The feature does not work with iPads.
57
*
58
* @param fromViewController The UIViewController instance from which the UI should be presented modally.
59
* @param animated Pass YES to animate the transition.
60
* @param block The completion block is called after the view controller has been dismissed.
61
*/
62
open class func presentTapToPayActivation(from fromViewController: UIViewController, animated: Bool, completionBlock block: SMPCompletionBlock? = nil)
63
64
/**
65
* Performs activation for Tap to Pay on iPhone. This prepares the device, introduces the merchant to the
66
* feature and links their Apple ID to their SumUp account (which will require confirmation from the merchant.)
67
*
68
* Call `checkTapToPayAvailability:` before calling this method to find out if this payment method is available
69
* and if activation is needed.
70
*
71
* The merchant must be logged in before you call this method.
72
*
73
* Tap to Pay on iPhone requirements:
74
*
75
* - The hosting app must have the `com.apple.developer.proximity-reader.payment.acceptance`
76
* entitlement.
77
*
78
* - The merchant must have an iPhone XS or later with iOS 16.4 or later (iOS 17 or later recommended.)
79
* The feature does not work with iPads.
80
*
81
* @param fromViewController The UIViewController instance from which the UI should be presented modally.
82
* @param animated Pass YES to animate the transition.
83
* @param block The completion block is called after the view controller has been dismissed.
84
*/
85
open class func presentTapToPayActivation(from fromViewController: UIViewController, animated: Bool) async throws -> Bool
```
* Objective C
```objc
1
/**
2
* Checks whether the Tap to Pay on iPhone payment method is available for the current merchant and whether or
3
* not it requires activation to be performed via a call to
4
* `presentTapToPayActivationFromViewController:animated:completionBlock:`.
5
*
6
* For the merchant to be able to use this payment method the following must be true:
7
*
8
* - The feature must be available in the merchant's country
9
*
10
* - It must be activated. This is where the merchant's Apple ID is linked with their SumUp account and the
11
* iPhone is prepared to work as a card reader. As this can take a minute or so the first time, the
12
* merchant is shown a UI that introduces them to the feature as it initializes in the background.
13
*
14
* The merchant must be logged in before you call this method.
15
*
16
* @param availability YES if the feature is available for the current merchant and it's OK to start activation.
17
* @param isActivated YES if activation has already been done for this device and merchant account
18
*/
19
+ (void)checkTapToPayAvailability:(void (^ _Nonnull)(BOOL isAvailable, BOOL isActivated, NSError * _Nullable error))block NS_SWIFT_NAME(checkTapToPayAvailability(completion:));
20
21
/**
22
* Performs activation for Tap to Pay on iPhone. This prepares the device, introduces the merchant to the
23
* feature and links their Apple ID to their SumUp account (which will require confirmation from the merchant.)
24
*
25
* Call `checkTapToPayAvailability:` before calling this method to find out if this payment method is available
26
* and if activation is needed.
27
*ń
28
* The merchant must be logged in before you call this method.
29
*
30
* Tap to Pay on iPhone requirements:
31
*
32
* - The hosting app must have the `com.apple.developer.proximity-reader.payment.acceptance`
33
* entitlement.
34
*
35
* - The merchant must have an iPhone XS or later with iOS 16.4 or later (iOS 17 or later recommended.)
36
* The feature does not work with iPads.
37
*
38
* @param fromViewController The UIViewController instance from which the UI should be presented modally.
39
* @param animated Pass YES to animate the transition.
40
* @param block The completion block is called after the view controller has been dismissed.
41
*/
42
+ (void)presentTapToPayActivationFromViewController:(UIViewController *)fromViewController
43
animated:(BOOL)animated
44
completionBlock:(nullable SMPCompletionBlock)block;
```
#### Implementation
[Section titled “Implementation”](#implementation)
* Swift
```swift
1
SumUpSDK.checkTapToPayAvailability { isAvailable, isActivated, error in
2
3
if let error {
4
// An error occurred
5
return
6
}
7
8
if !isAvailable {
9
// Tap to Pay on iPhone is not available for the merchant
10
return
11
}
12
13
if !isActivated {
14
// Tap to Pay on iPhone needs activation - call presentTapToPayActivation
15
return
16
}
17
18
// The app is ready to take Tap to Pay on iPhone payments!
19
}
```
* Objective C
```objc
1
[SMPSumUpSDK checkTapToPayAvailability:^(BOOL isAvailable, BOOL isActivated, NSError * _Nullable error) {
2
if (error == nil) {
3
if (!isAvailable) {
4
// Tap to Pay on iPhone is not available for the merchant
5
return;
6
}
7
8
if (!isActivated) {
9
// Tap to Pay on iPhone needs activation - call presentTapToPayActivation
10
return;
11
}
12
13
// The app is ready to take Tap to Pay on iPhone payments!
14
15
} else {
16
// An error occurred
17
}
18
}];
```
### Testing your Integration
[Section titled “Testing your Integration”](#testing-your-integration)
In your debug setup you can call `+[SMPSumUpSDK testSDKIntegration]` or `SumUpSDK.testIntegration()` in Swift. It will run various checks and print its findings to the console. Please do not call it in your Release build.
## SDK Structure
[Section titled “SDK Structure”](#sdk-structure)
The SDK uses Objective C header files, but XCode can also display its public types as Swift. The table below outlines the interfaces in the SDK and their purpose.
| Header (Swift alias) | Purpose |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SMPSumUpSDK.h (SumUpSDK) | Includes methods and properties for handling authentication, initial SDK setup, presenting checkout view, and testing your integration. Bundles all other headers and serves as the main SDK interface. |
| SMPCheckoutRequest.h (CheckoutRequest) | Includes methods and properties handling checkout requests, such as amounts, currencies, and payment methods |
| SMPCheckoutResult.h (CheckoutResult) | Handles checkout result structure, including status and transaction code |
| SMPCurrencyCodes.h | Defines available currency codes |
| SMPMerchant.h (Merchant) | Describes a Merchant, including Merchant Code (identifier) and currency used by merchant |
| SMPSkipScreenOptions.h (SkipScreenOptions) | Describes options allowing to skip transaction confirmation screen |
| SumUpSDK.h | Declares project version |
## Sample App
[Section titled “Sample App”](#sample-app)
SumUp provides a sample app which implements main SDK components in a sample App Delegate and View Controller. Check the examples below for highlights provided in both Swift and Objective C. [Clone the provided repository](https://github.com/sumup/sumup-ios-sdk) and check the SampleApp directory to use it.
## Known Issues
[Section titled “Known Issues”](#known-issues)
* In Tap-to-Pay solutions, if entitlements are not correctly set up in your app, `presentTapToPayActivation` may show an error Alert with `Failed to show Terms of Service`.
* Businesses using SumUp sub-accounts must first activate the feature on their main account before using it on devices logged in with sub-accounts, otherwise an error message will appear during activation for the sub-account user.
* Bluetooth permissions will be requested even if the merchant does not plan to use any of the SumUp Bluetooth card readers. This will be fixed in an upcoming release 6.1.
* Distributing XCFrameworks with the latest Carthage version (0.35.0) is not yet available. There is an open issue ([#2799](https://github.com/Carthage/Carthage/issues/2799)) to solve this.
## Community
[Section titled “Community”](#community)
Got questions or found a bug? Get in contact with our integration team by sending an email to .
## Out of Scope
[Section titled “Out of Scope”](#out-of-scope)
The following functions are handled by the [SumUp APIs](/api/):
* [Refunds](/api/transactions/refund/)
* [Transaction history](/api/transactions/list/)
* [Receipts](/api/receipts/get/)
* [Account management](/api/merchant/)
## What’s Next?
[Section titled “What’s Next?”](#whats-next)
Check other resources we have, such as:
* [SumUp Android SDK](https://github.com/sumup/sumup-android-sdk)
* Our [Postman REST API collection](https://github.com/sumup/sumup-postman)
# Authorization
> Pick the right authorization for your integration.
SumUp exposes a REST API that lets you manage checkouts, retrieve transactions and perform other operations programmatically. Before you can make requests you need to authenticate your application and, for card-present integrations, provide an [Affiliate Key](/docs/tools/authorization/affiliate-keys/).
Key topics in this section:
* **[Authorization](/docs/tools/authorization/authorization/)** – explains how to obtain access tokens with API keys or OAuth 2.0.
* **[Affiliate Keys](/docs/tools/authorization/affiliate-keys/)** – learn why affiliate keys are required and how to generate one.
Once you are familiar with these concepts you can explore the detailed [API reference](/api/).
# Affiliate Keys
> Learn about the role of Affiliate Keys at SumUp
## About Affiliate Keys
[Section titled “About Affiliate Keys”](#about-affiliate-keys)
SumUp uses Affiliate Keys to identify critical metrics such as Total Processing Volume coming through a Partner’s integration. The key associates all merchant account users of the Affiliate Key with the partner, allowing SumUp to enforce agreed terms such as fast onboarding, revenue share, and transaction fees. For that reason, **Affiliate Keys are mandatory for card-present integrations**, such as:
* Mobile SDKs including Android SDK and [iOS SDK](/terminal-payments/sdks/ios-sdk/)
* [API Payment Switch](/terminal-payments/payment-switch/)
* [Solo API (Cloud API)](/terminal-payments/cloud-api/)
Affiliate keys are NOT part of any authorization mechanism as such. They are used by SumUp in card-present integrations to attribute the payments to a specific integration.
See [Authorization Guide](/tools/authorization/authorization/) for details on authorization.
## Create Affiliate Key
[Section titled “Create Affiliate Key”](#create-affiliate-key)
1. Log in to .
2. Expand your profile and open **Settings**.
3. Go to **For Developers** > **Toolkit**.
4. Select **Affiliate Keys**.
If you didn’t create a key before, this page is empty, and shows the **Application identifier** field. If you did, your existing Affiliate Key can be found here.
5. Enter the **Application identifier** - this is the App ID/Bundle ID as defined in your development project (such as `com.example.app`).
6. Select **Add**. The key is generated automatically and the App ID is assigned to it. You can add more App IDs to the key if you need to integrate more apps, but **the key itself is immutable**.
## Example Usage
[Section titled “Example Usage”](#example-usage)
Solo Terminal API uses the Affiliate Key in the [Reader Checkout Request](https://developer.sumup.com/api/readers/create-checkout). This request contains a separate section of Affiliates that contains two fields:
* `app_id`: This is the application ID that has been discussed in the earlier section.
* `key`: This is the Affiliate key unique to each account and mandatory to be used by every merchant in their checkout requests.
```json
1
{
2
"affiliate": {
3
"app_id": "your_application_id",
4
"key": "your_affiliate_key"
5
},
6
"checkout": {
7
"amount": 10.0,
8
"currency": "EUR",
9
"description": "Test Transaction"
10
}
11
}
```
## What’s Next?
[Section titled “What’s Next?”](#whats-next)
Check the following resources to build your integration:
* [OAuth 2.0 App Registration Guide](/tools/authorization/register-app/)
* [iOS SDK Guide](/terminal-payments/sdks/ios-sdk/)
* [Android SDK Guide](https://github.com/sumup/sumup-android-sdk)
* [PHP SDK Guide](/online-payments/sdks/php-sdk/)
* [React Native SDK](/terminal-payments/sdks/react-native-sdk/)
* [Cloud API for the Solo Card Reader](/tools/api/sdks/cloud-api/)
# Authorization
> Learn how to authenticate and authorize when calling the SumUp APIs.
## Overview
[Section titled “Overview”](#overview)
All requests to SumUp API must be made over [HTTPS](https://en.wikipedia.org/wiki/HTTPS) and must be authorized.
SumUp supports two kinds of authorization. One is via [API keys](#api-keys) allowing the app to authenticate and authorize on behalf of the Merchant and access the SumUp API with full set of permissions. This is the easiest approach and accommodates most use cases.
The other approach is via [OAuth 2.0](#integration-via-oauth-20), which allows the app to request access on behalf of third parties. This is useful for building advanced integrations to be used by multiple merchants.
## Integration via API Keys
[Section titled “Integration via API Keys”](#integration-via-api-keys)
SumUp uses API keys to authenticate and authorize the API requests. API Keys are short static tokens passed in the `Authorization` header.
```bash
1
curl https://api.sumup.com/v0.1/me -H "Authorization: Bearer $SUMUP_API_KEY"
```
The intended purpose of API keys is to authorize on behalf of a single merchant to whom the API key belongs.
Caution
Do not share your secret API keys in publicly accessible places such as GitHub repositories, client-side code, etc. Your API keys carry full permissions to the entire SumUp API, so make sure to keep them secure. Should you decide to integrate third-parties with the API key, you are responsible for ensuring the security of such integration.
### Create API Key
[Section titled “Create API Key”](#create-api-key)
1. Log in to .
2. Expand your profile and open **Settings**.
3. Go to **For Developers** > **Toolkit**.
4. Select **API Keys**.
If you didn’t create a key before, this page only shows the SumUp Public Key. If you did, your existing API Keys can be found here.
Do not use the public key in your integration.
5. Select **Create** and give the key a meaningful name. Your key is now created and granted permissions to access SumUp APIs.
6. When prompted, copy the key (you can also download it). SumUp does not store the key for security reasons. Integrators are responsible for handling the key securely in accordance with best industry practices.
* Ideally, do not share the key with third parties. If you do, ensure they handle it securely.
* Do not add the key to source-controlled repository or client-side code.
* Monitor key usage.
* Rotate the key on regular basis.
## Affiliate Keys
[Section titled “Affiliate Keys”](#affiliate-keys)
Affiliate Keys are not part of authorization mechanisms as such, but they are required for card-present integrations. For more information, see [Affiliate Keys](/tools/authorization/affiliate-keys/).
## Integration via OAuth 2.0
[Section titled “Integration via OAuth 2.0”](#integration-via-oauth-20)
OAuth 2.0 is the recommended approach for building advanced integrations, where multiple different merchants or their employees want to use SumUp. SumUp conforms to the [OAuth 2.0 protocol](https://oauth.net/2/), providing an authorization server and exposing the following endpoints as defined by the industry:
* `https://api.sumup.com/authorize`
* `https://api.sumup.com/token`
[OAuth 2.0](https://oauth.net/2/) is an industry-standard authorization protocol that allows for control over an application’s scope, and authorization flows across multiple devices. OAuth 2.0 allows the app to request API access on behalf of other users after they grant you the permission.
SumUp supports two standard OAuth 2.0 authorization flows:
* The [authorization code flow](#authorization-code-flow) to request permissions from other users.
* The [client credentials flow](#client-credentials-flow) to authenticate as yourself.
Caution
For security reasons, SumUp manually verifies the following scope grants:
* `payments` - required to process payments.
* `payment_instruments` - required to store customer data and tokenize cards.
[Contact us](/contact) to request those scopes to be granted to your app.
SumUp does not recommend direct OAuth 2.0 integration and does not expose detailed authorization endpoint documentation for that reason. Please use a library that handles OAuth 2.0 protocol. We highly recommend that you use one of the [existing reputable implementations](https://openid.net/developers/certified-openid-connect-implementations/).
### Authorization Code Flow
[Section titled “Authorization Code Flow”](#authorization-code-flow)
This flow works [as specified by RFC 6749 Authorization Code Grant](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1), enabling applications to request permission from a SumUp merchant to act on their behalf. The [requested scopes](#authorization-scopes) define what your application is allowed to do.
1. To initiate the flow, your application redirects a user to the SumUp authorization server with the `https://api.sumup.com/authorize` endpoint.
2. The request triggers an authorization prompt describing which application is requesting authorization from the user.
Caution
If the user denies and clicks the **Cancel** button on the request, the authorization server will not generate an authorization code and will instead return an `error` parameter with an `access_denied` value instead.
3. Once the user accepts your authorization request, the authorization server redirects the user back to your application by using the registered URI you specified in the `redirect_uri` at the initial GET request. The response will return the `code` parameter, which is mandatory for retrieving an access token.
4. To retrieve the access token, the app makes a request to the `https://api.sumup.com/token` endpoint with a `Content-Type: application/x-www-form-urlencoded` header.
The app receives the standard response, containing `access_token`, `refresh_token`, `token_type`, and `expires_in`.
```json
1
{
2
"access_token": "565e2d19cef68203170ddadb952141326d14e03f4ccbd46daa079c26c910a864",
3
"refresh_token": "d180031bfe9bac36c336e5746637810272546865e9c9586012f462a56f3fe9af",
4
"token_type": "Bearer",
5
"expires_in": 3600
6
}
```
The `access_token` can now be used in the `Authorization` header with `Bearer` scheme to authorize calls to SumUp services. The app can use the `refresh_token` to get a new `access_token` when it expires without the user’s interaction (see [Refresh token flow](#refresh-token-flow) below).
### Refresh Token Flow
[Section titled “Refresh Token Flow”](#refresh-token-flow)
To refresh the access token, send a request to the `https://api.sumup.com/token` endpoint with the refresh token you’ve received when completing the [Authorization code flow](#authorization-code-flow), as the OAuth 2.0 protocol dictates. Access tokens can expire for many reasons, such as if the user changes their password or revokes the app access.
In the response, the app receives a new `access_token` that is valid for `expires_in` seconds and a new `refresh_token`. Make sure to store the new `refresh_token` for successive refreshes.
Caution
By default, refresh tokens are valid for a period of 6 months. After your `refresh_token` expires, the app must follow the [Authorization code flow](#authorization-code-flow) again to obtain a valid access token and a new refresh token. A new refresh token will also be issued when a valid refresh token is used within 30 days prior to its expiration. The new refresh token will be valid for another 6 months. The old refresh token remains valid until its expiration date, giving you a grace period to propagate the new token across your integration.
Note that refresh tokens can be invalidated due to factors other than expiration, such as password change, scope changes, etc. Failed attempt to refresh a token should be handled gracefully by triggering a new login and obtaining fresh set of access and refresh token.
### Authorization Scopes
[Section titled “Authorization Scopes”](#authorization-scopes)
Authorization scopes define what an application is allowed to do on a merchant’s behalf. A required set of scopes may be passed as a space-separated list in the authorization request. When scopes are omitted, the default ones are granted. If additional scopes are required, a new `access_token` has to be collected via the [Authorization code flow](#authorization-code-flow).
| Scope name | Default | Access Level | Description |
| --------------------------------- | ------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| transactions.history | yes | merchant | Allows to view the transactions and transaction history for a specific merchant user’s account. |
| user.app-settings | yes | merchant | Allows to view and modify the SumUp mobile application settings for a specific merchant user’s account. |
| user.profile\_readonly | yes | merchant | Allows to view the profile details for a specific merchant user’s account. |
| user.profile | no | merchant | Allows to modify the profile details of a specific merchant user’s account. |
| user.subaccounts | no | merchant | Allows to view and modify the profile details of a sub-account created for a specific merchant user’s account. Sub-accounts are user accounts for employees of a merchant and can be granted different permissions by the holder of the main merchant user’s account. |
| user.payout-settings | no | merchant | Allows to view and modify the payout settings for a specific merchant user’s account. |
| products | no | merchant | Allows to view and modify the product store for a specific merchant user’s account. This includes the products, shelves, prices, and VAT rates available in the merchant’s product store. |
| `restricted` payments | no | feature | Allows to make payments by creating and processing payment checkouts. Requires verification by SumUp before it can be granted. |
| `restricted` payment\_instruments | no | feature | Allows to save customers and tokenize their payment cards for a specific merchant user’s account. Requires verification by SumUp before it can be granted. |
Restricted scopes must be enabled by SumUp for your application. To do that, [contact us](/contact).
### Client Credentials Flow
[Section titled “Client Credentials Flow”](#client-credentials-flow)
This flow works [as specified by RFC 6749 Client Credentials Grant](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4)
In the Client Credentials flow, your application requests an access token without requesting authorization from a merchant user. As a result, when you use this flow, your application is not authorized to access any data that is associated with a merchant user’s account, such as transactions or saved customers and tokenized payment cards. In other words, you can only process payments for merchant accounts with an access token obtained via this grant flow.
To request an access token, the app needs to make a request to the `https://api.sumup.com/token` endpoint as defined in the OAuth 2.0 Client Credentials protocol. This flow does not grant a Refresh Token.
## What’s Next?
[Section titled “What’s Next?”](#whats-next)
Check the following resources to build your integration:
* [OAuth 2.0 App Registration Guide](/tools/authorization/register-app/)
* [iOS SDK Guide](/terminal-payments/sdks/ios-sdk/)
* [Android SDK Guide](https://github.com/sumup/sumup-android-sdk)
* [PHP SDK Guide](/online-payments/sdks/php-sdk/)
* [React Native SDK](/terminal-payments/sdks/react-native-sdk/)
* [Cloud API for the Solo Card Reader](/terminal-payments/cloud-api/)
# Register OAuth 2.0 Application
In order to integrate an external application with SumUp’s ecosystem, you have to register an OAuth application and generate the client credentials which are used to make OAuth-authenticated requests on behalf of your application. You can see more on [OAuth2 authorization flows](/tools/authorization/authorization/), which explain how to request an *access token* that is used to obtain permission to protected resources within SumUp’s API.
In this guide, you will learn how to register a client application and obtain OAuth client credentials for it. You will go through the following steps:
1. [Log in to your account](#1-log-in-to-your-account)
2. [Create an OAuth application](#2-create-an-o-auth-application)
3. [Generate the client credentials](#3-generate-the-client-credentials)
4. [Access the client credentials](#4-access-the-client-credentials)
## Before you begin
[Section titled “Before you begin”](#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 **test account** reach out to our support team through this [contact form](/contact).
* You have the following information available:
* Your application name.
* One or more redirection URIs for registering with SumUp. We will use a registered URI to redirect users to your application after authentication and to send you the authorization codes for obtaining access tokens via the [OAuth2 Authorization Code Flow](/tools/authorization/authorization/#authorization-code-flow).
### 1. Log in to your account
[Section titled “1. Log in to your account”](#1-log-in-to-your-account)
Log in to [your SumUp account](/auth/login). Once logged in, **Account** will appear in place of the **Log in** button on the top right corner of the page.
### 2. Create an OAuth application
[Section titled “2. Create an OAuth application”](#2-create-an-oauth-application)
Navigate to the [OAuth Apps](/apps/) page. This page allows you to create and edit OAuth applications.
Click on **Create application** at the bottom right of the page to define your application.
Create OAuth App screen
Describe your application and provide its homepage. Click **Register application** to complete.
It’s possible to edit the registered application details by clicking on it. The editing page allows to update the initial data and include **optional information** such as a “Logo”, “Terms & Conditions” and “Privacy policy” urls.
Additionally, it’s possible to specify the scope of access to your own merchant information. Each scope includes a short description of what it would give access to if selected.
Caution
For security reasons, SumUp manually verifies the following scope grants:
* `payments` - required to process payments.
* `payment_instruments` - required to store customer data and tokenize cards.
[Contact us](/contact) to request those scopes to be granted to your app.
SumUp does not recommend direct OAuth 2.0 integration and does not expose detailed authorization endpoint documentation for that reason. Please use a library that handles OAuth 2.0 protocol. We highly recommend that you use one of the [existing reputable implementations](https://openid.net/developers/certified-openid-connect-implementations/).
Edit OAuth App screen
The information provided in this section is showed to users when requesting access to their SumUp account data. To read more about how this information is presented see our [OAuth2 Authorization Code Flow](/tools/authorization/authorization/).
### 3. Generate the client credentials
[Section titled “3. Generate the client credentials”](#3-generate-the-client-credentials)
On the [OAuth Apps](/apps) page, click on a registered application. At the bottom of the page click on **Create client secret** to begin.
Click on **Create client secret** and the following form will be presented.
Create new OAuth App credentials form
Provide the following details:
| Name | Required | Description |
| ---------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Client name | Yes | A descriptive name for your client application. |
| Application type | Yes | The type of your client application. You can select from the following options: Web, Android, iOS, Other |
| Authorized redirect URL | Yes | A redirect URL that you want to register for your client application. When merchant users authenticate with SumUp and authorize your client app to access their account data, they are redirected to this path in your application. To specify more than one redirection URL for the client application, separate each URL with a comma. |
| Authorized JavaScript Origin | No | The origin URI of your client application. SumUp allows Cross-Origin Resource Sharing (CORS) across various domains from the browser and is available for type web applications only. The value allows your client application to request resources from SumUp servers. |
Click **Save** to generate the client credentials. In the **Client secrets** section, you will see an entry with the name, application type, and client ID of each generated credential.
Note
You can register as many client applications as you need. To register another credential, repeat this step.
### 4. Access the client credentials
[Section titled “4. Access the client credentials”](#4-access-the-client-credentials)
Once the client credentials have been created, they will be displayed in the **Client credentials** section of your OAuth application’s settings (see screenshot).
OAuth client credentials section
Note
For security reasons, the client secrets are not displayed.
Use the download button to access a JSON file with the full client credential details for the current application. Below you can see an example:
```json
1
{
2
"id": "CCCFAXYD",
3
"name": "SA web client",
4
"client_id": "fOcmczrYtYMJ7Li5GjMLLcUeC9dN",
5
"client_secret": "717bd571b54297494cd7a79b491e8f2c1da6189c4cc2d3481380e8366eef539c",
6
"application_type": "web",
7
"redirect_uris": ["https://sample-app.example.com/callback"]
8
}
```
Note
Make sure to store your client secret keys securely and never reveal them publicly. If you suspect that the secret key for an application has been compromised, [contact us](/contact) immediately.
## Result
[Section titled “Result”](#result)
You have registered at least one client application and have generated and downloaded your OAuth client credentials for it.
You can now use one of the [OAuth2 authorization flows](/tools/authorization/authorization/#authorization-flows) to obtain an access token and start making payments with either a [payment card entered by a customer](/online-payments/guides/single-payment/) or with a token for a [recurring payment](https://developer.sumup.com/online-payments/guides/recurring-payments).
# LLMs
> Use LLMs to guide you through developing with SumUp SDKs.
You can use large language models (LLMs) to assist in the building of SumUp integrations. We provide a set of tools and best practices if you use LLMs during development.
## Plain text docs
[Section titled “Plain text docs”](#plain-text-docs)
You can access all of our documentation as plain text markdown files by adding `index.md` to the end of any url. For example, you can find the plain text version of this page itself at .
This helps AI tools and agents consume our content and allows you to copy and paste the entire contents of a doc into an LLM. This format is preferable to scraping or copying from our HTML and JavaScript-rendered pages because:
* Plain text contains fewer formatting tokens.
* Content that isn’t rendered in the default view (for example, it’s hidden in a tab) of a given page is rendered in the plain text version.
* LLMs can parse and understand markdown hierarchy.
We also host an [/llms.txt](/llms.txt) file which instructs AI tools and agents how to retrieve the plain text versions of our pages. The `/llms.txt` file is an [emerging standard](https://llmstxt.org/) for making websites and content more accessible to LLMs.
## SumUp Model Context Protocol (MCP) Server
[Section titled “SumUp Model Context Protocol (MCP) Server”](#sumup-model-context-protocol-mcp-server)
[MCP](https://modelcontextprotocol.io/introduction) is an open protocol that standardizes how applications provide context to LLMs. For developers using code editors that use AI, such as Cursor or Windsurf, or general purpose tools such as Claude Desktop, we provide the [SumUp Model Context Protocol (MCP) server](https://github.com/sumup/sumup-agent-toolkit/tree/main/mcp). The MCP server provides AI agents a set of tools for calling the SumUp API and searching our knowledge base (documentation, support articles, and so on).
### CLI
[Section titled “CLI”](#cli)
Run the following command to start the MCP server locally.
```sh
1
SUMUP_API_KEY='sup_sk_MvxmLOl0...' npx -y @sumup/mcp
```
The MCP server uses either the passed in —api-key or the `SUMUP_API_KEY` environment variable.
### [Cursor](https://www.cursor.com/)
[Section titled “Cursor”](#cursor)
1. Go to `Cursor Settings` > `MCP`
2. Click `+ Add new Global MCP Server`
3. Add the following configuration to your global `.cursor/mcp.json` file.
See the [Cursor documentation](https://docs.cursor.com/context/model-context-protocol) for more details. Note that you can also add this to your project specific cursor configuration. (Supported in Cursor 0.46+)
```json
1
{
2
"mcpServers": {
3
"sumup": {
4
"command": "npx",
5
"args": ["-y", "@sumup/mcp"],
6
"env": {
7
"SUMUP_API_KEY": "sup_sk_..."
8
}
9
}
10
}
11
}
```
### [Claude](https://claude.ai)
[Section titled “Claude”](#claude)
Add the following to your `claude_desktop_config.json` file. See the [Claude Desktop documentation](https://modelcontextprotocol.io/quickstart/user) for more details.
```json
1
{
2
"mcpServers": {
3
"sumup": {
4
"command": "npx",
5
"args": ["-y", "@sumup/mcp"],
6
"env": {
7
"SUMUP_API_KEY": "sup_sk_..."
8
}
9
}
10
}
11
}
```
The code editor agent automatically detects all the available tools and calls the relevant tool when you post a related question in the chat.
## SumUp Agent Toolkit SDK
[Section titled “SumUp Agent Toolkit SDK”](#sumup-agent-toolkit-sdk)
If you’re building agentic software, we provide an SDK for adding SumUp functionality to your agent’s capabilities. Learn more in our [agents documentation](/tools/LLMs/agent-toolkit).
# Agentic Workflows
> Use SumUp in your agentic workflows.
Use SumUp to enhance your agent with SumUp functionalities. By enabling access to financial services and tools, you allow your agents to help you earn money, manage funds, and other provide other functionalities available in SumUp APIs.
## OpenAI
[Section titled “OpenAI”](#openai)
Example usage of the [SumUp Agent Toolkit](https://github.com/sumup/sumup-agent-toolkit) with the [OpenAI](https://github.com/openai/openai-node).
```ts
1
import { SumUpAgentToolkit } from "@sumup/agent-toolkit/openai";
2
import OpenAI from "openai";
3
import type { ChatCompletionMessageParam } from "openai/resources";
4
5
require("dotenv").config();
6
7
const openai = new OpenAI();
8
9
const sumupAgentToolkit = new SumUpAgentToolkit({
10
apiKey: process.env.SUMUP_API_KEY!,
11
});
12
13
(async (): Promise => {
14
let messages: ChatCompletionMessageParam[] = [
15
{
16
role: "user",
17
content: "Tell me about my last 10 transactions please.",
18
},
19
];
20
21
while (true) {
22
// eslint-disable-next-line no-await-in-loop
23
const completion = await openai.chat.completions.create({
24
model: "gpt-4o",
25
messages,
26
tools: sumupAgentToolkit.getTools(),
27
});
28
29
const message = completion.choices[0].message;
30
31
messages.push(message);
32
33
if (message.tool_calls) {
34
// eslint-disable-next-line no-await-in-loop
35
const toolMessages = await Promise.all(
36
message.tool_calls.map((tc) => sumupAgentToolkit.handleToolCall(tc)),
37
);
38
messages = [...messages, ...toolMessages];
39
} else {
40
console.log(completion.choices[0].message);
41
break;
42
}
43
}
44
})();
```
## AI SDK
[Section titled “AI SDK”](#ai-sdk)
Example usage of the [SumUp Agent Toolkit](https://github.com/sumup/sumup-agent-toolkit) with the [AI SDK](https://sdk.vercel.ai/).
```ts
1
import { openai } from "@ai-sdk/openai";
2
import { SumUpAgentToolkit } from "@sumup/agent-toolkit/ai";
3
import { generateText } from "ai";
4
5
require("dotenv").config();
6
7
const sumupAgentToolkit = new SumUpAgentToolkit({
8
apiKey: process.env.SUMUP_API_KEY!,
9
});
10
11
const model = openai("gpt-4o");
12
13
(async () => {
14
const result = await generateText({
15
model: model,
16
tools: {
17
...sumupAgentToolkit.getTools(),
18
},
19
maxSteps: 5,
20
prompt: "Tell me about my last 5 transactions and their status.",
21
});
22
23
console.log(result);
24
})();
```
# Merchant
> Merchant object represents the business operating with SumUp.
A Merchant is a business and a User can own and/or manage multiple businesses. Within SumUp every Merchant is identified by its merchant code, typically a string like `MK01A8C2`. For a detailed list of properties of the Merchant, please have a look at the [Merchants API reference](/api/merchants).
## Company
[Section titled “Company”](#company)
The `company` field of the Merchant contains the business’s legal information. This is the data SumUp checks when verifying the merchant before enabling products.
### Company Identifiers
[Section titled “Company Identifiers”](#company-identifiers)
A key part of the company data are identification numbers contained in the `identifiers` array. Each identifier is a `CompanyIdentifier` object with:
* **`ref`** (string): the unique reference for the identifier type
* **`value`** (string): the actual identifier value
For every identifier, we use a unique reference as key following the pattern `{country_code}.{identifier_type}`. The prefix indicates the country (using ISO 3166-1 alpha-2 codes), and the suffix identifies the specific type of identifier.
#### Australia `AU`
[Section titled “Australia AU”](#australia-au)
* **Australian Business Number** `au.abn`\
Australian Business Number is the Australian Business Number. Every Australian business must have one. Companies with an ABN may use it instead of the TFN and the ACN. The ABN is an 11-digit number.
* **Australian Company Number** `au.acn`\
Australian Company Number is the Australian Company Number. It is used for specific registered companies and is a subset of the ABN. We only use it for the legal type “company”. The ACN is a 9-digit number.
#### Austria `AT`
[Section titled “Austria AT”](#austria-at)
* **Umsatzsteuer-Identifikationsnummer** `at.uid`\
Umsatzsteuer-Identifikationsnummer is referece to the Austrian VAT ID, the Umsatzsteuer-Identifikationsnummer.
* **Abgabenkontonummer** `at.abgabenkontonummer`\
Abgabenkontonummer is the Austrian tax identification number, Abgabenkontonummer. It is issued to natural and legal persons for he purpose of declaring taxes and interacting with the local revenue offices. The number consists of 9 digits. The first two digits identify the local tax office (uses leading zero). The next six digits are the actual tax ID. The last digit is a check digit.
* **Zentrale Vereinsregister-Zahl** `at.zvr`\
Zentrale Vereinsregister-Zahl is the Austrian association registry number, Zentrale Vereinsregister-Zahl. It is a mandatory identifier for all associations. It is a 10-digit number.
* **Firmenbuchnummer** `at.fn`\
Firmenbuchnummer is the Austrian company registration number, the “Firmenbuchnummer”. It consists of six digits and a check letter.
#### Belgium `BE`
[Section titled “Belgium BE”](#belgium-be)
* **Belasting over de Toegevoegde Waarde nummer** `be.btw`\
Belasting over de Toegevoegde Waarde nummer is the Belgian VAT number. Since 2020 it’s the same as the Ondernemingsnummer, but with the `BE` prefix.
* **Ondernemingsnummer** `be.ondernemingsnummer`\
Ondernemingsnummer is the Belgian company registration number. Before 2023 all numbers started with `0`. Since 2023 numbers may start with `0` or `1`.
#### Brazil `BR`
[Section titled “Brazil BR”](#brazil-br)
* **Cadastro Nacional de Pessoa Juridica** `br.cnpj`\
Cadastro Nacional de Pessoa Juridica is the Brazilian company registration number. It is used as company identifier and as VAT ID for a company.
#### Bulgaria `BG`
[Section titled “Bulgaria BG”](#bulgaria-bg)
* **Identifikacionen nomer po DDS** `bg.dds`\
Identifikacionen nomer po DDS is the Bulgarian VAT number. It is the same for individuals and registered companies.
* **BULSTAT Unified Identification Code** `bg.uic`\
BULSTAT Unified Identification Code is the Bulgarian BULSTAT Unified Identification Code. Every individual business or registered company must have one.
#### Canada `CA`
[Section titled “Canada CA”](#canada-ca)
* **Business Number** `ca.business_number`\
Business Number (BN) is a unique number assigned by the Canada Revenue Agency (CRA) to identify a business.
* **GST/HST Number** `ca.gst_hst_number`\
GST/HST Number is a unique number assigned by the Canada Revenue Agency (CRA) to identify a business for Goods and Services Tax (GST) and Harmonized Sales Tax (HST).
* **QST Number (Quebec)** `ca.qst_number`\
QST Number is a unique number assigned by Revenu Québec to identify a business for Quebec Sales Tax (QST).
#### Chile `CL`
[Section titled “Chile CL”](#chile-cl)
* **Rol Único Tributario** `cl.rut`\
Rol Único Tributario is the Chilean tax ID. For individuals the RUT is the same as the RUN (the national ID). Registered companies have to obtain a RUT.
#### Colombia `CO`
[Section titled “Colombia CO”](#colombia-co)
* **Número de Identificación Tributaria** `co.nit`\
Número de Identificación Tributaria is the Colombian tax ID. It applies to individuals and companies.
#### Croatia `HR`
[Section titled “Croatia HR”](#croatia-hr)
* **Osobni identifikacijski broj** `hr.oib`\
In Croatia, the OIB (Osobni identifikacijski broj) is a unique, permanent personal identification number assigned to both citizens and legal entities.
#### Cyprus `CY`
[Section titled “Cyprus CY”](#cyprus-cy)
* **Arithmós Engraphḗs phi. pi. a.** `cy.fpa`\
Arithmós Engraphḗs phi. pi. a. is the Cypriot VAT number.
* **Company Registration Number** `cy.crn`\
Company Registration Number is the Cypriot company registration number.
#### Czech Republic `CZ`
[Section titled “Czech Republic CZ”](#czech-republic-cz)
* **Daňové identifikační číslo** `cz.dic`\
Daňové identifikační číslo is the Czech VAT ID, the Daňové identifikační číslo.
* **Identifikační číslo osoby** `cz.ico`\
Identifikační číslo osoby is the Czech company registration number, the Identifikační číslo osoby.
#### Denmark `DK`
[Section titled “Denmark DK”](#denmark-dk)
* **CVR-nummer** `dk.cvr`\
CVR-nummer is the Danish company registration number number, Centrale Virksomhedsregister nummer. It is used both as company identifier and VAT ID.
* **CVR-nummer** `dk.cvr`\
CVR-nummer is the Danish company registration number number, Centrale Virksomhedsregister nummer. It is used both as company identifier and VAT ID.
#### Estonia `EE`
[Section titled “Estonia EE”](#estonia-ee)
* **Käibemaksukohustuslase number** `ee.kmkr`\
Käibemaksukohustuslase number is the Estonian VAT ID, the Käibemaksukohustuslase.
* **Äriregistri Kood** `ee.reg`\
Äriregistri Kood is the Estonian company registration number, the Registrikood.
#### Finland `FI`
[Section titled “Finland FI”](#finland-fi)
* **Arvonlisäveronumero Mervärdesskattenummer** `fi.alv`\
Arvonlisäveronumero Mervärdesskattenummer is the Finnish VAT number. The VAT number can be derived directly from the Business ID by prefixing the Business ID with `FI` and removing the dash before the check digit at the end. Businesses must register with the Finnish tax office before they can use their Business ID dependent VAT number..
* **Y-tunnus** `fi.yt`\
Y-tunnus is the Finnish Business ID, the Y-tunnus. Sole traders and registered companies must obtain one. The Business ID The Business ID of a legal person, such as a company, remains the same as long as the legal person is operative. If the company type changes in a way defined by law, the Business ID remains the same. If the activities of a general partnership or a limited liability company are continued by a person operating as a sole trader, the Business ID changes. The Y-tunnus consists of seven digits, a dash and a control mark
#### France `FR`
[Section titled “France FR”](#france-fr)
* **Numéro d’identification à la taxe sur la valeur ajoutée / Numéro de TVA intracommunautaire** `fr.tva`\
Numéro d’identification à la taxe sur la valeur ajoutée / Numéro de TVA intracommunautaire is the French VAT number, the Taxe sur la valeur ajoutée. For registered companies, the TVA is derived from the SIREN by prefixing the SIREN with `FR`. Any company, exceeding a certain annual revenue are liable for VAT.
* **Système d’identification du répertoire des entreprises** `fr.siren`\
Système d’identification du répertoire des entreprises is the french registration number given to French businesses and non-profit associations. The number consists of nine digits, of which the final digit is a check digit calculated via Luhn. Exampels: - `123 123 123`
* **Système d’identification du répertoire des établissements** `fr.siret`\
Système d’identification du répertoire des établissements is a unique French identifier for a specific business location. SIRET is the Système d’identification du répertoire des établissements. Each SIRET number identifies a specific establishment/location of a business. The first nine digits of the SIRET are the business’ SIREN number. The business location is identified by the next four digits, the NIC or “Numéro interne de classement”. The final 14th digit is a check digit, calculated via Luhn. Sole traders
* **Numéro Répertoire national des associations / Numéro RNA** `fr.rna`\
Numéro Répertoire national des associations / Numéro RNA is the French association number, the Numéro d’Association. It starts with the letter `W`, followed by 9 digits. Associatinos must use a SIRET instead of the RNA, if they have employees, wish to apply for subsidies, or when they are required to pay VAT or corporate tax.
#### Germany `DE`
[Section titled “Germany DE”](#germany-de)
* **Umsatzsteuer-Identifikationsnummer** `de.ust_idnr`\
Umsatzsteuer-Identifikationsnummer is the German VAT ID, Umstatzsteuer-Identifikationsnummer.
* **Handelsregister A Nummer** `de.hra`\
Handelsregister A Nummer is the German company registration number for individual enterprises (e.K.), commercial (general and limited) partnerships (OHG and KG), corporations of public law running a business and EEIGs.
* **Handelsregister B Nummer** `de.hrb`\
Handelsregister B Nummer is the German company registration number for covers the following company types: public limited company (AG), association limited by shares (KGaA), limited liability companies (GmbH), and others.
* **Vereinsregenister Nummer** `de.vr`\
Vereinsregenister Nummer is the German registration number for registered associations, eingegratener Verein (e.V.).
* **Other registration numbers** `de.other`\
Other registration numbers is used to identify other German company registration numbers.
#### Greece `GR`
[Section titled “Greece GR”](#greece-gr)
* **Arithmós Forologikou Mētrṓou - ΑΦΜ** `gr.afm`\
Arithmós Forologikou Mētrṓou - ΑΦΜ is the Greece tax ID, the Arithmós Forologikou Mētrṓou (AFM). Sole traders (sole proprietorship) use their personal tax ID to conduct business. Companies register for a tax ID. We always require an AFM in Greece.
* **General Commercial Registry number.** `gr.gemi`\
General Commercial Registry number. is the Greek company registration number, the General Commercial Registry (Γ.Ε.ΜI.) number. All Natural or legal persons or associations of such persons have to register in the General Commercial Registry. The exception are sole traders, wo can start conducting their business without going through GEMI.
#### Hungary `HU`
[Section titled “Hungary HU”](#hungary-hu)
* **Közösségi adószám** `hu.anum`\
Közösségi adószám is the Hungarian vat number, the Közösségi adószám. The format of the ANUM is HU12345678. The eight digit are the first digits in the Hungarian tax ID, the adószám. The tax ID has the format 12345678-1-23 (see references). The regex we have for the ANUM also accepts the adószám and leaves the country code prefix optional.
* **Cégjegyzékszám** `hu.cegjegyzekszam`\
Cégjegyzékszám is the Hungarian company registration number, the Cégjegyzékszám. NOTE: the values we have for this in platform DB are all over the place in terms of legal types. Technically, the cegjegyzekszam contains the company form. Looking at the numbers we have to the sole trader and registered sole trader legal types, the numbers map to limited liability companies and other legal types.
* **Adószám** `hu.adoszam`\
Adószám is the Hungarian tax number, the Adószám. It is not to be confused with the tax identification number, adoazonosító jel.
#### Ireland `IE`
[Section titled “Ireland IE”](#ireland-ie)
* **Value added tax identification no.** `ie.vat`\
Value added tax identification no. is the Irish VAT number and a unique identifier for Irish companies. It is identical to the TRN prefixed with `IE`.
* **Tax Registration Number** `ie.trn`\
Tax Registration Number is the Irish tax ID, the Tax Registration Number. Companies must register with Revenue to obtain a TRN. For sole traders who register with Revenue their PPSN becomes their business’ TRN. We collect the TRN for non-registered companies as company registration number.
* **Value added tax identification no.** `ie.crn`\
Value added tax identification no. is the Irish company registration number, issued by Companies Registaion Office. It’s a six digit code. NOTE: I found it very hard to find *any* references for this. I asked some AI search which gave the six digit answer and maybe found something in a forum somewhere. Additionally our database is full of six digit numbers, so I deem this to be correct. Users does not have any validations for Irish CRNs.
* **Tax identification number for charities** `ie.chy`\
Tax identification number for charities is the tax identification number for charitable organizations. The format starts with the letters `CHY`, followed by 1 to 5 digits.
#### Italy `IT`
[Section titled “Italy IT”](#italy-it)
* **Partita IVA** `it.p_iva`\
Partita IVA is the Italian VAT number. It is used for individual businesses and registered companies. If a natural or legal person has a partita IVA, then it is used as fiscal code.
* **REA Number** `it.rea_number`\
REA Number is the Italian REA number, the “Repertorio Economico Amministrativo”. It’s issued upon registration with the Italian chamber of commerce. The REA also serves as fiscal code. It seems that if a company has a VAT number and a REA, the VAT number is used as fiscal code.
#### Latvia `LV`
[Section titled “Latvia LV”](#latvia-lv)
* **PVN reģistrācijas numurs** `lv.pvn`\
PVN reģistrācijas numurs is the Latvian VAT number, the Pievienotās vērtības nodokļa numurs. It is the same as the personal or company TIN, but prefixed with “LV” and without the check digit.
* **Reģistrācijas numur** `lv.registracijas_numur`\
Reģistrācijas numur is the Latvian company identification code. It is issued by the State Revenue Service or by the Enterprise Register. The number consists of 11 digits. The State Revenue Service issues numbers starting “9000”, while the Enterprise Register numbers start with “4000” or “5000”. There is no documented check digit algorithm. The identification code is also used as tax identification number (TIN).
#### Lithuania `LT`
[Section titled “Lithuania LT”](#lithuania-lt)
* **PVM mokėtojo kodas** `lt.pvm_kodas`\
PVM mokėtojo kodas is the Lithuanian VAT number, the PVM mokėtojo kodas. NOTE: You can almost not find any information about this identifier.
* **Įmonės kodas** `lt.imones_kodas`\
Įmonės kodas is the Lithuanian company code, the Įmonės kodas. NOTE: I’ve found nothing on this. An AI search said legal persons have a 9 digit code, natural persons have an 11 digit code. In our database we only seem to have 9 digit codes.
#### Luxembourg `LU`
[Section titled “Luxembourg LU”](#luxembourg-lu)
* **Numéro d’identification à la taxe sur la valeur ajoutée** `lu.tva`\
Numéro d’identification à la taxe sur la valeur ajoutée is the Luxembourgian VAT number, the Taxe sur la valeur ajoutée. Natural and legal persons typically must register for a VAT number, meaning sole traders and registered companies. “A taxable person liable for VAT is each natural or legal person who carries out, on an independent and regular basis, any operation falling within any economic activity, whatever the purpose or result of the activity and from whatever location it is performed.”
* **Matricule** `lu.matricule`\
Matricule is the Luxembourgian unique identification number for both natural and legal persons. It’s referred to as matricule or “numéro d’identification personnelle” and is used as tax ID. In the case of natural persons the matricule can have 11 or 13 digits. Any numbers issued from 2014 have 13 digits. Legal persons are issued matricules with 11 digits. The format for a natural person is `YYYY MMDD XXX (XX)`, where the first 8 digits are the date of birth of the person. The remaining five digits are “random”. The 12th digit is a Luhn10 check digit. The 13th digit is a de Verhoeff check digit. Both are calculated from the first 11 digits. The format for legal persons is `AAAA FF XX XXX`, where `AAAA` is the year of formation, `FF` is the form of the company, and `XX XXX`are random numbers.
* **Numéro d’identification unique** `lu.rcs`\
Numéro d’identification unique is the Luxmebourgian company registration number, stored in the “Registre du commerce et des sociétés”. The number format is `B123456`, it may be prefixed by variations of `RCS`. The letter at the beginning of the number indicates the kind of company. `B` stands for a commercial company. NOTE: I was not able to find any documentation on the exact format and the different letters used to identify the company type.
#### Malta `MT`
[Section titled “Malta MT”](#malta-mt)
* **Numru tal-VAT** `mt.vat_no`\
Numru tal-VAT is the Maltese VAT number, the Numru tal-VAT. It starts with “MT”, followed by 8 digits.
* **Business Registration Number** `mt.brn`\
Business Registration Number is the Maltese business registration number. The Maltese Business Register maintains a register of companies, foundations, and associations NOTE: sent an email to Malta Business Register to get clarification on different business registration number formats. We have many numbers with the formats C12345, P12345, V/O12345. These seem to be companies, partnerships, and associations.
#### Mexico `MX`
[Section titled “Mexico MX”](#mexico-mx)
* **Registro Federal de Contribuyentes** `mx.rfc`\
Registro Federal de Contribuyentes is the Mexican tax identification number, the Registro Federal de Contribuyentes. It is issued to natural persons and legal entities and required to perform any economic activity in Mexico, including VAT. The RFC format depends on whether it belongs to a natural person or legal entity. - Natural erson: XXXX YYMMDD ZZZ - Legal entity: XXX YYMMDD ZZZ The XXXX and XXX parts are derived from the person’s or company’s name. The YYMMDD is the date of birth or date of company formation, respectively. ZZZ is a randomly assigned alphanumeric code by the tax administration service. It includes a checksum.
#### Netherlands `NL`
[Section titled “Netherlands NL”](#netherlands-nl)
* **Btw-nummer** `nl.btw`\
Btw-nummer is the Dutch VAT identification number, the btw-identificatienummer. A Dutch VAT number starts with NL, then comes 9 digits, the letter B, and then another 2 digits. Sole traders and registered companies receive VAT IDs. There’s also a VAT tax number (omzetbelastingnummer), which is only used to communicate with the tax authorities.
* **Kamer van Koophandel nummer** `nl.kvk`\
Kamer van Koophandel nummer is the Dutch company registration number, the Kamer van Koophandel nummer (KVK nummer). It’s issued for every business registering in the chamber of commerce. Most businesses must register with the KVK, there are only a few exceptions. When the owner of a company changes, the KVK number will also change. The KVK number is an eight-digit number.
#### Norway `NO`
[Section titled “Norway NO”](#norway-no)
* **MVA-nummer** `no.mva`\
MVA-nummer is the Norwegian VAT number, the Merverdiavgiftsnummer. It is the same as the Organisasjonsnummer, but with an extra suffix `MVA`.
* **Organisasjonsnummer** `no.orgnr`\
Organisasjonsnummer is the Norwegian organization number, the Organisasjonsnummer. It is assigned to legal entities upon registration. Sole traders who are subject to value added tax must also register. The organization number consists of 9 digits whereof the last digit is a check digit based on a special weighted code, modulus 11.
#### Poland `PL`
[Section titled “Poland PL”](#poland-pl)
* **Numer identyfikacji podatkowej** `pl.nip`\
Numer identyfikacji podatkowej is the Polish tax identification number for for businesses, the numer identyfikacji podatkowej. It is used for both natural and legal persons. The NIP is also used as VAT ID, in which case it’s prefixed by `PL`. The hyphens are only used for formatting. The positioning of the hyphens depends on whether the NIP belongs to a natural or legal person. lib.
* **Numer Krajowego Rejestru Sądowego** `pl.krs`\
Numer Krajowego Rejestru Sądowego is the Polish registration number for companies, associations, foundations, etc., the numer Krajowego Rejestru Sądowego. It is used for companies only, sole traders register in a different registry. The KRS number has ten digits with leading zeros.
* **Numer Rejestr Gospodarki Narodowej** `pl.regon`\
Numer Rejestr Gospodarki Narodowej is the polish business registration number for sole traders, the numer Rejestr Gospodarki Narodowej. All natural and legal persons performing economic activies must register in the system. The number consists of 9 or 14 digits. Regular businesses receive a 9 digit REGON number. Larger businesses with multiple branches receive a 14 digit number. The first two digits identify the county in Poland where the business is registered. The following six digits are uniquely assigned to the business. In a 14 digit REGON number, the next 4 digits identify the local business unit. The final digit is a check digit.
#### Portugal `PT`
[Section titled “Portugal PT”](#portugal-pt)
* **Número de Identificação Fiscal** `pt.nif`\
Número de Identificação Fiscal is the Portuguese tax identification number for natural persons, the Número de Identificação Fiscal. The NIF is assigned by the Tax and Customs Authority for all citizens. NIFs can be distinguished from NIPCs by the first digit. NIFs start with 1, 2, or 3. The number has 9 digits, the last digit is a check digit.
* **Número de Identificação de Pessoa Coletiva** `pt.nipc`\
Número de Identificação de Pessoa Coletiva is the Portuguese tax identification number for legal persons, the Número de Identificação de Pessoa Coletiva. The NIPC is issued when a company is registered National Register of Legal Entities.. NIPCs can be distinguished from NIFs by the first digit. NIPCs start with the numbers 5 through 9 (see OECD TIN document). The number has 9 digits, the last digit is a check digit.
* **Código de acesso à certidão permanente** `pt.codigo`\
Código de acesso à certidão permanente is the access code for the permanent certificate of business registration, the código de acesso à certidão permanente. This code is required to access a company’s records (the permanent certificate) in the commercial register. NOTE: we seem to have collected this number for both the company registration number and as a dedicated field. The company registration numbers for Portugal seem to therefore be all over the place. Users were probably confused because there is no such thing as a company registration number in Portugal, that resembles the access code’s format. The NIPC serves as company identifier for tax purposes. The code consists of 12 digits in groups of four, separated by hyphens.
#### Romania `RO`
[Section titled “Romania RO”](#romania-ro)
* **Codul de TVA** `ro.cui`\
Codul de TVA is the Romanian unique identification number for businesses, the Codul Unic de Înregistrare. Pretty much all businesses, including sole traders, must register for a CUI. The CUI serves as tax identification number. If the business is registered for VAT, their CUI is also their VAT ID when prefixed with `RO`. The CUI consists of 2 to 10 digits. The last digit is a check digit (see linked Wikipedia).
* **Codul Unic de Înregistrare** `ro.cui`\
Codul Unic de Înregistrare is the Romanian unique identification number for businesses, the Codul Unic de Înregistrare. Pretty much all businesses, including sole traders, must register for a CUI. The CUI serves as tax identification number. If the business is registered for VAT, their CUI is also their VAT ID when prefixed with `RO`. The CUI consists of 2 to 10 digits. The last digit is a check digit (see linked Wikipedia).
* **Codul de identificare fiscală** `ro.cif`\
Codul de identificare fiscală is the generic term for the Romanian tax identification number, the Codul de identificare fiscală. The CIF can take several forms. - For Romanian citizens who have not registered their business in the Trade Register, due to exemptinos, their CNP is their business’ CIF. - For non-romanian citizens, the CIF is issued by the tax administration and takes the same shape as the CNP. - For natural persons who exercise their business under a special law, not requiring them to register, the CIF is issued by the tax authorities. - Businesses that register with the Trade Register receive a CUI to serve as their CIF. In most cases we should not collect a generic CIF and instead require a CUI or CNP.
* **Numărul de ordine în registrul comerţului** `ro.onrc`\
Numărul de ordine în registrul comerţului is the Romanian registration number from the trade register, the numărul de ordine în registrul comerţului. When registering a company in the trade register, one receives the ONRC number, which is akin to a company registration number, as well as the unique company code, CUI (see \[refROCUI]). The ONRC number is local to the province one registers in. It can change over time, for example when a company moves to a different province. The number consists of three parts. The first part starts with one of the letters J (legal entities), F (authorized natural persons, sole proprietorships and family businesses), or C (cooperative societies). The letter is followed by a number from 1 to 40 (with leading zero), identifying the county in which the business is registered. The second part of the ONRC is the local register’s “order number” of the year of registration. It gets reset every year. The last part is the year of registration.
#### Slovakia `SK`
[Section titled “Slovakia SK”](#slovakia-sk)
* **Identifikačné číslo pre daň z pridanej hodnoty** `sk.dph`\
Identifikačné číslo pre daň z pridanej hodnoty is the Slovak Republic’s VAT ID, the Identifikačné číslo pre daň z pridanej hodnoty. Any business making more than a certain threshold is required to register for VAT, including sole traders. It’s a ten-digit number, prefixed with `SK`. The number can be validated by calculating its modulo 11. The result has to be `0`.
* **Identifikačné číslo organizácie** `sk.ico`\
Identifikačné číslo organizácie is the Slovak Republic’s organization identification number, the Identifikačné číslo organizácie. It is issued automatically to natural persons and legal entities running a business as well as public sector organizations etc. The first seven digits are the identification number. The eights digit is a check digit.
#### Slovenia `SI`
[Section titled “Slovenia SI”](#slovenia-si)
* **Identifikacijska številka za DDV** `si.ddv`\
Identifikacijska številka za DDV is the Slovenian tax identification number, the Davčna številka. It is issued to all natural and legal persons. The DDV serves as VAT number when prefixed with `SI`. The DDV is an eight-digit number. The first seven digits are random, the eighth digit is a mod11 check digit.
* **Matična številka** `si.maticna`\
Matična številka is the Slovenian company registration number, the Matična številka poslovnega registra. The number consists of 7 or 10 digits and includes a check digit. The first 6 digits represent a unique number for each unit or company, followed by a check digit. The last 3 digits represent an additional business unit of the company, starting at 001. When a company consists of more than 1000 units, a letter is used instead of the first digit in the business unit. Unit 000 always represents the main registered address.
#### Spain `ES`
[Section titled “Spain ES”](#spain-es)
* **Número de Identificación Fiscal** `es.nif`\
Número de Identificación Fiscal is the Spanish personal identification number. It is used for individual company types. The NIF corresponds to the DNI for Spanish nationals and the NIE for foreign nationals.
* **Certificado de Identificación Fiscal** `es.cif`\
Certificado de Identificación Fiscal is the Spanish tax ID for companies and legal entities, the Código de Identificación Fiscal. It is used as unique identifier for companies and as VAT ID.
#### Sweden `SE`
[Section titled “Sweden SE”](#sweden-se)
* **VAT-nummer** `se.momsnr`\
VAT-nummer is the Swedish VAT number, the Momsregistreringsnummer. The format for the Momsregistreringsnummer is `SEXXXXXX-XXXX01` It always starts with `SE` and ends in `01`. For legal entities the middle part is the Organisationsnummer (see \[refSEOrgNr]). For sole traders, the part contains the Personnummer (see \[refSEPers]).
* **Organisationsnumret** `se.orgnr`\
Organisationsnumret is the Swedish tax identification number for legal entities, the Organisationsnummer. It is assigned by the authority, which registers the respective organization type (i.e., Companies Registration Office, Tax Agency, Central Bureau of Statistics, etc.). The Organisationsnummer is used as tax identification number. Sole traders use their social security number as tax identification numbers. The Organisationsnummer has 10 digits and should pass luhn’s checksum algorithm.
#### Switzerland `CH`
[Section titled “Switzerland CH”](#switzerland-ch)
* **Mehrwertsteuernummer / Taxe sur la valeur ajoutée / Imposta sul valore aggiunto** `ch.mwst`\
Mehrwertsteuernummer / Taxe sur la valeur ajoutée / Imposta sul valore aggiunto is the Swiss VAT number. It is identical to the UID but uses a MWST suffix when written without a label, i.e. `CHE123456789MWST`.
* **Unternehmens-Identifikationsnummer** `ch.uid`\
Unternehmens-Identifikationsnummer is the Swiss company registration number, the Unternehmens-Identifikationsnummer. It is has the format `CHE123456789`.
#### United Kingdom `GB`
[Section titled “United Kingdom GB”](#united-kingdom-gb)
* **Value added tax registration number** `gb.vrn`\
Value added tax registration number is the British VAT number, the VAT registration number. Any business with an annual turnover exceeding a VAT threshold must register for a VRN.
* **The company registration number for companies registered with Companies House** `gb.crn`\
The company registration number for companies registered with Companies House is the British company registration number. Limited companies, Limited Partnerships, and Limited Liability Partnerships have to register with Companies House and receive the CRN.
#### United States `US`
[Section titled “United States US”](#united-states-us)
* **Social Security Number** `us.ssn`\
Social Security Number is the United States social security number. It is used for taxation of natural persons, like sole traders. From Wikipedia: > The SSN is a nine-digit number, usually written in the format `AAA-GG-SSSS`. > The number has three parts: the first three digits, called the area number because > they were formerly assigned by geographical region; the middle two digits, the > group number; and the last four digits, the serial number.
* **Employer Identification Number** `us.ein`\
Employer Identification Number is the United States employer identification number. It is used for business entities which have to pay withholding taxes on employees. The EIN is a nine-digit number, usually written in form 00-0000000.
* **Social Security Number** `us.itin`\
Social Security Number is the United States individual tax identification number. Individuals who cannot get a social security number (see refUSSSN) can apply for an ITIN. From Wikipedia: > It is a nine-digit number beginning with the number “9”, has a range > of numbers from “50” to “65”, “70” to “88”, “90” to “92” and “94” to “99” > for the fourth and fifth digits, and is formatted like a SSN (i.e., 9XX-XX-XXXX).
* **Social Security Number** `us.ssn`\
Social Security Number is the United States social security number. It is used for taxation of natural persons, like sole traders. From Wikipedia: > The SSN is a nine-digit number, usually written in the format `AAA-GG-SSSS`. > The number has three parts: the first three digits, called the area number because > they were formerly assigned by geographical region; the middle two digits, the > group number; and the last four digits, the serial number.
* **Employer Identification Number** `us.ein`\
Employer Identification Number is the United States employer identification number. It is used for business entities which have to pay withholding taxes on employees. The EIN is a nine-digit number, usually written in form 00-0000000.
* **Social Security Number** `us.itin`\
Social Security Number is the United States individual tax identification number. Individuals who cannot get a social security number (see refUSSSN) can apply for an ITIN. From Wikipedia: > It is a nine-digit number beginning with the number “9”, has a range > of numbers from “50” to “65”, “70” to “88”, “90” to “92” and “94” to “99” > for the fourth and fifth digits, and is formatted like a SSN (i.e., 9XX-XX-XXXX).
Example:
```json
1
{
2
"identifiers": [
3
{
4
"ref": "de.hrb",
5
"value": "HRB 123456 B"
6
},
7
{
8
"ref": "de.ust_idnr",
9
"value": "DE123456789"
10
}
11
]
12
}
```
### Legal types
[Section titled “Legal types”](#legal-types)
Legal type is the official way the business is set up and recognized by the law. Legal types are of the pattern `{country_code}.{identifier_type}`. The prefix indicates the country (using [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)), and the suffix identifies the specific legal type within that country.
#### Australia `AU`
[Section titled “Australia AU”](#australia-au-1)
* **Agent** (Agent) `au.agt`
* **Trust** (Trust) `au.trust`
* **Co-operative** (Co-operative) `au.coop`
* **Sole Trader** (Sole Trader) `au.st`
* **Company** (Company) `au.co`
* **Partnership** (Partnership) `au.pship`
* **Association** (Association) `au.assoc`
#### Austria `AT`
[Section titled “Austria AT”](#austria-at-1)
* **Alle nicht registrierten Einzelunternehmen und freien Berufe ohne andere Gesellschaftsform** (Einzelunternehmer/Freiberufler) `at.freiberufler`
* **Eingetragenes Einzelunternehmen (e. U.)** (e.U.) `at.eu`
* **Gesellschaft bürgerlichen Rechts (GesbR)** (GesbR) `at.gesbr`
* **Offene Gesellschaft (OG)** (OG) `at.og`
* **Kommanditgesellschaft (KG)** (KG) `at.kg`
* **Gesellschaft mit beschränkter Haftung (GmbH)** (GmbH) `at.gmbh`
* **Aktiengesellschaft (AG)** (AG) `at.ag`
* **Verein** (Verein) `at.verein`
* **Andere Rechtsformen** (Andere) `at.andere`
#### Belgium `BE`
[Section titled “Belgium BE”](#belgium-be-1)
* **Entreprise individuelle** (Entreprise individuelle) `be.ei`
* **Partenariat** (Partenariat) `be.partenariat`
* **Société en Nom Collectif (SNC)** (Société en Nom Collectif (SNC)) `be.vof`
* **Société en Commandite par Action (SCA)** (Société en Commandite par Action (SCA)) `be.sca`
* **Société en Commandite Simple (SCS)** (Société en Commandite Simple (SCS)) `be.cv`
* **Société Anonyme (SA)** (Société Anonyme (SA)) `be.nv`
* **Société à responsabilité limitée (S.R.L.)** (Société à responsabilité limitée (S.R.L.)) `be.sprl`
* **Fondations** (Fondations) `be.stichting`
* **Association Sans But Lucratif (ASBL)** (Association Sans But Lucratif (ASBL)) `be.asbl`
* **Société Coopérative à Responsabilité Limitée (SC/SCRL)** (Société Coopérative à Responsabilité Limitée (SC/SCRL)) `be.scscrl`
* **Société Coopérative à Responsabilité Illimitée (SCRI)** (Société Coopérative à Responsabilité Illimitée (SCRI)) `be.scri`
* **Agence Publique** (Agence Publique) `be.state_agency`
#### Brazil `BR`
[Section titled “Brazil BR”](#brazil-br-1)
* **Pessoa Física** (Pessoa Física) `br.pessoa_fisica`
* **LTDA** (LTDA) `br.ltda`
* **S/A Capital Aberto** (S/A Capital Aberto) `br.sa_capital_aberto`
* **S/A Capital Fechado** (S/A Capital Fechado) `br.sa_capital_fechado`
* **Sociedade Simples** (Sociedade Simples) `br.sociedade_simples`
* **Cooperativa** (Cooperativa) `br.cooperativa`
* **Associação** (Associação) `br.associacao`
* **Fundação** (Fundação) `br.fundacao`
* **Outros** (Outros) `br.outros`
* **Entidade Sindical** (Entidade Sindical) `br.entidade_sindical`
* **Empresa de Pequeno Porte (EPP)** (Empresa de Pequeno Porte (EPP)) `br.empresa_pequeno_porte`
* **Empresa Individual de Responsabilidade Limitada (Eireli)** (Empresa Individual de Responsabilidade Limitada (Eireli)) `br.eireli`
* **Pessoa Jurídica payleven** (Pessoa Jurídica payleven) `br.pessoa_juridica_payleven`
* **Micro Empreendedor Individual (MEI)** (Micro Empreendedor Individual (MEI)) `br.empresario_individual`
* **Pessoa Jurídica** (Pessoa Jurídica) `br.pessoa_juridica`
* **Empresa individual (EI)** (Empresa individual (EI)) `br.empresa_individual`
#### Bulgaria `BG`
[Section titled “Bulgaria BG”](#bulgaria-bg-1)
* **Събирателно дружество** (СД) `bg.general_partnership`
* **Командитно дружество** (КД) `bg.limited_partnership`
* **Командитно дружество с акции** (КДА) `bg.limited_partnership_with_shares`
* **Дружество с ограничена oтговорност** (ООД) `bg.private_limited_company`
* **Еднолично дружество с ограничена отговорност** (ЕООД) `bg.private_limited_company_with_a_single_member`
* **Акционерно дружество** (АД) `bg.joint-stock_company`
* **Консорциум** (Консорциум) `bg.association`
* **Фондация** (Фондация) `bg.foundation`
* **Кооперация** (Кооперация) `bg.cooperative`
* **Друго** (Друго) `bg.other`
* **Едноличен търговец** (Едноличен търговец) `bg.sole_trader`
* **Професионалист на свободна практика** (Професионалист на свободна практика) `bg.freelancer`
* **Еднолично акционерно дружество** (ЕАД) `bg.sole_shareholding_company`
#### Canada `CA`
[Section titled “Canada CA”](#canada-ca-1)
* **Sole proprietorship** (Sole proprietorship) `ca.sp`
* **Private company** (Private company) `ca.bsns`
* **Listed public company** (Listed public company) `ca.lpc`
* **Governmental organization** (Governmental organization) `ca.gorg`
* **Association incorporated** (Association incorporated) `ca.asinc`
* **Nonprofit or charitable organisation** (Non-profit) `ca.npro`
* **Unincorporated partnership** (Unincorporated partnership) `ca.unincpar`
* **Incorporated partnership** (Partnership) `ca.pship`
#### Chile `CL`
[Section titled “Chile CL”](#chile-cl-1)
* **Persona Natural** (Persona Natural) `cl.sole_trader`
* **Sociedad de Responsabilidad Limitada** (Sociedad de Responsabilidad Limitada (SRL)) `cl.ltda`
* **Sociedad Anónima** (Sociedad Anónima (SA)) `cl.sa`
* **Sociedad por Acciones** (Sociedad por Acciones (SPA)) `cl.sca`
* **Empresas Individuales de Responsabilidad Limitada** (Empresa Individual de Responsabilidad Limitada (EIRL)) `cl.eirl`
* **Sociedad en Comandita Simple** (Sociedad en Comandita Simple) `cl.scs`
#### Colombia `CO`
[Section titled “Colombia CO”](#colombia-co-1)
* **Sociedad por Acciones Simplificadas (S.A.S.)** (Sociedad por Acciones Simplificadas (S.A.S.)) `co.sas`
* **Sociedad de Responsabilidad Limitada (Ltda.)** (Sociedad de Responsabilidad Limitada (Ltda.)) `co.ltda`
* **Sociedad Colectiva (S.C.)** (Sociedad Colectiva (S.C.)) `co.sc`
* **Sociedad Comandita Simple (S. en C.)** (Sociedad Comandita Simple (S. en C.)) `co.sec`
* **Persona Natural** (Persona Natural) `co.pers`
* **Empresa Unipersonal (E.U.)** (Empresa Unipersonal (E.U.)) `co.eu`
* **Sociedad Comandita por Acciones (S.C.A.)** (Sociedad Comandita por Acciones (S.C.A.)) `co.sca`
* **Sociedad Anónima (S.A.)** (Sociedad Anónima (S.A.)) `co.sa`
#### Croatia `HR`
[Section titled “Croatia HR”](#croatia-hr-1)
* **udruga** (udruga) `hr.association_new`
* **obrt** (obrt) `hr.sole_trader_new`
* **javno trgovačko društvo** (j.t.d.) `hr.general_partnership_new`
* **komanditno društvo** (k.d.) `hr.limited_partnership_new`
* **društvo s ograničenom odgovornošću** (d.o.o. / j.d.o.o.) `hr.private_limited_company_new`
* **dioničko društvo** (d.d.) `hr.public_limited_company_new`
* **zadruga** (zadruga) `hr.cooperative_new`
* **Drugo** (Drugo) `hr.other_new`
* **Ortaštvo** (Ortaštvo) `hr.partnership_of_two_or_more_sole_traders_new`
#### Cyprus `CY`
[Section titled “Cyprus CY”](#cyprus-cy-1)
* **Δημόσια εταιρεία περιορισμένης ευθύνης** (Δημόσια εταιρεία περιορισμένης ευθύνης) `cy.public_limited_company`
* **Ατομική επιχείρηση** (Ατομική επιχείρηση) `cy.sole_trader`
* **Εταιρεία περιορισμένης ευθύνης δια μετοχών** (Εταιρεία περιορισμένης ευθύνης δια μετοχών) `cy.private_limited_company`
* **Άλλο** (Άλλο) `cy.other`
* **Εταιρεία περιορισμένης ευθύνης με εγγύηση** (Εταιρεία περιορισμένης ευθύνης με εγγύηση) `cy.company_limited_by_guarantee`
* **Ομόρρυθμη εταιρεία** (Ομόρρυθμη εταιρεία) `cy.general_partnership`
* **Συνεταιρισμός** (Συνεταιρισμός) `cy.associations`
* **Ίδρυμα** (Ίδρυμα) `cy.foundation`
* **Ετερόρρυθμη εταιρεία** (Ετερόρρυθμη εταιρεία) `cy.limited_partnership`
#### Czech Republic `CZ`
[Section titled “Czech Republic CZ”](#czech-republic-cz-1)
* **Živnost** (Živnost) `cz.sole_trader`
* **Společnost** (Společnost) `cz.unregistered_partnership`
* **Veřejná obchodní společnost** (v.o.s.) `cz.general_partnership`
* **Komanditní společnost** (k.s.) `cz.limited_partnerhip`
* **Společnost s ručením omezeným** (s.r.o., spol. s r.o.) `cz.private_limited_company`
* **Akciová společnost** (a.s., akc. spol.) `cz.public_limited_company`
* **Družstvo** (Družstvo) `cz.cooperative`
* **Zapsaný spolek** (z.s.) `cz.association`
* **Nadační fond** (Nadační fond) `cz.foundation`
* **jiný** (jiný) `cz.other`
#### Denmark `DK`
[Section titled “Denmark DK”](#denmark-dk-1)
* **Enkeltmandsvirksomhed** (Enkeltmandsvirksomhed) `dk.sole_trader`
* **Interessentskab** (I/S) `dk.general_partnership`
* **Kommanditselskab** (K/S) `dk.limited_partnership`
* **Partnerselskab or Kommanditaktieselskab** (P/S) `dk.partnership_limited_by_shares`
* **Anpartsselskab** (ApS) `dk.private_limited_company`
* **Aktieselskab** (A/S) `dk.public_limited_company`
* **Andelsselskab med begrænset ansvar** (A.M.B.A.) `dk.limited_liability_co-operative`
* **Forening med begrænset ansvar** (F.M.B.A.) `dk.limited_liability_voluntary_association`
* **Forening** (Forening) `dk.association`
* **Erhvervsdrivende fond** (Erhvervsdrivende fond) `dk.commercial_foundation`
* **Ikke-erhvervsdrivende fond** (Ikke-erhvervsdrivende fond) `dk.non_commercial_foundation`
* **Anden** (Anden) `dk.other`
#### Estonia `EE`
[Section titled “Estonia EE”](#estonia-ee-1)
* **Füüsilisest Isikust Ettevõtja** (FIE) `ee.sole_trader`
* **Täisühing** (TÜ) `ee.general_partnership`
* **Usaldusühing** (UÜ) `ee.limited_partnership`
* **Osaühing** (OÜ) `ee.private_limited_company`
* **Aktsiaselts** (AS) `ee.public_limited_company`
* **Ühistu** (Ühistu) `ee.cooperative`
* **Muud liiki** (Muud liiki) `ee.other`
* **Tulundusühistu** (TulÜ) `ee.commercial_association`
#### Finland `FI`
[Section titled “Finland FI”](#finland-fi-1)
* **Avoin yhtiö** (Ay) `fi.general_partnership`
* **Kommandiittiyhtiö** (Ky) `fi.limited_partnership`
* **Osakeyhtiö** (Oy) `fi.private_limited_company`
* **Julkinen osakeyhtiö** (Oyj) `fi.public_limited_company`
* **Osuuskunta** (Osk) `fi.cooperative`
* **Rekisteröity yhdistys** (ry) `fi.registered_association`
* **Säätiö** (rs) `fi.foundation`
* **Muut** (Muut) `fi.other`
* **Yksityinen elinkeinonharjoittaja** (Yksityinen elinkeinonharjoittaja) `fi.sole_trader`
#### France `FR`
[Section titled “France FR”](#france-fr-1)
* **Entrepreneur Individuel is a sole trader legal type.** (Entrepreneur Individuel) `fr.ei`
* **EURL** (EURL) `fr.eurl`
* **SARL** (SARL) `fr.sarl`
* **SA** (SA) `fr.sa`
* **SAS** (SAS) `fr.sas`
* **SASU** (SASU) `fr.sasu`
* **SNC** (SNC) `fr.snc`
* **Association** (Association) `fr.association`
* **Autres** (Autres) `fr.autres`
#### Germany `DE`
[Section titled “Germany DE”](#germany-de-1)
* **Alle nicht registrierten Einzelunternehmen und freien Berufe ohne andere Gesellschaftsform** (Einzelunternehmer/Freiberufler) `de.freiberufler`
* **Eingetragener Kaufmann / Eingetragene Kauffrau (e.K., e.Kfm. oder e.Kfr.)** (e.Kfm./e.Kfr.) `de.ekfr`
* **Gesellschaft bürgerlichen Rechts (GbR)** (GbR) `de.gbr`
* **Offene Handelsgesellschaft (OHG)** (OHG) `de.ohg`
* **Kommanditgesellschaft (KG)** (KG) `de.kg`
* **Unternehmergesellschaft (UG (haftungsbeschränkt))** (UG (haftungsbeschränkt)) `de.ug`
* **Gesellschaft mit beschränkter Haftung (GmbH)** (GmbH) `de.gmbh`
* **GmbH & Co. KG** (GmbH & Co. KG) `de.gmbhco`
* **Aktiengesellschaft (AG)** (AG) `de.ag`
* **Eingetragener Verein (e.V.)** (e.V.) `de.ev`
* **Andere Rechtsformen** (Andere) `de.andere`
* **Stiftung** (Stiftung) `de.stiftung`
* **Genossenschaft (eG)** (eG) `de.genossenschaft`
* **Körperschaft öffentlichen Rechts (KöR)** (KöR) `de.koerperschaft`
#### Greece `GR`
[Section titled “Greece GR”](#greece-gr-1)
* **Atomikí epicheírisi / ατομική επιχείρηση** (Atomikí epicheírisi / ατομική επιχείρηση) `gr.sole_trader`
* **Omórithmi Etaireía / Ομόρρυθμη Εταιρεία** (OE) `gr.general_partnership`
* **Eterórithmi Etaireía / Ετερόρρυθμη Εταιρία** (EE) `gr.limited_partnership`
* **Anónimi Etaireía / Ανώνυμη Εταιρεία** (AE) `gr.public_limited_company`
* **Etaireía Periorisménis Euthínis / Εταιρεία Περιορισμένης Ευθύνης** (EPE) `gr.private_limited_company`
* **Monoprósopi Etaireía Periorisménis Euthínis / Μονοπρόσωπη** (MEPE) `gr.ltd_with_a_single_member`
* **Άλλο** (Άλλο) `gr.other`
* **Συνεταιρισμός** (Συνεταιρισμός) `gr.association`
* **Ίδρυμα** (Ίδρυμα) `gr.foundation`
#### Hungary `HU`
[Section titled “Hungary HU”](#hungary-hu-1)
* **Egyéni vállalkozó** (e.v.) `hu.sole_trader`
* **Egyéni cég** (e.c.) `hu.registered_sole_trader`
* **Betéti társaság** (bt.) `hu.limited_partnership`
* **Közkereseti társaság** (kkt.) `hu.general_partnership`
* **Korlátolt felelősségű társaság** (kft.) `hu.private_limited_company`
* **Nyilvánosan működő részvénytársaság** (Nyrt.) `hu.public_limited_company`
* **Zártközűen működő részvénytársaság** (Zártközűen működő részvénytársaság) `hu.privately_held_company`
* **Társaság** (Társaság) `hu.cooperative`
* **Szövetség** (Szövetség) `hu.association`
* **Alapítvány** (Alapítvány) `hu.foundation`
* **Más** (Más) `hu.other`
#### Ireland `IE`
[Section titled “Ireland IE”](#ireland-ie-1)
* **Sole proprietorship / sole trader** (Sole trader) `ie.sole_trader`
* **All clubs or societies** (Club or society) `ie.society`
* **All schools, colleges or universities** (School, college or university) `ie.edu`
* **All other legal forms** (Other) `ie.other`
* **Private limited company** (Limited company (Ltd.)) `ie.limited`
* **All partnerships** (Partnership (LP, LLP)) `ie.partnership`
#### Italy `IT`
[Section titled “Italy IT”](#italy-it-1)
* **Società a responsabilità limitata semplificata (Srls)** (Società a responsabilità limitata semplificata (Srls)) `it.srls`
* **Società a responsabilità limitata unipersonale (Srl Uni)** (Società a responsabilità limitata unipersonale (Srl Uni)) `it.srl_uni`
* **Società Semplice (S.s.)** (Società Semplice (S.s.)) `it.ss`
* **Libero Professionista** (Libero Professionista) `it.libero`
* **Imprenditore individuale** (Imprenditore individuale) `it.individuale`
* **Società in nome collettivo (S.n.c.)** (Società in nome collettivo (S.n.c.)) `it.snc`
* **Società in accomandita semplice (S.a.s)** (Società in accomandita semplice (S.a.s)) `it.sas`
* **Società Cooperativa** (Società Cooperativa) `it.societa_cooperative`
* **Società per Azioni (Spa)** (Società per Azioni (Spa)) `it.spa`
* **Società a responsabilità limitata (Srl)** (Società a responsabilità limitata (Srl)) `it.srl`
* **Società di capitali** (Società di capitali) `it.società_di_capitali`
* **Società di persone** (Società di persone) `it.società_di_persone`
* **Società in accomandita per azioni** (Società in accomandita per azioni) `it.siapa`
* **Agenzia Statale** (Agenzia Statale) `it.agenzia_statale`
* **Associazioni** (Associazioni) `it.associazioni`
#### Latvia `LV`
[Section titled “Latvia LV”](#latvia-lv-1)
* **Individuālais komersants** (IK) `lv.sole_trader`
* **Komandītsabiedrība** (KS) `lv.limited_partnership`
* **Pilnsabiedrība** (PS) `lv.general_partnership`
* **Sabiedrība ar ierobežotu atbildību** (SIA) `lv.private_limited_company`
* **Akciju sabiedrība** (AS) `lv.public_limited_company`
* **Asociācija** (Asociācija) `lv.association`
* **Fonds** (Fonds) `lv.foundation`
#### Lithuania `LT`
[Section titled “Lithuania LT”](#lithuania-lt-1)
* **Individuali veikla** (Individuali veikla) `lt.sole_trader`
* **Individuali įmonė** (IĮ) `lt.individual_company`
* **Tikroji ūkinė bendrija** (TŪB) `lt.general_partnership`
* **Komanditinė ūkinė bendrija** (KŪB) `lt.limited_partnership`
* **Mažoji bendrija** (MB) `lt.small_partnership`
* **Uždaroji akcinė bendrovė** (UAB) `lt.private_limited_company`
* **Akcinė bendrovė** (AB) `lt.public_limited_company`
* **Kooperatinė bendrovė** (Kooperatinė bendrovė) `lt.cooperative`
* **Asociacija** (Asociacija) `lt.association`
* **Fondas** (Fondas) `lt.foundation`
* **Kitas** (Kitas) `lt.other`
#### Luxembourg `LU`
[Section titled “Luxembourg LU”](#luxembourg-lu-1)
* **Entrepreneur Individual** (Entrepreneur Individual) `lu.sole_trader`
* **Société en commandite simple** (SECS) `lu.limited_partnership`
* **Sociéteé civil or sociéteé en nom collectif** (SENC) `lu.general_partnership`
* **Société en commandité par actions** (SCA) `lu.partnership_limited_by_shares`
* **Société à responsabilitée limitée** (SARL) `lu.private_limited_company`
* **Société anonyme** (SA) `lu.public_limited_company`
* **Société co-opérative** (SC) `lu.cooperative`
* **Association** (Association) `lu.association`
* **Autres** (Autres) `lu.other`
#### Malta `MT`
[Section titled “Malta MT”](#malta-mt-1)
* **Sole trader** (Sole trader) `mt.sole_trader`
* **Limited partnership** (Limited partnership) `mt.limited_partnership`
* **General partnership** (General partnership) `mt.general_partnership`
* **Private limited company** (Private limited company) `mt.private_limited_company`
* **Public limited company** (Public limited company) `mt.public_limited_company`
* **Association** (Association) `mt.associations`
* **Foundation** (Foundation) `mt.foundation`
* **Other** (Other) `mt.other`
#### Mexico `MX`
[Section titled “Mexico MX”](#mexico-mx-1)
* **Persona fisica** (Persona fisica) `mx.persona_fisica`
* **Persona moral** (Persona moral) `mx.persona_moral`
* **Empresa sin fin de lucro** (Empresa sin fin de lucro) `mx.empresa_sin_fin_de_lucro`
#### Netherlands `NL`
[Section titled “Netherlands NL”](#netherlands-nl-1)
* **Zzp (Zelfstandige Zonder Personeel)** (Zzp (Zelfstandige Zonder Personeel)) `nl.zzp`
* **Eenmanszaak (KvK registratie)** (Eenmanszaak (KvK registratie)) `nl.kvk`
* **Maatschap** (Maatschap) `nl.maatschap`
* **Vennootschap Onder Firma (VOF)** (Vennootschap Onder Firma (VOF)) `nl.vof`
* **Commanditaire Vennootschap (CV)** (Commanditaire Vennootschap (CV)) `nl.cv`
* **Naamloze Vennootschap (NV)** (Naamloze Vennootschap (NV)) `nl.nv`
* **Besloten Vennootschap (BV)** (Besloten Vennootschap (BV)) `nl.bv`
* **Stichting** (Stichting) `nl.stichting`
* **Vereniging met volledige rechtsbevoegdheid** (Vereniging met volledige rechtsbevoegdheid) `nl.vvr`
* **Vereniging met beperkte rechtsbevoegdheid** (Vereniging met beperkte rechtsbevoegdheid) `nl.vbr`
* **Coöperatie en Onderlinge Waarborgmaatschappij** (Coöperatie en Onderlinge Waarborgmaatschappij) `nl.cow`
* **Overheidsinstelling** (Overheidsinstelling) `nl.overheidsinstelling`
* **Vereniging** (Vereniging) `nl.vereniging`
#### Norway `NO`
[Section titled “Norway NO”](#norway-no-1)
* **Enkeltpersonforetak** (ENK) `no.sole_trader`
* **Kommandittselsjap** (KS) `no.limited_partnership`
* **Ansvarlig Selskap** (ANS/DA) `no.general_partnership`
* **Aksjeselskap** (AS) `no.private_limited_company`
* **Allmennaksjeselskap** (ASA) `no.public_limited_company`
* **Samvirkeforetak** (Samvirkeforetak) `no.cooperative`
* **Stiftelse** (Stiftelse) `no.foundation`
* **Forening** (Forening) `no.association`
* **Norskregistrert Utenlandsk Foretak** (Norskregistrert Utenlandsk Foretak) `no.norwegian_registered_foreign_enterprise`
* **Annen** (Annen) `no.other`
#### Peru `PE`
[Section titled “Peru PE”](#peru-pe)
* **Persona Natural** (Persona Natural) `pe.pers`
* **Empresa Unipersonal (E.U.)** (Empresa Unipersonal (E.U.)) `pe.eu`
* **Empresa Individual de Responsabilidad Limitada (E.I.R.L.)** (Empresa Individual de Responsabilidad Limitada (E.I.R.L.)) `pe.eirl`
* **Sociedad Anónima (S.A.)** (Sociedad Anónima (S.A.)) `pe.sa`
* **Sociedad Anónima Abierta (S.A.A.)** (Sociedad Anónima Abierta (S.A.A.)) `pe.saa`
* **Sociedad Anónima Cerrada (S.A.C.)** (Sociedad Anónima Cerrada (S.A.C.)) `pe.sac`
* **Sociedad Comercial de Responsabilidad Limitada (S.R.L.)** (Sociedad Comercial de Responsabilidad Limitada (S.R.L.)) `pe.srl`
* **Sociedad por Acciones Cerrada Simplificada (S.A.C.S.)** (Sociedad por Acciones Cerrada Simplificada (S.A.C.S.)) `pe.sacs`
* **Associación** (Associación) `pe.associación`
* **Fundación** (Fundación) `pe.fundación`
* **Comité** (Comité) `pe.comité`
#### Poland `PL`
[Section titled “Poland PL”](#poland-pl-1)
* **Spółka Cywilna** (Spółka Cywilna) `pl.cywilna`
* **Indywidualna działalność gospodarcza** (Indywidualna działalność gospodarcza) `pl.indywidualna`
* **Stowarzyszenie/Fundacja** (Stowarzyszenie/Fundacja) `pl.stowarzyszenie_fundacja`
* **spółka komandytowo-akcyjna** (Spółka komandytowo-akcyjna) `pl.komandytowo-akcyjna`
* **spółka komandytowa** (Spółka komandytowa) `pl.komandytowa`
* **spółka jawna** (Spółka jawna) `pl.jawna`
* **spółka akcyjna** (Spółka akcyjna) `pl.akcyjna`
* **spółka z o.o.** (Spółka z o.o.) `pl.zoo`
* **spółka partnerska** (Spółka partnerska) `pl.partnerska`
#### Portugal `PT`
[Section titled “Portugal PT”](#portugal-pt-1)
* **Empresário em nome individual** (Empresário em nome individual) `pt.eni`
* **Associação/Organização sem fins lucrativos** (Associação/Organização sem fins lucrativos) `pt.asfl`
* **Sociedade Civil** (Sociedade Civil) `pt.sociedad`
* **Sociedade por Quotas** (Sociedade por Quotas) `pt.sociedad_limitada`
* **Sociedade Anônima** (Sociedade Anônima) `pt.sociedad_anonima`
* **Sociedade em Comandita** (Sociedade em Comandita) `pt.sociedad_comanditaria`
* **Sociedade em Nome Colectivo** (Sociedade em Nome Colectivo) `pt.sociedad_colectiva`
* **Cooperativas** (Cooperativas) `pt.sociedad_cooperativa`
* **Espresa Estatal** (Espresa Estatal) `pt.state_agency`
* **Pessoas Colectivas de Direito Público** (Pessoas Colectivas de Direito Público) `pt.pcdp`
#### Romania `RO`
[Section titled “Romania RO”](#romania-ro-1)
* **Persoana fizica autorizata** (PFA) `ro.sole_trader`
* **Asociere fără personalitate juridică** (Asociere fără personalitate juridică) `ro.unregistered_partnership`
* **Societatea în nume colectiv** (SNC) `ro.general_partnership`
* **Societatea în comandită simplă** (SCS) `ro.limited_partnership`
* **Societatea în comandită pe acțiuni,** (SCA) `ro.partnership_limited_by_shares`
* **Societatea pe acțiuni** (SA) `ro.public_limited_company`
* **Societatea cu răspundere limitată** (SRL) `ro.private_limited_company`
* **Societatea cu răspundere limitată cu proprietar unic** (SRL cu proprietar unic) `ro.private_limited_company_with_sole_owner`
* **Cooperativă** (Cooperativă) `ro.cooperative`
* **Asociație** (Asociație) `ro.association`
* **Fundație** (Fundație) `ro.foundation`
* **Alt** (Alt) `ro.other`
#### Slovakia `SK`
[Section titled “Slovakia SK”](#slovakia-sk-1)
* **akciová spoločnosť** (a.s.) `sk.public_limited_company`
* **verejná obchodná spoločnosť** (v.o.s.) `sk.general_partnership`
* **komanditná spoločnosť** (k.s.) `sk.limited_partnership`
* **spoločnosť s ručením obmedzeným** (s.r.o.) `sk.private_limited_company`
* **živnostník** (živnostník) `sk.sole_trader`
* **Združenie bez právnej subjektivity** (Združenie bez právnej subjektivity) `sk.unregistered_partnership`
* **Združenie** (Združenie) `sk.association`
* **Nadácia** (Nadácia) `sk.foundation`
* **Podnik / Organizačná zložka podniku zahraničnej osob** (Podnik / Organizačná zložka podniku zahraničnej osob) `sk.enterprise_or_foreign_company`
* **Iný** (Iný) `sk.other`
* **Družstvo** (Družstvo) `sk.cooperative`
#### Slovenia `SI`
[Section titled “Slovenia SI”](#slovenia-si-1)
* **Komanditna delniška družba** (k.d.d.) `si.partnership_limited_by_shares`
* **Združenje** (Združenje) `si.foundation`
* **Samostojni podjetnik** (s.p.) `si.sole_trader`
* **Komanditna družba** (k.d.) `si.limited_partnership`
* **Družba z neomejeno odgovornostjo** (d.n.o.) `si.private_unlimited_company`
* **Družba z omejeno odgovornostjo** (d.o.o.) `si.private_limited_company`
* **Delniška družba** (d.d.) `si.public_limited_company`
* **Zadruga** (Zadruga) `si.cooperative`
* **Druga** (Druga) `si.other`
* **Društvo, zveza društev** (Društvo, zveza društev) `si.association`
#### Spain `ES`
[Section titled “Spain ES”](#spain-es-1)
* **Empresario Individual/autónomo** (Empresario Individual/autónomo) `es.autonomo`
* **Comunidad de Bienes** (Comunidad de Bienes) `es.comunidad`
* **Sociedad Civil** (Sociedad Civil) `es.sociedad`
* **Asociaciones sin ánimo de lucro** (Asociaciones sin ánimo de lucro) `es.asociaciones`
* **Sociedad Colectiva** (Sociedad Colectiva) `es.sociedad_colectiva`
* **Sociedad Limitada** (Sociedad Limitada) `es.sociedad_limitada`
* **Sociedad Anónima** (Sociedad Anónima) `es.sociedad_anonima`
* **Sociedad Comanditaria** (Sociedad Comanditaria) `es.sociedad_comanditaria`
* **Sociedad Cooperativa** (Sociedad Cooperativa) `es.sociedad_cooperativa`
* **Agencia Estatal** (Agencia Estatal) `es.state_agency`
#### Sweden `SE`
[Section titled “Sweden SE”](#sweden-se-1)
* **Enskildnärings - verksamhet** (Enskildnärings) `se.sole_trader`
* **Kommanditbolag** (Kommanditbolag) `se.limited_partnership`
* **Aktiebolag** (Aktiebolag) `se.limited`
* **Handelsbolag** (Handelsbolag) `se.trading_partnership`
* **Förening** (Förening) `se.economic_association`
#### Switzerland `CH`
[Section titled “Switzerland CH”](#switzerland-ch-1)
* **Kollektivgesellschaft** (Kollektivgesellschaft) `ch.kollektivgesellschaft`
* **Kollektivgesellschaft (OLD)** (Kollektivgesellschaft (OLD)) `ch.kollektivgesellschaft`
* **Einzelfirma** (Einzelfirma) `ch.einzelfirma`
* **Kommanditgesellschaft** (Kommanditgesellschaft) `ch.kommanditgesellschaft`
* **Gesellschaft mit beschränkter Haftung** (Gesellschaft mit beschränkter Haftung) `ch.gesellschaft_haftung`
* **Aktiengesellschaft/ Société anonyme** (Aktiengesellschaft/ Société anonyme) `ch.aktiengesellschaft_societe`
* **Verein** (Verein) `ch.ch_verein`
* **Einfache Gesellschaft** (Einfache Gesellschaft) `ch.einfachegesellschaft`
#### United Kingdom `GB`
[Section titled “United Kingdom GB”](#united-kingdom-gb-1)
* **All partnerships** (Partnership (LP, LLP)) `gb.partnership`
* **Sole proprietorship / sole trader** (Sole trader) `gb.sole_trader`
* **All clubs or societies** (Club or society) `gb.society`
* **All schools, colleges or universities** (School, college or university) `gb.edu`
* **All other legal forms** (Other) `gb.other`
* **Private limited company** (Limited company (Ltd.)) `gb.limited`
#### United States `US`
[Section titled “United States US”](#united-states-us-1)
* **Limited Partnership** (LP) `us.partnership`
* **Limited Liability Partnership** (LLP) `us.llp`
* **Limited Liability Limited Partnership** (LLLP) `us.lllp`
* **Limited Company** (LC) `us.lc`
* **Limited Liability Company** (LLC) `us.llc`
* **Professional Limited Liability Company** (PLLC) `us.pllc`
* **Single Member Limited Liability Company** (SMLLC) `us.smllc`
* **Corporation Incorporated** (Corp. Inc.) `us.corp_inc`
* **Professional Corporation** (PC) `us.pc`
* **Non-profit Organisation** (Non-profit Organisation) `us.uba_org`
* **Sole proprietorship** (Sole proprietorship) `us.sole_trader`
## Business Profile
[Section titled “Business Profile”](#business-profile)
A Merchant’s business profile contains information that a Merchant wants to be publicly visible for their customers, for example on their website.
## Addresses
[Section titled “Addresses”](#addresses)
The Merchant object uses a comprehensive address format that can handle addresses from around the world. The address fields used depend on the country conventions. For example, in Great Britain, `city` is `post_town`. In the United States, the top-level administrative unit used in addresses is `state`, whereas in Chile it’s `region`.
The address structure is based on [libaddressinput](https://github.com/google/libaddressinput) used by Android and Chromium.
Whether an address is valid depends on whether the locally required fields are present. For example:
* **Germany**: requires `street_address`, `post_code`, and `city`
* **United States**: uses `state` for the top-level administrative unit
* **Great Britain**: uses `post_town` instead of `city`
* **Chile**: uses `region` for the top-level administrative unit
* **Ireland**: uses `eircode` instead of `post_code`
### Core Address Fields
[Section titled “Core Address Fields”](#core-address-fields)
* **`country`**: The two letter country code formatted according to [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). Example: `["DE", "GB"]`
* **`street_address`**: The address lines, with each element representing one line. Example: `["Paul-Linke-Ufer 39-40", "2. Hinterhof"]`
### Post code
[Section titled “Post code”](#post-code)
A postal code included in a postal address for the purpose of sorting mail.
The following fields are used for post code, depending on the country:
* **`post_code`** (default): used by most countries. Example: `"10999"`
* **`zip_code`**: used in the United States
* **`eircode`**: used in the Ireland
### Administrative areas
[Section titled “Administrative areas”](#administrative-areas)
The address supports up to 3 levels of administrative areas, `administrative_area_level_1` through `administrative_area_level_3`.
The following fields are used for administrative divisions, depending on the country:
* **`province`** (default): used in some countries for administrative divisions
* **`state`**: used in countries like the United States for the top-level administrative unit
* **`region`**: used in countries like Chile for administrative divisions
* **`county`**: used in countries like Ireland and Romania
* **`autonomous_community`**: used in Spain for the first sub-national level
### Locality levels
[Section titled “Locality levels”](#locality-levels)
The address supports up to 3 levels of locality levels, `locality_level_1` through `locality_level_3`.
For more specific location information:
* **`city`** (default): a city
* **`post_town`**: used in Great Britain instead of city
* **`district`**: a district within a city or region
* **`neighborhood`**: a neighborhood or local area
* **`suburb`**: a suburb or outlying area of a city
* **`village`**: a village or small settlement
* **`municipality`**: a municipality or local government area
## Persons
[Section titled “Persons”](#persons)
A Person is someone who plays some legally relevant role in the Merchant.
### Person Relations
[Section titled “Person Relations”](#person-relations)
Persons can have various roles within a merchant:
* **Legal Representative**: the person legally representing the business towards SumUp
* **Business Owner**: owner of the business (especially for sole traders)
* **Business Officer**: officer of the business (for corporations)
### Person identifiers
[Section titled “Person identifiers”](#person-identifiers)
#### Belgium `BE`
[Section titled “Belgium BE”](#belgium-be-2)
* **Numéro de registre national** `be.nn`\
Numéro de registre national is the Belgian National Registration Number. Every Belgian citizen above the age of 12 has one upon first registration for an ID card. The format is YY.MM.DD-XXX.XX where YY.MM.DD is the birthdate and XXX.XX are a sequential ID and checksum.
#### Brazil `BR`
[Section titled “Brazil BR”](#brazil-br-2)
* **Cadastro de Pessoas Física** `br.cpf`\
Cadastro de Pessoas Física is the Brazilian personal identification number (Cadastro de Pessoas Físicas).
#### Bulgaria `BG`
[Section titled “Bulgaria BG”](#bulgaria-bg-2)
* **Единен граждански номер (Edinen grazhdanski nomer)** `bg.egn`\
Единен граждански номер (Edinen grazhdanski nomer) is the Bulgarian Unified Civil Number (Единен граждански номер) which serves as a national identification number
#### Chile `CL`
[Section titled “Chile CL”](#chile-cl-2)
* **Rol Único Nacional** `cl.run`\
Rol Único Nacional is the Chilean national ID number. For individuals it is used as tax ID. It is therefore the same as the RUT.
* **Número de Documento** `cl.id_card_serial`\
Número de Documento is the Chilean ID card serial number. It identifies the document, not the person. The document number used to be the same as the RUN, but that’s no longer the case.
#### Colombia `CO`
[Section titled “Colombia CO”](#colombia-co-2)
* **Número Único de Identificación Personal** `co.nuip`\
Número Único de Identificación Personal is the personal identification number on the Colombian cédula. The number is the same across all official documents, such as drivers licenses and civil registry documents. The cedula is between 6-10 digits long depending on when it was issued.
#### Cyprus `CY`
[Section titled “Cyprus CY”](#cyprus-cy-2)
* **Δελτίο Ταυτότητας** `cy.identity_card`\
Δελτίο Ταυτότητας is the Cypriot national ID number.
#### Czech Republic `CZ`
[Section titled “Czech Republic CZ”](#czech-republic-cz-2)
* **Občanský průkaz** `cz.civil_card`\
Občanský průkaz is the Czech national ID number
#### Denmark `DK`
[Section titled “Denmark DK”](#denmark-dk-2)
* **Det Centrale Personregister nummer** `dk.cpr`\
Det Centrale Personregister nummer is the Danish personal identification number, the Central Person Register number. It is used for identification purposes.
#### Estonia `EE`
[Section titled “Estonia EE”](#estonia-ee-2)
* **Isikukoodi** `ee.isikukoodi`\
Isikukoodi is the Estonian national ID number.
#### Finland `FI`
[Section titled “Finland FI”](#finland-fi-2)
* **Henkilötunnus** `fi.hetu`\
Henkilötunnus is the Finnish personal identification number, the Henkilötunnus.
#### Hungary `HU`
[Section titled “Hungary HU”](#hungary-hu-2)
* **Személyi igazolvány** `hu.szemelyi`\
Személyi igazolvány is the Hungarian National ID the Személyi igazolvány. It is issued to Hungarian citizens and is used for identification purposes. The Personal ID is not used anymore.
* **Adóazonosító jel** `hu.adoazonosito_jel`\
Adóazonosító jel is the Hungarian personal tax identification number, the adóazonosító jel. It should not be confused with the adószám, the tax number. The difference between the adóazonosító jel and the adószám is that the latter is specifically issued for business purposes of natural and legal persons. The former is a personal identifier that should not be shared, for example on invoices, for privacy reasons. The two do share the same basic format. NOTE: because of this we should not expect to have adóazonosító jel values in our DB and should not collect them.
#### Italy `IT`
[Section titled “Italy IT”](#italy-it-2)
* **Carta d’identità** `it.cie`\
Carta d’identità is the Italian Carta d’Identità Elettronica, the electronic identity card. It is used as personal identification number.
* **Codice fiscale** `it.itax`\
Codice fiscale is the Italian tax identification number for natural and some legal persons. Registered companies use their REA as tax ID. Any entity with a VAT number uses that as tax ID. For natural persons the codice fiscale has 16 alphanumeric characters, for legal persons it has 11. The OECD and Wikipedia describe the format in detail.
#### Latvia `LV`
[Section titled “Latvia LV”](#latvia-lv-2)
* **Personas kods** `lv.personas_kods`\
Personas kods is the Latvian personal identification code (PIC), the Personas kods. Every Latvian citizen has one, and foreigners can get one. The identifier is used for all interaction with the government and serves as personal tax ID. Sole traders may use their PIC for their business. It is an 11 digit number with an optional hyphen after the sixth digit. Before 1. July 2017, the PIC would consist of the date of birth of a person, followed by 5 random digits, withthe blocks separated by a dash.: YYMMDD-XXXXX. PICs issued from 1. July 2017 onward start with the number “3” followed by ten random numbers, also separated by a dash after position six: 3XXXXX-XXXXX. Sources are conflicting regarding the second digit. The EU Commission document on clickworker.com mentions that numbers should start with the digits “32”. The OECD document states numbers start with the number “3”, their example however starts with “38”, while all remaining digits are scrambled to not potentially leak a real number.
#### Lithuania `LT`
[Section titled “Lithuania LT”](#lithuania-lt-2)
* **Asmens tapatybės kortelė** `lt.asmens`\
Asmens tapatybės kortelė is the Lithuanian personal identification number, the Asmens tapatybės kortelė. It is used for identification purposes.
#### Luxembourg `LU`
[Section titled “Luxembourg LU”](#luxembourg-lu-2)
* **Matricule** `lu.matricule`\
Matricule is the Luxembourgian unique identification number for both natural and legal persons. It’s referred to as matricule or “numéro d’identification personnelle” and is used as tax ID. In the case of natural persons the matricule can have 11 or 13 digits. Any numbers issued from 2014 have 13 digits. Legal persons are issued matricules with 11 digits. The format for a natural person is `YYYY MMDD XXX (XX)`, where the first 8 digits are the date of birth of the person. The remaining five digits are “random”. The 12th digit is a Luhn10 check digit. The 13th digit is a de Verhoeff check digit. Both are calculated from the first 11 digits. The format for legal persons is `AAAA FF XX XXX`, where `AAAA` is the year of formation, `FF` is the form of the company, and `XX XXX`are random numbers.
#### Malta `MT`
[Section titled “Malta MT”](#malta-mt-2)
* **Karta tal-Identità** `mt.karta_tal_identita`\
Karta tal-Identità is the Maltese national ID number, the Identity Card Number. It is used for identification purposes.
#### Mexico `MX`
[Section titled “Mexico MX”](#mexico-mx-2)
* **Clave Única de Registro de Población** `mx.curp`\
Clave Única de Registro de Población is the Mexican personal identification number, the Clave Única de Registro de Población. It is used for identification purposes.
* **Régimen Fiscal** `mx.tax_regimen`\
The Tax Regime classifies taxpayers according to their economic activity and tax obligations.
#### Norway `NO`
[Section titled “Norway NO”](#norway-no-2)
* **Fødselsnummer** `no.fodelsnummer`\
Fødselsnummer is the Norwegian national ID number, the Fødselsnummer. It is used for identification purposes. All official IDs, including passports, national ID cards, driving licenses and bank cards contain the National Identity Number.
#### Peru `PE`
[Section titled “Peru PE”](#peru-pe-1)
* **Cédula Única de Identidad** `pe.cui`\
Cédula Única de Identidad is the Peruvian unique identity number that appears on the Documento Nacional de Identidad (DNI), the national identity document of Peru. The number consists of 8 digits and an optional extra check digit.
#### Poland `PL`
[Section titled “Poland PL”](#poland-pl-2)
* **Powszechny Elektroniczny System Ewidencji Ludności** `pl.pesel`\
Powszechny Elektroniczny System Ewidencji Ludności is the Polish national ID number, the Powszechny Elektroniczny System Ewidencji Ludności. The number consists of the date of birth, a serial number, the person’s gender and a check digit.
#### Portugal `PT`
[Section titled “Portugal PT”](#portugal-pt-2)
* **Cartão de Cidadão** `pt.cc`\
Cartão de Cidadão is the Portuguese citizen card number, the Cartão de Cidadão. It is alphanumeric and consists of the numeric Número de Identificação Civil, a two-letter version and a check digit. Format: DDDDDDDD C AAT - DDDDDDDD: Número de Identificação Civil \[0-9] - C: Check digit \[0-9] - AA: Two-letter version \[A-Z, 0-9] - T: Check digit \[0-9]
#### Romania `RO`
[Section titled “Romania RO”](#romania-ro-2)
* **Codul numeric personal** `ro.cnp`\
Codul numeric personal is the Romanian unique identification number for individuals, the Cod numeric personal. The CNP is issued for residents by the Ministry of Internal Affairs. It also serves as tax identification number for natural persons, in particular for sole traders and similar legal types that do not register with the Trade Registry. The CNP consists of 13 digits, the last of which is a check digit (see wikipedia).
#### Slovakia `SK`
[Section titled “Slovakia SK”](#slovakia-sk-2)
* **Rodné číslo** `sk.rc`\
Rodné číslo is the Slovak Republic’s birth number, the Rodné číslo. The birth number is the Slovak national identifier. The number can be 9 or 10 digits long. Numbers given out after January 1st 1954 should have 10 digits. The number includes the birth date of the person and their gender
#### Slovenia `SI`
[Section titled “Slovenia SI”](#slovenia-si-2)
* **Enotna matična številka občana (Unique Master Citizen Number)** `si.emso`\
Enotna matična številka občana (Unique Master Citizen Number) is the Slovenian personal identification number, the EMŠO. The EMŠO is used for uniquely identify persons including foreign citizens living in Slovenia. It is issued by Centralni Register Prebivalstva CRP (Central Citizen Registry). used for identification purposes. The number consists of 13 digits and includes the person’s date of birth, a political region of birth and a unique number that encodes a person’s gender followed by a check digit.
#### Spain `ES`
[Section titled “Spain ES”](#spain-es-2)
* **Número de Identificación de Extranjero** `es.nie`\
Número de Identificación de Extranjero is the Spanish tax ID for foreign nationals, the Número de Identificación de Extranjero.
* **Documento Nacional de Identidad** `es.dni`\
Documento Nacional de Identidad is the Spanish national ID number, the Documento Nacional de Identidad. It is used for Spanish nationals. Foreign nationals, since 2010 are issued an NIE (Número de Identificación de Extranjeros, Foreigner’s Identity Number) instead.
#### Sweden `SE`
[Section titled “Sweden SE”](#sweden-se-2)
* **Personnummer** `se.pn`\
Personnummer is the Swedish personal identity number number, the personnummer. It is issued at birth, or at registration. The personnummer is used as tax identification number. The personnummer has 10 digits and should pass luhn’s checksum algorithm. The first six or eight digits are the date of birth of a person, i.e. YYMMDD or YYYYMMDD. The In case the specific day is out of birth numbers, another day (close to the correct one) is used. They are followed by a hyphen, and four final digits. The year a person turns 100 the hyphen is replaced with a plus sign. Among the four last digits, the three first are a serial number. For the last digit among these three, an odd number is assigned to males and an even number to females.
#### United States `US`
[Section titled “United States US”](#united-states-us-2)
* **Social Security Number** `us.ssn`\
Social Security Number is the United States social security number. It is used for taxation of natural persons, like sole traders. From Wikipedia: > The SSN is a nine-digit number, usually written in the format `AAA-GG-SSSS`. > The number has three parts: the first three digits, called the area number because > they were formerly assigned by geographical region; the middle two digits, the > group number; and the last four digits, the serial number.