Skip to main content

Payment card widget

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

The card widget lets you collect card information from your customers and includes inputs for cardholder name, card number, expiry date and security code. It also dynamically recognizes the card brand and shows the respective brand icon.

A secure HTTPS connection is used to submit the card 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 card data form via HTTPS as well.

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

Compliance

Payment Card Industry

By using SumUp's card 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 card 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 card.

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 card 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({
checkoutId: '2ceffb63-cbbe-4227-87cf-0409dd191a98',
onResponse: function (type, body) {
console.log('Type', type);
console.log('Body', body);
},
});
</script>

Configurations

The card 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.
functionnullno
onLoadThe callback function that will be called when the card widget is loaded.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
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

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

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 card widget. This section contains the necessary adjustments to render the card widget properly.

To confirm your issue is related to CSP, check your browser's console for an error message of this nature:

danger

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

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

Content TypeURL
SDK'https://gateway.sumup.com'
API'https://api.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 card widget, reach out to our support through this contact form.