Save Customer Cards

Overview

In this guide, you will learn how to use the payment widget to store card details for future use, for example to set up recurring payments. This feature is also known as card on file or tokenization.

You will go through the following steps:

1. Create a customer
2. 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.
3. Process payment with the payment widget
4. Make subsequent payments with a payment instrument

Prerequisites

• You have a merchant account with SumUp and have already filled in your account details.
  • For a test account reach out to our support team through this 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 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:

curl -X POST \
  https://api.sumup.com/v0.1/customers \
  -H "Authorization: Bearer $SUMUP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "customer_id": "MYCUSTOMERID-123",
  "personal_details": {
    "address": {
      "city": "Venice",
      "state": "California",
      "country": "US",
      "line1": "606 Venezia Ave",
      "line2": "Front",
      "postal_code": "90291"
    },
    "birthdate": "1949-11-11",
    "email": "thedude@example.com",
    "first_name": "Jeffrey",
    "last_name": "Lebowski",
    "phone": "+1 310-555-1234"
  }
}'

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

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:

curl -X POST \
  https://api.sumup.com/v0.1/checkouts \
  -H "Authorization: Bearer $SUMUP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
        "checkout_reference": "MYCHECKOUT",
        "amount": 100,
        "currency": "EUR",
        "merchant_code": "MDEERENR",
        "description": "My checkout",
        "customer_id": "MYCUSTOMERID-123",
        "purpose": "SETUP_RECURRING_PAYMENT"
      }'

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

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

For more information, see the create a checkout endpoint.

Processing Request with Payment Widget

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 you should always process the checkout with the 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.

<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: `${checkout_id}`, // Ex: '7164c99b-13cb-42a1-8ba1-3c2c46a29de7'
    onResponse: function (type, body) {
      console.log("Type", type);
      console.log("Body", body);
    },
  });
</script>

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

Card on file with payment widget

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.

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

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

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

Setting up Recurring Payments

Having tokenized the customer’s card, we can use it to process recurring payments. For detailed information, read the Recurring Payments guide.