Back to top

Quickstart

SumUp strives to provide you with a smooth experience for you and your clients. You need just 3 steps to see how easy it is to start processing payments on your merchant’s behalf.

Step 1. Register platform

To get started with your integration, you need to register at https://sumup.com/.

As a next step, you need to set up your consent screen and client credentials at https://me.sumup.com/developers.

The consent screen will be shown to users whenever you request access to their private data using your client ID.

In order to create client credentials, you need to submit the application type, client name and redirect URI in the following screen. A unique client_id will be generated which will be used later to authorize the application.

Step 2. Connect merchant to platform

SumUp uses OAuth flow for onboarding accounts and providing access to its API.

To start with the integration, you would need to have client_id - a unique identifier generated by SumUp, and redirect_uri that you had already provided in the setup and would like SumUp to redirect your merchants to.

In order for you to be able to process payments on your merchants’ behalf, they need to be onboarded on SumUp. You need to direct them to the following URI using your platform’s client_id.

https://api.sumup.com/authorize?scope={SCOPE}&response_type=code&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&state={STATE}

The scope parameter is optional. If you do not provide it, we will enable the default set of scopes. If you need any scope outside the default ones, you have to contact us to enable this for you.

The state parameter is optional, although it is recommended to provide a unique token as its value in order to prevent CSRF attacks. SumUp will send back the state you provided when we send the user back to your redirect_uri address.

After the merchant has authenticated with SumUp and the application is authorized for the requested scopes, SumUp sends the merchant back to your application’s redirect_uri address and provides an authorization_code and state, if provided.

The authorization code is then used to request access and refresh tokens.

curl https://api.sumup.com/token \
   -d grant_type=authorization_code \
   -d client_id=”{CLIENT_ID}” \ 
   -d client_secret=”{CLIENT_SECRET}” \ 
   -d redirect_uri=”{REDIRECT_URI}” \ 
   -d code="{AUTHORIZATION_CODE}"

The response includes the access token, which you will need in Step 3.

{
  "access_token": "{ACCESS_TOKEN}",
  "token_type": "Bearer",
  "expires_in": 3600
  "refresh_token": "{REFRESH_TOKEN}"
}

Step 3. Initiate payment

In order to create a payment checkout, you need to use the access_token received in the previous step and pass it in a Server-to-Server communication call in the header of the request. Specify the merchant email to receive the payment in pay_to_email.

curl https://api.sumup.com/v0.1/checkouts \
   -H "Content-Type:application/json" \
   -H "Authorization:Bearer {ACCESS_TOKEN}" \
   -d \
   '{"amount": XXX.XX, 
     "currency": "EUR",
     "pay_to_email": "{PAY_TO_EMAIL}",
     "checkout_reference": "{CHECKOUT_REFERENCE}",
     "description": "{DESCRIPTION}"
   }'

If the request was successful, you will receive the id of the checkout which then must be used to complete the checkout.

SumUp provides flexibility to complete a checkout by offering different integration approaches. Once you complete the checkout, you would have processed a payment on the merchant’s behalf.

Checkout flow

The checkout flow described below enables applications to create a checkout and process card payments in a browser or a native application such as a mobile application.

Checkouts are created in a server to server communication. This allows to

  • Keep your access token and client credentials secret.

  • Prevent changes of your web based checkout properties. For example, amount or recipient.

Checkouts are processed by the client (in a browser in the case of web application). This guarantees that

  • No sensitive (card data) ever hits your server.

  • You don’t need to worry about PCI compliance.

  • You are in full control of the UI, thus giving the best user experience to your customers.

Creating a checkout

A new checkout is created in a server-to-server communication between your Server and SumUp. Therefore the amount of the checkout cannot be altered in the frontend after it’s been created.

The following is an example curl request:

curl -i -X POST \
-H "Content-Type:application/json" \
-H "Authorization:Bearer YOUR_ACCESS_TOKEN" \
-d \
'{"amount": XXX.XX, 
    "currency": "EUR",
    "pay_to_email": "MERCHANT_EMAIL",
    "checkout_reference": "YOUR_UNIQUE_REFERENCE",
    "description": "YOUR_DESCRIPTION"
}' \
'https://api.sumup.com/v0.1/checkouts'
  • Authorization- Access token created when authorised by merchant

Refer to the checkouts API for full details of the create checkout request and response.

If successful, the following response will be received:

{ 
  "id": "CHECKOUT_ID",
  "checkout_reference": "YOUR_UNIQUE_REFERNCE"
  "status": "PENDING",
  ...
}
  • id- used when completing the checkout

  • status - Pending until the checkout is completed

Completing a checkout

The checkout you created in a server to server communication can be completed in your mobile or web app. You are free to go with a custom integration checkout or embed the SumUp checkout form.

Note that a checkout can be completed in a browser only from a domain that is present in your OAuth setup as an authorized javascript origin(s).

SumUp Checkout

Alternatively you can complete a checkout by using a checkout form provided by SumUp. It will automatically handle all the details as building a custom payment form, validating the user input or make a call to complete a checkout. The only thing that you need to bother with is to handle the result of the checkout. The checkout form is completely white labelled and straightforward to integrate.

Start typing to try it on your own

 

To integrate the checkout form you need a few lines of code in your html page

<!-- the place it will appear-->
<card></card>
<!-- the form js library-->
<script src="https://gateway.sumup.com/gateway/card.js"></script>
<script>
    //render the form ui providing a configuration object
    PaymentCard.mount({checkoutId: "..."});
    //listen to checkout processing result and handle it
    PaymentCard.on('checkout:paymentResult', function(data) {
        //TODO: handle the checkout result
    })
</script>

The checkout form is fully customizable. To do so you can provide a configuration to PaymentCard.mount method. All the possible configuration properties with their default values are listed bellow. The only required field is checkoutId without which the checkout cannot be completed.

{
  "checkoutId": "...", //Id of the checkout to be completed (Required).
  "fields_placeholders": {
    "card_number": "Card number",
    "cvv": "CVV",
    "expiry_date": "Expiry date",
    "cardholder_name": "Cardholder name",
    "pay_now": "Pay"
  },
  "card_placeholders": {
    "number": "•••• •••• •••• ••••",
    "name": "Cardholder name",
    "expiry": "••/••••",
    "cvc": "•••"
  },
  "card_messages": {
    "validDate": "valid/date",
    "monthYear": "mm/yyyy"
  }
}

By providing a specific configuration you can easily localize and customize the form.

The checkout result handler is a function that is called with an object presenting the checkout processing result. See Checkout API document for description of the checkout response.

It is recommended that your checkout processing result handler sends the result to your backend which verifies the checkout result before showing any status to the end user.

Custom integration Checkout

In this scenario it is up to you to build a payment form and send the user input to SumUp in order to complete a pending checkout created on your server. There are three options for payment with a custom integration:

  • Customer entered credit card

  • Tokenized credit card

  • Merchant balance

Customer entered credit card

The request should be made from a client only, and not from a server. In a browser this can be done by an ajax request, like:

PUT /v0.1/checkouts/:id

{
  "payment_type":"card",
    "card": {
        "cvv": "...",
        "expiry_month": "01",
        "expiry_year": "2016",
        "number": ".......",
        "name":"...."
    }
}

Check the Checkout API documentation for complete details of the request and response from the checkout call.

CORS requests are possible if you have correctly set cors origins in your OAuth setup and the checkout was created by a client with that setup.

Tokenized Cards

If you have already created a customer and tokenized a card, then the checkout can be completed with a token. This request can be made server side as the card data has already been collected, or from a web application as only the client id is used for authorization.

The following is an example curl request:

curl -i -X PUT \
-H "Content-Type:application/json" \
-d \
'{"payment_type": "card", 
    "token": "VALID_CARD_TOKEN",
    "customer_id": "YOUR_CUSTOMER_ID"
 }' \
'https://api.sumup.com/v0.1/checkouts/:id'

Merchant Balance

Merchants can also be enabled to pay with the balance of their SumUp account, please contact integration@sumup.com for more information.

Card on File

Creating a customer

A customer is associated with your application, and can be used to make a payment to any merchant who has authorised the application to take payments on it’s behalf.

The following is an example curl request without any personal_details:

curl -i -X POST \
-H "Content-Type:application/json" \
-H "Authorization:Bearer VALID_ACCESS_TOKEN" \
-d \
'{"customer_id": "YOUR_CUSTOMER_REFERENCE" 
 }' \
'https://api.sumup.com/v0.1/customers'
  • authorization - Bearer and access_token created using client credentials grant

  • customer_id - Unique id generated by your application

Check the Customers API documentation for complete details of the request and response from the customers call.

If the request is successful, the customer data will be echoed in the response.

Tokenizing a card

Once a customer has been created, cards can be tokenized and added as payment instruments. This token can then be used to complete a checkout.

An authorization of 1.00 in the currency of the card will be processed and then reversed in order to verify the card.

curl -i -X POST \
-H "Content-Type:application/json" \
-H "Authorization:Basic BASE64_ENCODED_CLIENT_ID" \
-d \
'{"type": "card",
  "card": {
    "name": "CARDHOLDER_NAME",
    "number": "CARD_NUMBER",
    "expiry_month": "EXP_MONTH_DIGITS",
    "expiry_year": "EXP_YEAR_TWO_OR_FOUR_DIGITS"
    "cvv": "CVV"
  }
 }' \
'https://api.sumup.com/v0.1/customers/:customer_id/payment-instruments'
  • authorization - Basic and Base64 encoded client_id which enables the request to be made from non-trusted clients like web or mobile applications

  • customer_id - Unique id generated by your application representing the customer

  • type - card

Check the Payment Instruments API documentation for complete details of the request and response from the payment instruments call.

If the request is successful the following will be returned:

{
  "token": "...",
  "active": true,
  "type": "...",
  "card": {
    "last_4_digits": "...",
    "type": "..."
  }
}
  • token - token to be used when completing a checkout with this payment instrument

  • active - Each customer can have up to 4 active payment instruments using the payment instruments API

  • type - card

Subscriptions

Subscription services can achieved using recurring payments, performed by completing a checkout with a tokenized card at the frequency required.