GuidesRecipesAPI ReferenceChangelog
Log In
Guides

Save a Card

📘 What this guide covers

How to save a customer's card without taking a payment, using the Super Card web component. Once saved, use the paymentMethodId to charge the customer at any point - see Charge a Saved Card.

How It Works

The customer enters their card details into the <super-card> web component. Super handles 3D Secure authentication and tokenises the card securely. Once the setup is complete, you poll our API to confirm the payment method is ready, then store the returned paymentMethodId against the customer in your system.

No payment is taken during this flow.

Prerequisites

  • Your brandId (available in the Business Portal)
  • A webhook endpoint or polling mechanism to confirm the payment method status

Pricing

📘 Pricing

Saved card payments are subject to additional charges. For full pricing details, visit our Pricing page.

Integration Guide

Step 1: Create a Customer

Create a customer record in Super. Store the id returned in the response - you will need it in Step 2.

Request

curl --request POST \
     --url https://api.superpayments.com/API_VERSION/customers \
     --header 'accept: application/json' \
     --header 'authorization: YOUR_SECRET_KEY' \
     --header 'content-type: application/json' \
     --data '{
       "brandId": "YOUR_BRAND_ID",
       "emailAddress": "[email protected]",
       "externalReference": "customer_123",
       "firstName": "John",
       "lastName": "Smith",
       "phoneNumber": "07462123456"
     }'
curl --request POST \
     --url https://api.test.superpayments.com/API_VERSION/customers \
     --header 'accept: application/json' \
     --header 'authorization: YOUR_SECRET_KEY' \
     --header 'content-type: application/json' \
     --data '{
       "brandId": "YOUR_BRAND_ID",
       "emailAddress": "[email protected]",
       "externalReference": "customer_123",
       "firstName": "John",
       "lastName": "Smith",
       "phoneNumber": "07462123456"
     }'

Response

{
  "id": "cus_123",
  "brandId": "YOUR_BRAND_ID",
  "emailAddress": "[email protected]",
  "externalReference": "customer_123",
  "firstName": "John",
  "lastName": "Smith",
  "paymentMethods": [],
  "phoneNumber": "07462123456",
  "createdAt": "2026-03-15T10:00:00.000Z",
  "updatedAt": "2026-03-15T10:00:00.000Z"
}

📘 Store the id (e.g. cus_...) against the customer in your system. You will need it in the next step.

Step 2: Create a Payment Method

Create a payment method record for the customer. This returns a paymentMethodId with a status of REQUIRES_ACTION, indicating the card details still need to be captured.

Request

curl --request POST \
     --url https://api.superpayments.com/API_VERSION/payment-methods \
     --header 'accept: application/json' \
     --header 'authorization: YOUR_SECRET_KEY' \
     --header 'content-type: application/json' \
     --data '{
       "customerId": "cus_123",
       "type": "CARD",
       "usage": "OFF_SESSION"
     }'
curl --request POST \
     --url https://api.test.superpayments.com/API_VERSION/payment-methods \
     --header 'accept: application/json' \
     --header 'authorization: YOUR_SECRET_KEY' \
     --header 'content-type: application/json' \
     --data '{
       "customerId": "cus_123",
       "type": "CARD",
       "usage": "OFF_SESSION"
     }'

Response

{
  "id": "pm_123",
  "type": "CARD",
  "usage": "OFF_SESSION",
  "status": "REQUIRES_ACTION",
  "customerId": "cus_123",
  "createdAt": "2026-03-15T10:00:00.000Z",
  "updatedAt": "2026-03-15T10:00:00.000Z"
}

📘 Store the id (e.g. pm_...) - you will need it in Steps 3 and 5.

Step 3: Get a Card SetupIntent Session Token

Request a setup intent for the payment method. This returns a sessionToken used to initialise the card capture component in Step 4.

Request

curl --request POST \
     --url https://api.superpayments.com/API_VERSION/payment-methods/pm_123/setup-intents \
     --header 'accept: application/json' \
     --header 'authorization: YOUR_SECRET_KEY' \
     --header 'content-type: application/json' \
     --data '{
       "returnUrl": "https://your-site.com/card-saved"
     }'
curl --request POST \
     --url https://api.test.superpayments.com/API_VERSION/payment-methods/pm_123/setup-intents \
     --header 'accept: application/json' \
     --header 'authorization: YOUR_SECRET_KEY' \
     --header 'content-type: application/json' \
     --data '{
       "returnUrl": "https://your-site.com/card-saved"
     }'

Response

{
  "id": "si_123",
  "sessionToken": "YOUR_SESSION_TOKEN"
}

Step 4: Mount the Card Component

Add the Super payment.js library to your page and render the <super-card> component using the sessionToken from Step 3. Render a button that calls window.superCard.submit() on click to trigger card capture.

<script src="https://cdn.superpayments.com/js/payments.js"></script>

<super-card session-token="YOUR_SESSION_TOKEN"></super-card>

<button onclick="saveCard()">Save Card</button>

<script>
  async function saveCard() {
    const response = await window.superCard.submit();

    if (response.status === 'FAILURE') {
      // Handle error
    } else {
      // Card saved successfully
    }
  }
</script>
<script src="https://cdn.superpayments.com/js/test/payment.js"></script>

<super-card session-token="YOUR_SESSION_TOKEN"></super-card>

<button onclick="saveCard()">Save Card</button>

<script>
  async function saveCard() {
    const response = await window.superCard.submit();

    if (response.status === 'FAILURE') {
      // Handle error 
    } else {
      // Card saved successfully
    }
  }
</script>

Once the customer submits their card details, they will be redirected to the returnUrl specified in Step 3.

Step 5: Confirm the Payment Method is Ready

Once the customer submits their card details and is redirected to your returnUrl, Super sends a customer.payment_method.enabled webhook to your configured endpoint. The paymentMethodId in this event is what you will use for all future off-session charges.

Webhook Event: customer.payment_method.enabled

{
  "data": {
    "type": "CARD",
    "usage": "OFF_SESSION",
    "status": "ENABLED",
    "customerId": "cus_123",
    "merchantId": "123-123-123-123",
    "paymentMethodId": "pm_123"
  },
  "eventId": "evt_test_123",
  "eventType": "customer.payment_method.enabled",
  "eventDatetime": "2026-03-15T10:01:00.000Z"
}

You can also confirm the status by polling the GET payment method endpoint until status returns ENABLED.

curl --request GET \
     --url https://api.superpayments.com/API_VERSION/payment-methods/pm_123 \
     --header 'accept: application/json' \
     --header 'authorization: YOUR_SECRET_KEY'
curl --request GET \
     --url https://api.test.superpayments.com/API_VERSION/payment-methods/pm_123 \
     --header 'accept: application/json' \
     --header 'authorization: YOUR_SECRET_KEY'
{
  "id": "pm_123",
  "type": "CARD",
  "usage": "OFF_SESSION",
  "status": "ENABLED",
  "customerId": "cus_123",
  "createdAt": "2026-03-15T10:00:00.000Z",
  "updatedAt": "2026-03-15T10:01:00.000Z"
}

Store the paymentMethodId against the customer in your system. This is used for all future off-session charges.

Testing

Use the following test card in the sandbox environment. Use 03/30 expiry date, 737 CVC, and any postcode.

ScenarioCard number
Card saved successfully4111 1111 1111 1111

For a full list of test cards and decline scenarios, see Test with Cards.

Next Steps


Updated about 6 hours ago

Did this page help you?