Tokens

A payment method is a stored card credential linked to a customer, identified by an id prefixed with pm_. Payment methods are sometimes referred to as tokens - both terms refer to the same concept: a stored card reference used to charge a customer without them being present.

📘

Relationship to customers

Payment methods are always linked to a customer. You must create a customer before you can create a payment method.

Payment Method Lifecycle

A payment method moves through the following statuses:

How a payment method reaches ENABLED depends on how it was created:

• New customer - you create the payment method, then use a Setup Intent to collect the customer's card details via the <super-card> web component. The payment method moves to ENABLED once the customer completes card entry.
• Migrating from another provider - Super backfills the card details automatically after the token import completes. See Migrate to Super.

Payment Method Object

Create a Payment Method

Creates a new payment method linked to a customer. The payment method will initially have a status of REQUIRES_ACTION until card details are collected or imported.

Endpoint: POST https://api.superpayments.com/2026-04-01/payment-methods

Request:

{
  "customerId": "cus_0123456789",
  "type": "CARD",
  "usage": "OFF_SESSION",
  "metadata": {
    "subscriptionReference": "sub_your-internal-ref"
  }
}

Response (201):

{
  "id": "pm_0123456789",
  "customerId": "cus_0123456789",
  "type": "CARD",
  "usage": "OFF_SESSION",
  "status": "REQUIRES_ACTION"
}

📘

Store the returned ID

Store the returned id as your payment method ID. This is what you will pass when charging a saved card.

Setup Intents

For new customers, once you have created a payment method you need to collect their card details. A setup intent generates a short-lived session that you pass to the <super-card> web component to render a secure card entry form.

Endpoint: POST https://api.superpayments.com/2026-04-01/payment-methods/{id}/setup-intents

Request:

{
  "redirectUrl": "https://yourapp.com/card-saved"
}

Response:

{
  "id": "si_...",
  "sessionToken": "...",
  "redirectUrl": "https://yourapp.com/card-saved"
}

Pass the sessionToken to the <super-card> component to begin the card collection flow. Super handles PCI-compliant card capture and 3DS authentication automatically.

Once the customer completes card entry, the payment method status moves to ENABLED and you will receive a customer.payment_method.enabled webhook.

🚧

Setup intents are not needed for migration

If you are migrating payment methods from another provider, you do not need to create setup intents. Super backfills the card details after the import - see Migrate to Super.

Get a Payment Method

Returns a payment method and its current status.

Endpoint: GET https://api.superpayments.com/2026-04-01/payment-methods/{id}

Response:

{
  "id": "pm_01kv8jysnmfeys73cq2e3azyhd",
  "customerId": "cus_01kv8jy4zrfeys73c8dn3bn2ap",
  "type": "CARD",
  "usage": "OFF_SESSION",
  "status": "ENABLED",
  "createdAt": "2026-06-16T16:06:45.172Z",
  "updatedAt": "2026-06-16T16:06:45.172Z"
}

List Payment Methods

Returns a paginated list of payment methods, with optional filtering.

Endpoint: GET https://api.superpayments.com/2026-04-01/payment-methods

Query Parameters:

Webhooks

Super sends the following webhook events for payment method status changes. Configure these in your Super dashboard.

📘

Recommended webhook setup

Listen to customer.payment_method.enabled to know when a payment method is ready to use - both for new customers completing card entry and for payment methods activated after a migration import.

Next Steps