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.

You can experience the payment widget‘s functionality by using the interactive demo below (no real charges will occur)

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'
});
NameDescriptionValueDefault ValueRequired
checkoutIdThe unique ID you receive once you create a checkout.stringno default valueyes
onResponseThe 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 on your server. The second parameter contains the response from the endpoint.
  • fail - failed result returned by the checkout endpoint, can occur when the user cancels the payment form or the session has timed out.
functionnullno
onLoadThe callback function that will be called when the card widget is loaded.functionnullno
onPaymentMethodsLoadThe 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'];
functionnullno
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).functionnullno
showSubmitButtonDisplays or hides the form's submit button.booleantrueno
showFooterDisplays or hides "Powered by SumUp" label.booleantrueno
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.booleanfalseno
showZipCode**Displays or hides ZIP code input field. It is mandatory for merchant users from USA.booleanfalseno
showEmailDisplays or hides email input field. At some time in the future it'll be a mandagory field for every integrator because of the SCA.booleanfalseno
emailAlternative 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.stringnullno
installments*The number of installments with which the transaction should be processed.number
[1 .. 12]
nullno
maxInstallments*The maximum amount of installments in the selector displayed by the widget.number
[1 .. 12]
12no
idid of the element that you wish to render the card widget in. Example: <div id="sumup-card"></div>string"sumup-card"no
donateSubmitButtonChanges the text of the submit button to "Donate".booleanfalseno
amountThe amount you want to be displayed on the submit button. Requires currency and locale to take effect.stringnullno
currencyThe 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"nullno
localeTranslates 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
countrySets 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"nullno
googlePayRequired for accepting payments with the widget via Google Pay:
  • merchantId is a value provided by Google after 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.
{merchantId: string, merchantName: string}nullno

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

Methods

NameDescriptionParametersReturn Type
mountInitializes and renders the payment form.JSON object with a configuration.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

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:

Content TypeURL
SDK & API'https://*.sumup.com'
Images'data:', 'https://static.sumup.com'

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.