Save Customer Cards

Shows how to tokenize cards with the Payment Widget so you can save payment instruments for future charges.

About Card Tokenization

In this guide, you will learn how to use the Payment Widget to store card details for future use, and how to set up recurring payments, as SumUp handles the UI/UX and consent collection for you. Alternatively, you can process payments with your own UI, following the API guidelines also provided in this document. This feature is also known as card on file or tokenization.

You will go through the following steps:

Create a customer.
Create checkout intended for card tokenization, where we specify it’s for tokenization purpose. This is where 3DS verification takes place. The transaction amount is instantly reimbursed.
Process payment with the payment widget or process payment directly with SumUp API.
Retrieve the tokenized card.
Make subsequent payments with the tokenized card.

Prerequisites

You have a merchant account with SumUp and have already filled in your account details.
- You can also create a test account. Please note that setting up 3DS verification in a test account requires contact with our team at integrations@sumup.com.
You have an API Key. For more details see the Authorization Guide.
You have control over the backend server to retrieve data securely.

Creating Customer

A customer resource is a representation of a person or business that is paying for a product or service. It contains personal information such as their name, contact details, postal address, as well as a unique identifier that is relevant to your business logic (customer_id).

To create a new customer resource, make a POST request to the https://api.sumup.com/v0.1/customers endpoint:

1
curl -X POST \
2
  https://api.sumup.com/v0.1/customers \
3
  -H "Authorization: Bearer $SUMUP_API_KEY" \
4
  -H 'Content-Type: application/json' \
5
  -d '{
6
  "customer_id": "MYCUSTOMERID-123",
7
  "personal_details": {
8
    "address": {
9
      "city": "Venice",
10
      "state": "California",
11
      "country": "US",
12
      "line1": "606 Venezia Ave",
13
      "line2": "Front",
14
      "postal_code": "90291"
15
    },
16
    "birthdate": "1949-11-11",
17
    "email": "thedude@example.com",
18
    "first_name": "Jeffrey",
19
    "last_name": "Lebowski",
20
    "phone": "+1 310-555-1234"
21
  }
22
}'

You should expect a standard 201 Created response, with the customer details you passed. For more details see the create a customer endpoint. Having created the customer, we can now proceed to making a payment

Creating Checkout to Save Card

Now, we need to tokenize the customer’s card, and we will need a checkout for this. The checkout resource is a representation of a payment being made by the previously created customer. It contains information such as the amount, currency, and a unique checkout_reference identifier that is relevant to your business logic.

The flow is initiated with the create a checkout endpoint. It is important to pass the customer_id parameter in this step, for future linking to a payment instrument. Critically, a purpose parameter is passed to indicate the payment type as recurring payment and process an authorization charge of the checkout amount indicated, which is instantly reimbursed. Note that this doesn’t automatically imply further payments from this customer - at this point, we’re just tokenizing the card.

To create a new checkout resource, make a POST request to the https://api.sumup.com/v0.1/checkouts endpoint.

Example of such request:

1
curl -X POST \
2
  https://api.sumup.com/v0.1/checkouts \
3
  -H "Authorization: Bearer $SUMUP_API_KEY" \
4
  -H 'Content-Type: application/json' \
5
  -d '{
6
        "checkout_reference": "MYCHECKOUT",
7
        "amount": 1,
8
        "currency": "EUR",
9
        "merchant_code": "MDEERENR",
10
        "description": "My checkout",
11
        "customer_id": "MYCUSTOMERID-123",
12
        "purpose": "SETUP_RECURRING_PAYMENT"
13
      }'

You should expect a standard 201 Created response, with the checkout reference and both merchant and customer information.

1
{
2
    "amount": 1,
3
    "checkout_reference": "MYCHECKOUT",
4
    "checkout_type": "checkout",
5
    "currency": "EUR",
6
    "customer_id": "MYCUSTOMERID-123",
7
    "date": "2025-10-29T15:09:11.550+00:00",
8
    "description": "My checkout",
9
    "id": "7164c99b-13cb-42a1-8ba1-3c2c46a29de7",
10
    "merchant_code": "MDEERENR",
11
    "merchant_country": "PL",
12
    "merchant_name": "Test Account",
13
    "pay_to_email": "a8e019f9bb2f49159182e8bd61eb5ea6@developer.sumup.com",
14
    "purpose": "SETUP_RECURRING_PAYMENT",
15
    "status": "PENDING",
16
    "transactions": []
17
}

For more information, see the create a checkout endpoint.

The SumUp’s Payment Widget is a JavaScript library that allows you to securely process checkouts and collect card details securely, handling consent collection and 3DS verification. These steps are mandatory due to legal requirements, which is why we recommend processing the checkout with our widget.

Once you have a checkout reference from the step above, you can mount the payment widget into your website and collect the card details. Pass the checkout_reference from above as the checkoutId here.

1
<div id="sumup-card"></div>
2
<script
3
  type="text/javascript"
4
  src="https://gateway.sumup.com/gateway/ecom/card/v2/sdk.js"
5
></script>
6
<script type="text/javascript">
7
  SumUpCard.mount({
8
    id: "sumup-card",
9
    checkoutId: `${checkout_id}`, // Ex: '7164c99b-13cb-42a1-8ba1-3c2c46a29de7'
10
    onResponse: function (type, body) {
11
      console.log("Type", type);
12
      console.log("Body", body);
13
    },
14
  });
15
</script>

Upon mounting the Payment Widget with a recurring purpose checkout, you should see the following screen:

The user is prompted to enter their card details, give consent to store their card details and complete the checkout. The widget uses the Process Checkout endpoint to securely process the checkout. We strongly recommend using the widget over direct integration, as the widget correctly handles all legal requirements for payments.

If the previous operation is successful, and the card is stored with the Save for future payments option, a payment_instrument object containing a token representing the card is created (AKA tokenized card) for this customer.

1
"payment_instrument": {
2
    "mandate_reference": "2078683",
3
    "token": "6878cb7f-6515-47bf-bdd9-1408d270fdce"
4
}

At any time, you can fetch the list of tokenized cards of a customer by requesting them via the list payment instruments endpoint.

1
curl -X GET \
2
  "https://api.sumup.com/v0.1/customers/${CUSTOMER_ID}/payment-instruments" \
3
  -H "Authorization: Bearer $SUMUP_API_KEY" \
4
  -H "Content-Type: application/json;charset=UTF-8"

Processing Request Directly

In case you want to provide a fully customized experience, you can process the request using SumUp API directly. In this case, you need to make sure to handle all legal requirements yourself. Critically, SumUp API expects the mandate object in the request. By providing the mandate object, you are stating that you have obtained the consent of the customer. The mandate object establishes the authorization framework for storing and reusing card details. It defines what the card token will be used for (only recurring payments for the time being), while also capturing technical details about the tokenization request for security and compliance purposes.

1
{
2
  "payment_type": "card",
3
  "installments": 1,
4
  "card": {
5
    "name": "FIRSTNAME LASTNAME",
6
    "number": "4111111111111111",
7
    "expiry_year": "2023",
8
    "expiry_month": "01",
9
    "cvv": "123",
10
    "zip_code": "12345"
11
  },
12
  "mandate": {
13
    "type": "recurrent",
14
    "user_agent": "Chrome: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3865.90 Safari/537.36.",
15
    "user_ip": "2001:0db8:85a3:0000:0a00:8a2e:0370:7300"
16
  }
17
}

Again, a payment_instrument object containing a token representing the card is created (AKA tokenized card) for this customer.

1
"payment_instrument": {
2
    "mandate_reference": "2078683",
3
    "token": "6878cb7f-6515-47bf-bdd9-1408d270fdce"
4
}

At any time, you can fetch the list of tokenized cards of a customer by requesting them via the list payment instruments endpoint.

1
curl -X GET \
2
  "https://api.sumup.com/v0.1/customers/${CUSTOMER_ID}/payment-instruments" \
3
  -H "Authorization: Bearer $SUMUP_API_KEY" \
4
  -H "Content-Type: application/json;charset=UTF-8"

Retrieving Tokenized Card

If you have successfully processed the checkout, a token representing the payment instrument (card) is created. You can now retrieve the checkout to find the token within a payment_instrument object for later recurrent payment.

1
{
2
  "id": "cd36780e-f43d-4f22-1i9e-e32a1a1bafc8",
3
  "checkout_reference": "0BYNWLYC7KV",
4
  "amount": 3.51,
5
  "currency": "EUR",
6
  ...
7
  "payment_instrument": {
8
    "token": "2fa27578-e765-5dbh-aa97-d45d3d6cdfbb"
9
  }
10
}

Processing Recurring Payments

Having tokenized the customer’s card, you can now process recurring payments by referencing the saved token and the associated customer. Both token and customer_id fields are required.

Create a checkout again. This time, it’s for the actual payment. The previous checkout was for tokenizing the card only.
Process the checkout. Make sure to pass the following data (installments is only valid for the Brazilian market):

1
{
2
  "payment_type": "card",
3
  "installments": 1,
4
  "token": "{{CARD_TOKEN}}"
5
  "customer_id": "{{CUSTOMER_ID}}",
6
}

What’s Next?

You may be interested in the following resources related to Online Payments: