Save a card for later

A setup intent lets you collect card details during a buyer-initiated session and store them securely, so you can charge the card later — for subscriptions, one-click reorder, or any merchant-initiated payment — without requiring the buyer to re-enter their details.

How it works

Create a setup intent

Your server calls POST /v1/setup_intents. The intent starts in requires_confirmation and is ready to accept a client-side token.

Tokenize the card in the browser

Ionic Hosted Card Fields sends the card details directly to the tokenization service and returns a single-use payment_token. Your server never sees the PAN.

Confirm the intent

Your server calls POST /v1/setup_intents/{id}/confirm with the payment_token. On success the intent moves to succeeded and a reusable payment method (pm_…) is created.

Attach to a customer (optional)

Call POST /v1/payment_methods/{id}/attach to associate the saved method with a customer record for easy retrieval later.

Charge off-session

When you need to collect payment without the buyer present, create a payment intent using the saved pm_… and set initiated_by: merchant.

On Node, npm install @ionicfi/sdk gives you typed calls for every request below; the server SDK guide has details. Each example also shows raw curl.

Create a setup intent

import { Ionic } from "@ionicfi/sdk";

const ionic = new Ionic({ token: process.env.IONIC_SECRET_KEY });

const intent = await ionic.setupIntents.create({
  "Idempotency-Key": "setup_user_42_2026",
  currency: "usd",
  customer: "cus_000000000000000000000001",
  metadata: { signup_flow: "checkout" },
});

curl https://api.ionicfi.com/v1/setup_intents \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Idempotency-Key: setup_user_42_2026" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "usd",
    "customer": "cus_000000000000000000000001",
    "metadata": {
      "signup_flow": "checkout"
    }
  }'

The response is a setup intent in requires_confirmation status:

{
  "id": "seti_000000000000000000000001",
  "object": "setup_intent",
  "status": "requires_confirmation",
  "currency": "usd",
  "customer": "cus_000000000000000000000001",
  "payment_method": null,
  "livemode": false
}

Create request fields

Field	Type	Notes
`currency`	string	Required. Three-letter ISO currency code (e.g. `usd`).
`customer`	string	Customer id (`cus_…`). When present, a mandate is created on confirm and the resulting payment method is linked to this customer.
`metadata`	object	Up to 50 key-value pairs of arbitrary metadata.

Confirm the setup intent

After your client-side card form returns a payment_token, pass it to the confirm endpoint from your server.

// The payment token is single-use, so it makes a natural Idempotency-Key:
// retries of this attempt replay the original result, and a fresh token
// after a failed vault is automatically a new key.
const paymentToken = "tok_..."; // from your client-side card form

const confirmed = await ionic.setupIntents.confirm({
  id: intent.id,
  "Idempotency-Key": `confirm-${paymentToken}`,
  payment_token: paymentToken,
});

curl -X POST https://api.ionicfi.com/v1/setup_intents/seti_000000000000000000000001/confirm \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Idempotency-Key: confirm-tok_..." \
  -H "Content-Type: application/json" \
  -d '{
    "payment_token": "tok_..."
  }'

Key the confirm to the attempt, not to a constant. A fixed key blocks every later confirmation with a 422 conflict once the first one is recorded; deriving it from the single-use token scopes each key to one attempt. On success the intent moves to succeeded and payment_method is populated:

{
  "id": "seti_000000000000000000000001",
  "object": "setup_intent",
  "status": "succeeded",
  "payment_method": "pm_000000000000000000000001",
  "customer": "cus_000000000000000000000001"
}

If vaulting fails, the intent returns to requires_confirmation so you can retry with a fresh token from the client. A 422 response means the intent is not in a confirmable state.

Setup intent status values

Status	Meaning
`requires_confirmation`	Initial state; awaiting a client-side token. Also the state after a failed vault attempt.
`processing`	Vault operation is in progress.
`succeeded`	Card vaulted and reusable payment method created.
`canceled`	Intent was canceled before completion.

Inspect the saved payment method

Retrieve the saved method to confirm the card details. The response includes brand, last four digits, and expiration — never the PAN.

const method = await ionic.paymentMethods.retrieve({
  id: "pm_000000000000000000000001",
});

curl https://api.ionicfi.com/v1/payment_methods/pm_000000000000000000000001 \
  -H "Authorization: Bearer sk_v1_test_..."

{
  "id": "pm_000000000000000000000001",
  "object": "payment_method",
  "type": "card",
  "status": "active",
  "reusable": true,
  "card": {
    "brand": "visa",
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 2029,
    "funding_type": "credit"
  },
  "customer": "cus_000000000000000000000001",
  "fingerprint": "fp_..."
}

Payment method card fields

Field	Notes
`brand`	One of `visa`, `mastercard`, `amex`, `discover`, `unknown`.
`last4`	Last four digits of the card number.
`exp_month`	Expiration month (1–12).
`exp_year`	Expiration year (four digits).
`funding_type`	One of `credit`, `debit`, `prepaid`, `unknown`.

Attach to a customer

If you did not supply a customer when creating the intent, attach the method to a customer now. Attachment is write-once — a method can only be attached to one customer.

await ionic.paymentMethods.attach({
  id: "pm_000000000000000000000001",
  "Idempotency-Key": "attach_pm_user_42",
  customer: "cus_000000000000000000000001",
});

curl -X POST https://api.ionicfi.com/v1/payment_methods/pm_000000000000000000000001/attach \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Idempotency-Key: attach_pm_user_42" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_000000000000000000000001"
  }'

Charge off-session

When you need to charge the buyer without them present, create a payment intent using the saved method. Set initiated_by: merchant — merchant-initiated transactions require a secret key.

const payment = await ionic.paymentIntents.create({
  "Idempotency-Key": "pi_renewal_order_789",
  amount: 4900,
  currency: "usd",
  payment_method: "pm_000000000000000000000001",
  customer: "cus_000000000000000000000001",
  initiated_by: "merchant",
  mandate: "mand_000000000000000000000001",
  reference: "order_789",
});

curl https://api.ionicfi.com/v1/payment_intents \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Idempotency-Key: pi_renewal_order_789" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4900,
    "currency": "usd",
    "payment_method": "pm_000000000000000000000001",
    "customer": "cus_000000000000000000000001",
    "initiated_by": "merchant",
    "mandate": "mand_000000000000000000000001",
    "reference": "order_789"
  }'

A successful off-session charge returns a payment intent in succeeded status. A decline returns 402 with a card_error type and the current payment intent embedded in the response body so you can inspect its status without a second request.

Off-session payment intent fields

Field	Type	Notes
`amount`	integer	Amount in minor units (e.g. cents for USD).
`currency`	string	Three-letter ISO currency code.
`payment_method`	string	The saved payment method id (`pm_…`).
`initiated_by`	string	Use `merchant` for off-session charges. Requires a secret key.
`mandate`	string	Mandate id authorizing the merchant-initiated charge. Created automatically when a setup intent is confirmed with a `customer`.
`customer`	string	Customer id (`cus_…`) to attach.
`reference`	string	Your order number or other reference (max 256 chars).

Operational guidance

Always send an Idempotency-Key on setup-intent create, confirm, and payment-intent create. Retried requests without a key can vault the same card twice or charge a buyer more than once.
Tokenize card data in the browser with Ionic Hosted Card Fields. Your server only ever receives an opaque payment_token — never raw card details.
Store the pm_… id in your database against the customer or subscription record after the setup intent succeeds. You will need it for every subsequent off-session charge.
Use GET /v1/payment_methods?customer=cus_… to list all saved methods for a customer before charging, so you can handle expired or revoked cards gracefully.
A payment method’s fingerprint is stable across multiple vaultings of the same physical card. Use it to detect duplicate cards on a customer before saving a second copy.
When an off-session charge returns 402, check the embedded payment_intent.status. A requires_payment_method status means the card was declined and the buyer needs to update their payment details.

Start here

Accept payments

Recurring billing

After the payment

Build commerce

Concepts

Save a card for later

How it works

Create a setup intent

Create request fields

Confirm the setup intent

Setup intent status values

Inspect the saved payment method

Payment method card fields

Attach to a customer

Charge off-session

Off-session payment intent fields

Operational guidance

​How it works

​Create a setup intent

​Create request fields

​Confirm the setup intent

​Setup intent status values

​Inspect the saved payment method

​Payment method card fields

​Attach to a customer

​Charge off-session

​Off-session payment intent fields

​Operational guidance

How it works

Create a setup intent

Create request fields

Confirm the setup intent

Setup intent status values

Inspect the saved payment method

Payment method card fields

Attach to a customer

Charge off-session

Off-session payment intent fields

Operational guidance