SumUp SDK & API Integration

Connect your app to the most powerful payment platform and card terminals in the world.

  • Introduction

    Access a complete Card Payment solution from your own app, with full PCI & EMV certifications, mobile point of sales technology and card readers.

    • Card Payments SDK - Allows your app to access SumUp's back end and process payments with little integration effort.
    • Transaction History API - Provides real time transaction status and transaction history reporting.
    • Electronic Receipts Solution - Send electronic EMV receipts to your clients via SMS or email.

    Glossary

    End Customer

    The customer of the merchant (i.e. the card holder), who pays the merchant with a card or through mobile payment.

    Affiliate Key

    The SumUp Affiliate Key allows you to use the Payment API, the SDKs (iOS & Android) and RESTful APIs. Please note, the Affiliate Key is part of your authentication and designed to protect your data from unauthorized use. It is in your best interest to protect this information from access by unauthorized individuals. To get your SumUp Affiliate Key, please create a SumUp merchant account and once you've logged in, you will be able to provide your app bundle identifier in the developers menu and receive your Affiliate Key.

    Card Terminal(s)

    Any of SumUp’s range of devices, including the “Magtripe & Signature, the “Chip & Signature, the combined “Chip/magstripe & Signature as well as the Chip & PIN device, called PIN+.

    Partner

    This is you; the merchant will use your third-party app in order to accept payments via the SumUp Checkout Flow and the SumUp Card Terminal (e.g. a taxi driver app, cash register app, etc.)

    Merchant

    This is the merchant using the integration partner app to RECEIVE a payment (e.g. the taxi driver or the restaurant waiter charging a customer). In short, the merchant is the user of your app.

    Payment Option

    SumUp offers merchants and partners the opportunity to use different payment options, through SumUp's apps and SDKs. These payment options include SumUp’s various Card Terminals, mobile payments, bitcoin, and cash. Available payment options depend on the merchant’s country. You can see the available payment options when making a checkout attempt in the SumUp app.

    Payment Instrument

    This is usually an end customer’s credit or debit card, but could also be Bitcoin, cash, or a third-party wallet.

    SumUp App

    SumUp’s standard merchant app that can be downloaded from the Apple AppStore or from the Google Play Store.

    SumUp Merchant Account

    In order to use our payment acceptance service, the merchant needs to have a SumUp Merchant Account. This account is created by signing up to our service (merchant onboarding). Once the merchant passes our KYC and AML checks (most of which will be conducted “in the background”, transparent to you and the merchant), we enable the Merchant Account to accept card payments. Please note, that we reserve the right to revisit and request additional information from the merchant.

    Get Started — Quick Guide

    1. Read this documentation
    2. Register an account at sumup.com, once logged in go to “Developers”
    3. Provide your app’s bundle ID, obtain your Affiliate Key and download (if applicable) our Android or iOS SDK
    4. Integrate the SDK or Payment API into your app, optionally also our Transaction Reporting APIs
    5. Enable your merchants to accept card payments in the easiest way possible
    6. In case you have any questions during the process, do not hesitate to write us at integration@sumup.com
  • Terminal Payment SDK

    To integrate SumUp’s proprietary Card Terminal(s) and our Payment Platform into your app, we provide you with a native iOS or Android SDK. Our SDKs provide the following functionalities:

    Communication with terminal

    The SDK handles all communication with SumUp’s Card Terminal(s) transparently. The communication is controlled through either Bluetooth or audio libraries. The PIN+ Terminal connects to your Android or iOS app via Bluetooth Low Energy (BLE 4.0) or via cable connection through the headphone/audio jack. The Chip/Magstripe & Signature Card Readers connect through the headphone/audio jack only.

    Dynamic checkout

    This will correspond to the checkout process in the SumUp App. The applicable screens will be pushed from SumUp's backend to your app. The checkout process will be triggered by your app and we will return the transaction result with all relevant data at the end of the transaction. The transaction itself is transparent to you.

    Transaction status

    After the completion of a transaction, a unique transaction ID, payment receipt details, as well as the current transaction status “transaction successful”, “transaction failed” or “transaction timeout” will be passed back to you and can be stored there for reporting purposes.

    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 with all relevant certificates of the credit card industry (PCI, EMV I & II, Visa, MasterCard & Amex).

    Authentication

    Your app will authenticate itself with the Affiliate Key provided by SumUp. To get your Affiliate Key, please create a SumUp Merchant Account and after logging in, you will be able to provide your app bundle identifier in the “Developers” menu and receive your Affiliate Key. In addition, the Merchant will have to log in with his SumUp Merchant Account.

    iOS SDK

    The iOS SDK is documented and published on Github.

    Android SDK

    The Android SDK is documented and published on Github.

  • The Payment API

    The Payment API is designed for a very easy and quick implementation. It allows your app to start the checkout flow inside the native SumUp App, which will also have to be installed on your merchant’s phone or tablet. Your app can manage everything including the creation of the total amount to be charged by your merchant. When your merchant clicks the checkout button in your app, your app will define a payment request object, using the parameters supported by our API which include the total billing amount. Those parameters will then be passed by your app to the SumUp App via the Payment API. The Payment API is a part of the SumUp App, so that neither your app nor your backend will have to be connected to SumUp’s Backend.

    Your app will need an Affiliate Key to connect to the Payment API. Once the SumUp App receives the Payment API request it will be pushed into the foreground on your merchant’s phone or tablet and your app will be in the background. Your merchant will follow the checkout process inside the SumUp App, that way the SumUp App can manage the communication with the Card Terminal and your app does not need to manage this communication. On completion of the transaction, the SumUp App will return the result to those callback URLs in your app as supplied in the original request. Your merchant may have to select the appropriate Payment Option before being able to complete the transaction with the end-customer’s Payment Instrument.

    iOS Payment API

    The iOS Payment API is documented and published on Github.

    Android Payment API

    The Android Payment API is documented and published on Github.

  • Merchant Onboarding

    Every merchant wanting to use SumUp Payment Services must sign up and create a SumUp Merchant Account due to anti-money laundering (AML) regulations. SumUp needs to ensure a so-called “Know-Your-Customer (KYC) process is conducted. Signing up for SumUp takes less than 5 minutes and can be easily done online on the SumUp Homepage. This process is called “onboarding”.

    Our basic signup is described below under the Standard Sign-Up section. If you are interested in deepening our cooperation, we can also offer you additional services such as co-branded sign-up or an on-boarding API. Please contact us at integration@sumup.com, should you be interested in discussing these.

    Please go ahead and do a sign-up in order to access our SDK documentation kit.

    Standard Sign-Up

    We designed our sign-up flow as user-friendly and short as possible, while also complying with all required AML and KYC checks. You are required to do a sign-up in order to access to the SDK and affiliate keys, it will only take 5 minutes. The following information is needed to complete the sign-up:

    • Email address (E-Mail-Adresse)
    • Password (Passwort)
    • Legal type of registered business (Rechtsform)
    • Business Type of registered business (Geschäftskategorie)
    • Company name of registered business (if available) (vollständiger Geschäftsname)
    • Website of registered business (Webseite)
    • First name (Vorname)
    • Last name (Nachname)
    • Date of Birth (Geburtsdatum)
    • Street and Number (Strasse und Hausnummer)
    • Street and Number 2 (Adresszusatz)
    • Zip code (PLZ)
    • City (Stadt)
    • Country (Land)
    • Private Address = place of business yes/no (otherwise second address same fields as above)
    • Mobile phone (Handynummer)
    • Landline (Festnetznummer) (optional)
    • Bank account number (Kontonummer)
    • Sort code (Bankleitzahl)

    Co-branded Sign-up flow

    We understand that your brand is important to you. For many of our SDK partners, our standard sign-up flow is sufficient to get their merchants ready for card acceptance quickly. Yet, for some partners that onboard a larger number of merchants, but do not want to go through the full integration of our onboarding API, we offer a fully web-based co-branded signup flow including your logo and customized text, for example: https://sumup.de/gastrofix. Just approach us by sending an email to integration@sumup.com in order discuss this sign-up option.

    Onboarding API

    This is the Big Kahuna of sign-up and onboarding experience for your merchants. In essence, your merchants do not have to re-enter all their data mentioned above to register, but SumUp will import the entered data from your database directly.

    So, the onboarding API connects your merchant database to SumUp’s Signup Flow. You will be allowed to “automatically onboard” existing and new merchants of your solution. It can go as far, that when a merchant signs up for your service he can choose to sign up for SumUp at the same time! How cool is that!

    From a legal point of view, your merchant needs to agree to our terms and conditions (ideally in your sign-up flow). After accepting SumUp’s T&Cs, all merchant data-fields (available in your database) will be submitted from your backend to SumUp’s backend through the Onboarding API. This request will create a SumUp ID, which will be passed back to your backend. Depending on the data fields that were imported and the grade of integration, the registration of your merchant is already done at this stage, or the merchant will have created a SumUp Account but still needs to fill out some fields in the web-based SumUp Merchant Dashboard, which can be accessed under “Log in” on the SumUp Homepage.

    The process to order a card terminal can either be integrated in your sign-up flow or the merchant can order it through their web-based SumUp Merchant Dashboard. For more information, please contact us at integration@sumup.com.

    Other Onboarding Services

    Reader distribution & shipment

    The merchant can order a SumUp Card Terminal during the sign-up flow or any time through their web-based merchant dashboard which can be accessed under “Log in” on the SumUp homepage. The card terminals are then shipped within 2 days - so your merchants should be ready to go in no time.

    Personalized voucher code

    Once you have at least ten active merchants running on our SDK or API switch, we are happy to offer special personalized voucher codes to support you in your marketing efforts. For more information, please contact us at integration@sumup.com.

  • APIs

    Overview

    The SumUp API is built following REST style guidelines. The format of the requests and responses is JSON. Although few endpoints are currently exposed (see Transaction Reporting APIs), they provide exhaustive information about your transactions and can be used for automating features like transaction history, receipts information and transactions status reporting.

    Authentication

    The APIs access requires authentication. The following header should be included in a valid request:

    
                Authorization: Bearer valid_access_token
                

    Obtaining an access token example:

    
    curl https://api.sumup.com/oauth \
        -d'{"username":"...","password":"...","client_id":"...","client_secret":"..."}' \
        -H'Content-Type: application/json'
                
    Authentication request fields:

    Field

    Description

    username *

    The username registered along with obtaining an Affiliate Key

    password *

    User password

    client_id *

    User application ID

    client_secret *

    User Affiliate Key

    * — Required.

    The obtained access token will have a TTL of 3600 seconds, after which it will be considered invalid. The expire time of an access_token can be obtained with the following request:

    
    curl https://api.sumup.com/session-info \
        -H'Bearer: Authorization valid_access_token'
                

    See How do I get an Affiliate Key and the SDK

    Transaction Reporting APIs

    GET /v0.1/me/transaction-history

    Returns a paginated list of all transactions of the currently authenticated SumUp Account. The default pagination parameter is 100 and can be adjusted. Use the next link sent in the response to get to the next page until you receive a blank.

    Query parameters

    Field

    Description

    start_time *

    Start time in milliseconds or iso format (YYYY-MM-DD)

    end_time *

    End time in milliseconds or iso format (YYYY-MM-DD)

    geo_coordinates

    This parameter allows you to only retrieve transactions that were made within a box of coordinates: use CSVs of southwest_lng, southwest_lat, northeast_lng, northeast_lat

    reader_sn

    Allows filtering of transactions that were made with a certain reader serial number

    status

    Filter transactions by status. Possible values: SUCCESSFUL, CANCELLED, FAILED

    type

    Filter transactions by type. Possible values: CASH, POS, ECOM

    limit

    Number of results for pagination. Default 100

    include_operators

    In case you have sub-accounts, you can supply here a list of them in the form of email-addresses so that SumUp will only include transactions made by those accounts in the result. If this parameter is not submitted, transactions of the master-account and all sub-accounts (if any) will be returned.

    * — Required.

    GET /v0.1/me/transactions

    This resource fetches all transaction information for a given transaction identifier. Identifier can be one of the following

    Query parameters

    Field

    Description

    transaction_code

    SumUp transaction code.

    foreign_transaction_id

    External transaction identifier passed to the payment SDK

    Staff accounts APIs

    GET /v0.1/me/accounts

    Returns a list of all staff accounts

     

    POST /v0.1/me/accounts

    Creates a new staff account

    Staff account request fields:

    Field

    Description

    username *

    The username of the staff account

    password *

    The password of the staff account

     

    PUT /v0.1/me/accounts/:id

    Change a staff account. Actually applies to password.

    Path parameters:

    Field

    Description

    id *

    Id of the staff account

    Request parameters:

    Field

    Description

    password *

    The new password to be set for the staff account

     

    DELETE /v0.1/me/accounts/:id

    Disable staff account

    Path parameters:

    Field

    Description

    id *

    Id of the staff account

    Return types

    Transaction History

    Name

    Type

    Description

    transactions

    Transaction

    Collection of transactions

    links

    Link

    Collection of links as next page link

    Transaction

    Name

    Type

    Description

    id

    String

    Transaction id

    transaction_code

    String

    Transaction code (short id)

    amount

    BigDecimal

    Transaction amount

    currency

    String

    Transaction currency

    timestamp

    Time

    Time created

    lat

    Float

    Latitude

    lon

    Float

    Longitude

    horizontal_accuracy

    Float

    Position precision

    merchant_id

    Integer

    Merchant id

    device_info

    Device

    Device info

    status

    String

    Transaction processing status

    payment_type

    String

    Transaction type

    entry_mode

    String

    Transaction entry mode

    verification_method

    String

    Cardholder verification method

    card_reader

    CardReader

    Card reader details

    card

    Card

    Card information

    elv_account

    ElvCardAccount

    Elv bank account

    product_summary

    String

    Product summary

    local_time

    Time

    Creation time in the timezone of the device on which the transaction was made

    payout_date

    Date

    The date of the payout

    products

    TransactionProduct

    Collection of Purchase products

    transaction_events

    TransactionEvent

    Collection of transaction events such as payouts, refunds and chargebacks

    simple_status

    String

    Simple status generated from processing status and latest transaction state

    links

    Link

    A list with links to related resources such as receipts

    Transaction Event

    Name

    Type

    Description

    event_type

    String

    Type of the transaction event. Possible values: PAYOUT, CHARGE_BACK, REFUND

    status

    String

    Status of the event

    amount

    BigDecimal

    Amount

    due_date

    Date

    The date when the event is due to occur

    date

    Date

    The date when this event occurred

    installment_number

    Integer

    The number of installment that was payed out in case of a PAYOUT event

    Product

    Name

    Type

    Description

    name

    String

    Product name

    price

    BigDecimal

    Product price

    vat_rate

    BigDecimal

    vat_amount

    BigDecimal

    quantity

    Integer

    Product quantity

    Card

    Name

    Type

    Description

    last_4_digits

    String

    Card last 4 digits

    type

    String

    Card Scheme

    token

    String

    Token ID of these card details

    Elv Card Account

    Name

    Type

    Description

    sort_code

    String

    Elv card sort code

    last_4_digits

    String

    Elv card account number last 4 digits

    Card Reader

    Name

    Type

    Description

    code

    String

    Reader serial number

    type

    String

    Reader type

    Device

    Name

    Type

    Description

    name

    String

    system_name

    String

    Device os

    model

    String

    Model

    system_version

    String

    Version

    uuid

    String

    Link

    Name

    Type

    Description

    rel

    String

    Relation

    href

    String

    Location

    type

    String

    Mime type

  • Miscellaneous

    Supported operating systems

    In order to use SumUp’s Card Terminal “PIN+ with Bluetooth Low Energy (recommended) your merchants will need a smartphone or tablet that supports Bluetooth 4.0 and runs on one of the following operating systems: Apple iOS 7.0 or higher / Android 4.3 or higher. The PIN+ audio connection and the Chip/Magstripe & Signature Reader also support payments for older smartphones from Apple iOS 5.0 and up, as well as Android 2.3.7 and up.

    Supported Card Readers

    Your SumUp integration supports all SumUp Card Terminals and Readers. When the documentation refers to a SumUp Card Terminal, it applies to the following:

    • PIN+, SumUp’s proprietary Chip & Pin Terminal (supports transactions via chip or magnetic stripe)
    • EMV Chip & Sign Reader (supports transactions via chip only)
    • EMV Chip/Magstripe & Sign Reader (supports transactions via chip and magstripe)
    • Encrypted Magstripe Reader (supports transactions via magnetic stripe only)

    Supported phones

    SDK is available for small as well as large screen devices running on iOS or Android, you can find a full list here: https://sumup.co.uk/check-device

    Supported currencies

    EUR, GBP, USD, BRL, CHF, PLN, SEK

    Supported countries

    SumUp currently supports the following countries:

    • Austria
    • Belgium
    • Brazil
    • France
    • Germany
    • Ireland
    • Italy
    • Netherlands
    • Poland
    • Portugal
    • Spain
    • Sweden
    • Switzerland
    • United Kingdom
    • United States of America

    Supported payment options

    The SumUp PIN+ Terminal supports the following card types: MasterCard, Maestro, Visa, VPay, American Express**. The SumUp Chip & Signature Card Reader supports the following card types: MasterCard, American Express**, Visa (Brazil only), EC-Cards (Germany only)

    ** American Express acceptance currently not available in the following markets: Belgium, Ireland, Poland, and Portugal.

    Contact Details SumUp

    SumUp has offices across Europe as well as in Brazil. We are headquartered in London and Berlin. In case you have any questions please do not hesitate to contact us at integration@sumup.com or visit us at our offices

    How do I get an Affiliate Key and the SDK

    You can generate the SumUp Affiliate Key and download the SumUp iOS and Android SDKs onced logged in to a SumUp Website. Just create a regular SumUp Merchant Account (sign up as sole trader and choose your country (country determines currency) - you do not have to provide your bank details, but if you do, we will settle your test transactions (minimum transaction EUR 1) back to you), it literally takes minutes, and log into the merchant web interface, where you will be asked to provide your app bundle identifier. After providing your app bundle identifier, a SumUp Affiliate Key will be generated and you can download the SDKs.

Partners