Save cards with the payment widget

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

Prerequisites

Here are the things that you need in order to complete the steps in this guide:

  • 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 docs
  • You have control over the backend server to retrieve data in a secure manner.

Summary

You will go through the following steps:

  1. Create a customer
  2. Create checkout for saving cards
  3. Collecting consent with the payment widget
  4. Subsequent payments with a payment instrument

Create a customer

A customer resource is a representation of a person or business that is paying for a product or service. It contains 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.

Example of such request:

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": "[email protected]",
    "first_name": "Jeffrey",
    "last_name": "Lebowski",
    "phone": "+1 310-555-1234"
  }
}'

For more details see the create a customer endpoint.

Create a checkout for saving cards

The checkout resource is a representation of a payment that is being made by a customer. It contains information such as the amount, currency, and a unique identifier that is relevant to your business logic (checkout_reference).

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. Additionally, a purpose parameter is passed to indicate the payment type as card on file and process an authorization charge of the checkout amount indicated, which is instantly reimbursed.

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": "CO746453",
        "amount": 100,
        "currency": "EUR",
        "pay_to_email": "[email protected]",
        "description": "My checkout",
        "customer_id": "MYCUSTOMERID-123",
        "purpose": "SETUP_RECURRING_PAYMENT"
      }'

For more info see the create a checkout endpoint.

The SumUp's payment widget is a JavaScript library that allows you to process checkouts and collect card details in a secure way.

Once you have a checkout id, you can mount the payment widget into your website and collect the card details.

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

Upon mouting the payment widget with a recurring purpose checkout you should see the following screen:

Card on file with payment widget

The user will be prompted to enter their card details, give consent to store their card details and complete the checkout.

If the previous operation is successful, and the card is stored, a token representing a payment instrument is created (AKA tokenized card).

The checkout process response contains the newly created payment instruments but 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"

Subsequent payments with a payment instrument

To process future subsequent payments with a token by passing a payment instrument as the token parameter of the checkout request and payment_type as card.

Example of such request:

curl -X PUT \
  "https://api.sumup.com/v0.1/checkouts/${CHECKOUT_ID}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $SUMUP_API_KEY" \
  -d '{
    "payment_type": "card"
    "token": "${token}",
  }'