Save Customer Cards

Tokenize cards with the Payment Widget for future recurring payments.

About Card Tokenization

In this guide, you will learn how to use the Payment Widget to save a customer’s card as a tokenized payment instrument and set up recurring payments. The Payment Widget handles the payment interface, consent collection, and 3D Secure authentication. This feature is also known as card on file or tokenization.

You will go through the following steps:

Create a customer.
Create a checkout for card tokenization. This is where 3D Secure authentication takes place. The transaction amount is instantly reimbursed.
Process the payment with the Payment Widget.
Retrieve the tokenized card.
Make subsequent payments with the tokenized card.

Prerequisites

You have a merchant account with SumUp(Opens in a new tab) and have already filled in your account details(Opens in a new tab).
- You can also create a sandbox merchant account. Please note that setting up 3DS verification in a sandbox merchant account requires contacting our team through the contact form.
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 paying for a product or service. It contains personal information such as name, contact details, postal address, as well as a unique identifier relevant to your business logic (customer_id).

Create a new customer resource with 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
}'

1
const customer = await client.customers.create({
2
  customer_id: "MYCUSTOMERID-123",
3
  personal_details: {
4
    first_name: "Jeffrey",
5
    last_name: "Lebowski",
6
    email: "thedude@example.com",
7
    phone: "+1 310-555-1234",
8
    birth_date: "1949-11-11",
9
    address: {
10
      city: "Venice",
11
      state: "California",
12
      country: "US",
13
      line_1: "606 Venezia Ave",
14
      line_2: "Front",
15
      postal_code: "90291",
16
    },
17
  },
18
});

1
var customer = await client.Customers.CreateAsync(new Customer
2
{
3
    CustomerId = "MYCUSTOMERID-123",
4
    PersonalDetails = new PersonalDetails
5
    {
6
        FirstName = "Jeffrey",
7
        LastName = "Lebowski",
8
        Email = "thedude@example.com",
9
        Phone = "+1 310-555-1234",
10
        BirthDate = new System.DateTime(1949, 11, 11),
11
        Address = new AddressLegacy
12
        {
13
            City = "Venice",
14
            State = "California",
15
            Country = "US",
16
            Line1 = "606 Venezia Ave",
17
            Line2 = "Front",
18
            PostalCode = "90291",
19
        },
20
    },
21
});

1
var customer = client.customers().createCustomer(
2
    Customer.builder()
3
        .customerId("MYCUSTOMERID-123")
4
        .personalDetails(
5
            PersonalDetails.builder()
6
                .firstName("Jeffrey")
7
                .lastName("Lebowski")
8
                .email("thedude@example.com")
9
                .phone("+1 310-555-1234")
10
                .birthDate(java.time.LocalDate.parse("1949-11-11"))
11
                .address(
12
                    AddressLegacy.builder()
13
                        .city("Venice")
14
                        .state("California")
15
                        .country("US")
16
                        .line1("606 Venezia Ave")
17
                        .line2("Front")
18
                        .postalCode("90291")
19
                        .build()
20
                )
21
                .build()
22
        )
23
        .build()
24
);

1
str := func(v string) *string { return &v }
2

3
customer, err := client.Customers.Create(ctx, sumup.CustomersCreateParams{
4
  CustomerID: "MYCUSTOMERID-123",
5
  PersonalDetails: &sumup.PersonalDetails{
6
    FirstName: str("Jeffrey"),
7
    LastName:  str("Lebowski"),
8
    Email:     str("thedude@example.com"),
9
    Phone:     str("+1 310-555-1234"),
10
    Address: &sumup.AddressLegacy{
11
      City:       str("Venice"),
12
      State:      str("California"),
13
      Country:    str("US"),
14
      Line1:      str("606 Venezia Ave"),
15
      Line2:      str("Front"),
16
      PostalCode: str("90291"),
17
    },
18
  },
19
})

1
from sumup.customers.resource import CreateCustomerBody
2
from sumup.customers.types import AddressLegacy, PersonalDetails
3

4
customer = client.customers.create(
5
    CreateCustomerBody(
6
        customer_id="MYCUSTOMERID-123",
7
        personal_details=PersonalDetails(
8
            first_name="Jeffrey",
9
            last_name="Lebowski",
10
            email="thedude@example.com",
11
            phone="+1 310-555-1234",
12
            birth_date="1949-11-11",
13
            address=AddressLegacy(
14
                city="Venice",
15
                state="California",
16
                country="US",
17
                line_1="606 Venezia Ave",
18
                line_2="Front",
19
                postal_code="90291",
20
            ),
21
        ),
22
    )
23
)

1
  let customer = client
2
      .customers()
3
      .create(sumup::resources::customers::Customer {
4
          customer_id: "MYCUSTOMERID-123".into(),
5
          personal_details: Some(sumup::resources::common::PersonalDetails {
6
              first_name: Some("Jeffrey".into()),
7
              last_name: Some("Lebowski".into()),
8
              email: Some("thedude@example.com".into()),
9
              phone: Some("+1 310-555-1234".into()),
10
              birth_date: None,
11
              tax_id: None,
12
              address: Some(sumup::resources::common::AddressLegacy {
13
                  city: Some("Venice".into()),
14
                  state: Some("California".into()),
15
                  country: Some("US".into()),
16
                  line_1: Some("606 Venezia Ave".into()),
17
                  line_2: Some("Front".into()),
18
                  postal_code: Some("90291".into()),
19
              }),
20
          }),
21
      })
22
      .await?;

1
$customer = $sumup->customers->create([
2
    'customer_id' => 'MYCUSTOMERID-123',
3
    'personal_details' => [
4
        'first_name' => 'Jeffrey',
5
        'last_name' => 'Lebowski',
6
        'email' => 'thedude@example.com',
7
        'phone' => '+1 310-555-1234',
8
        'address' => [
9
            'city' => 'Venice',
10
            'state' => 'California',
11
            'country' => 'US',
12
            'line_1' => '606 Venezia Ave',
13
            'line_2' => 'Front',
14
            'postal_code' => '90291',
15
        ],
16
    ],
17
]);

You should expect a standard 201 Created response, with the customer details you passed. For full details, see the endpoint documentation. 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
      }'

1
const checkout = await client.checkouts.create({
2
  checkout_reference: "MYCHECKOUT",
3
  amount: 1,
4
  currency: "EUR",
5
  merchant_code: "MDEERENR",
6
  description: "My checkout",
7
  customer_id: "MYCUSTOMERID-123",
8
  purpose: "SETUP_RECURRING_PAYMENT",
9
});

1
var checkout = await client.Checkouts.CreateAsync(new CheckoutCreateRequest
2
{
3
    CheckoutReference = "MYCHECKOUT",
4
    Amount = 1.0f,
5
    Currency = Currency.Eur,
6
    MerchantCode = "MDEERENR",
7
    Description = "My checkout",
8
    CustomerId = "MYCUSTOMERID-123",
9
    Purpose = "SETUP_RECURRING_PAYMENT",
10
});

1
var checkout = client.checkouts().createCheckout(
2
    CheckoutCreateRequest.builder()
3
        .checkoutReference("MYCHECKOUT")
4
        .amount(1.0f)
5
        .currency(Currency.EUR)
6
        .merchantCode("MDEERENR")
7
        .description("My checkout")
8
        .customerId("MYCUSTOMERID-123")
9
        .purpose(CheckoutCreateRequestPurpose.SETUP_RECURRING_PAYMENT)
10
        .build()
11
);

1
customerID := "MYCUSTOMERID-123"
2
purpose := sumup.CheckoutCreateRequestPurposeSetupRecurringPayment
3
description := "My checkout"
4

5
checkout, err := client.Checkouts.Create(ctx, sumup.CheckoutsCreateParams{
6
  CheckoutReference: "MYCHECKOUT",
7
  Amount:            1,
8
  Currency:          sumup.CurrencyEUR,
9
  MerchantCode:      "MDEERENR",
10
  Description:       &description,
11
  CustomerID:        &customerID,
12
  Purpose:           &purpose,
13
})

1
from sumup.checkouts.resource import CreateCheckoutBody
2

3
checkout = client.checkouts.create(
4
    CreateCheckoutBody(
5
        checkout_reference="MYCHECKOUT",
6
        amount=1,
7
        currency="EUR",
8
        merchant_code="MDEERENR",
9
        description="My checkout",
10
        customer_id="MYCUSTOMERID-123",
11
        purpose="SETUP_RECURRING_PAYMENT",
12
    )
13
)

1
let checkout = client
2
    .checkouts()
3
    .create(Some(sumup::resources::checkouts::CheckoutCreateRequest {
4
        checkout_reference: "MYCHECKOUT".into(),
5
        amount: 1.0,
6
        currency: sumup::resources::checkouts::Currency::EUR,
7
        merchant_code: "MDEERENR".into(),
8
        description: Some("My checkout".into()),
9
        customer_id: Some("MYCUSTOMERID-123".into()),
10
        purpose: Some("SETUP_RECURRING_PAYMENT".into()),
11
        id: None,
12
        status: None,
13
        date: None,
14
        valid_until: None,
15
        transactions: None,
16
        return_url: None,
17
        redirect_url: None,
18
    }))
19
    .await?;

1
$checkout = $sumup->checkouts->create([
2
    'checkout_reference' => 'MYCHECKOUT',
3
    'amount' => 1,
4
    'currency' => 'EUR',
5
    'merchant_code' => 'MDEERENR',
6
    'description' => 'My checkout',
7
    'customer_id' => 'MYCUSTOMERID-123',
8
    'purpose' => 'SETUP_RECURRING_PAYMENT',
9
]);

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": "Sandbox Merchant 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 Payment Widget securely collects card details and processes checkouts while handling consent collection and 3D Secure authentication.

Once you have the checkout ID from the previous step, mount the Payment Widget on your website and pass the ID as checkoutId.

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 customer enters their card details, consents to storing them, and completes the checkout in the Payment Widget. The card details are sent directly to SumUp and do not pass through your server.

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
    "token": "6878cb7f-6515-47bf-bdd9-1408d270fdce"
3
}

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"

1
const instruments = await client.customers.listPaymentInstruments("MYCUSTOMERID-123");

1
var instruments = await client.Customers.ListPaymentInstrumentsAsync("MYCUSTOMERID-123");

1
var instruments = client.customers().listPaymentInstruments("MYCUSTOMERID-123");

1
instruments, err := client.Customers.ListPaymentInstruments(ctx, "MYCUSTOMERID-123")

1
instruments = client.customers.list_payment_instruments("MYCUSTOMERID-123")

1
let instruments = client
2
    .customers()
3
    .list_payment_instruments("MYCUSTOMERID-123")
4
    .await?;

1
$instruments = $sumup->customers->listPaymentInstruments('MYCUSTOMERID-123');

Retrieving Tokenized Card

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

Example response:

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: