Payment Widget

SumUp provides a payment widget for easier processing of checkouts on your website.

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.

Compliance

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

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

In order to integrate the payment widget on your website, you simply need to include the sdk.js script on your payment page.

<script src="https://gateway.sumup.com/gateway/ecom/card/v2/sdk.js"></script>

Once the script is loaded you have access to a global variable SumUpCard, that has a mount method which renders the available payment methods.

You need the following lines of code to integrate the payment form to your web page. First create a checkout and use the returned id from the response in the code below. 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.

<div id="sumup-card"></div>
<script
  type="text/javascript"
  src="https://gateway.sumup.com/gateway/ecom/card/v2/sdk.js"
></script>
<script type="text/javascript">
  SumUpCard.mount({
    id: 'sumup-card',
    checkoutId: '2ceffb63-cbbe-4227-87cf-0409dd191a98',
    onResponse: function (type, body) {
      console.log('Type', type);
      console.log('Body', body);
    },
  });
</script>

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 use other than the default ones, you should provide them to the SumUpCard.mount method.

SumUpCard.mount({
  checkoutId: '...',
  // 'config-name': 'config-value'
});

* Installments are available only to merchant users in Brazil.
** ZIP code is required only for merchant users in the USA.

Methods

Alternative Payment Methods

Depending on the country a merchant is registered in, Alternative Payment Methods (APMs) are available for accepting payments from your customers. Please note, the show* configuration properties from the widget 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.

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:

[data-sumup-id='widget__container'] {
  color: red;
  line-height: 18px;
}

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}.

[data-sumup-id='payment_option'][data-sumup-item='blik'] {
  display: none;
}

Using your own submit button

If you need to use your own submit button you can achieve this by following the example below:

<button id="custom-submit-button" class="custom-button">Pay your order</button>
<script type="text/javascript">
  document.addEventListener('load', function () {
    var sumupCard = SumUpCard.mount({
      checkoutId: '2ceffb63-cbbe-4227-87cf-0409dd191a98',
      onResponse: function (type, body) {
        console.log('Response from client', res);
        // Verify the checkout is processed correctly.
        // Display success message to the user and destroy the SumUpCard object:
        sumupCard.unmount();
      },
      showSubmitButton: false,
    });
  });
  document
    .getElementById('custom-submit-button')
    .addEventListener('click', function (event) {
      sumupCard.submit();
    });
</script>

Handling strict Content Security Policies

Pages with strict Content Security Policies (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:

Required Configurations

In order to properly render the card widget with CSP in place, you must whitelist the following URLs for your application:

Additionally to the above, nonce is required to make inline styles work on your host page. For more information view the CSP docs.

Here’s an example implementation with nonce:

const express = require('express');
const app = express();
const http = require('http');
const server = http.createServer(app);

const port = process.env.PORT || 4000;

const crypto = require('crypto');

// Resources
const apisToConnect = ['https://gateway.sumup.com', 'https://api.sumup.com'];

const imagesResources = [
  'data:', // inline icons
  'https://static.sumup.com',
  // For generated barcodes

  'https://api.sumup.com',
];

const scriptsResources = [
  'https://gateway.sumup.com',
  // PLUS nonce-$HASH
];

const stylesResources = [
  // nonce-$HASH
];

const framesResources = ['https://gateway.sumup.com'];

app.get('/', (req, res) => {
  const nonce = crypto.randomBytes(16).toString('base64');
  res.setHeader(
    'Content-Security-Policy',
    `default-src 'self';` +
      ` connect-src 'self' ${apisToConnect.join(' ')};` +
      ` img-src 'self' ${imagesResources.join(' ')};` +
      ` script-src 'self' ${scriptsResources.join(' ')} 'nonce-${nonce}';` +
      ` style-src 'self' 'nonce-${nonce}';` +
      ` frame-src 'self' ${framesResources.join(' ')};`,
  );

  // <script type="text/javascript" src="http://localhost:8003/sdkv2.js"></script>
  res.send(`
    <h1>Test CSP</h1>
    <div>Test using generated nonce: ${nonce}</div>
    <div id="sumup-card"></div>
    <script type="text/javascript" nonce="${nonce}">
      (window.SumUpPayment).mount({
        nonce: "${nonce}",
        checkoutId: '7538e178-c8c1-43a1-8eef-c29ab608edd1',
        onResponse: function(type, body) {
          console.log('Type', type);
          console.log('Body', body);
        }
      });
    </script>
    <a href="/without-nonce">See without nonce</a>
    <div>Footer</div>
 `);
});

server.listen(port, () => {
  console.log('listening on:', port);
});

If you continue to experience issues with rendering the payment widget, reach out to our support through this contact form.