Save a card for later

A SetupIntent saves a new card without taking a payment. Ionic Blocks collects the card and consent, and confirmSetup confirms the intent. Your application owns customer authorization and the lifecycle of the save request.

Operation	Interface
Save without paying	SetupIntent and `confirmSetup`
Pay with optional saving	PaymentIntent with `setup_future_usage: "off_session"` and `confirmPayment`
Save for a connected account	Connect SetupIntents

Install both packages from npm: @ionicfi/js on the page and @ionicfi/sdk on the server.

Create a SetupIntent

The customer ID must belong to the intended merchant and mode and be authorized for the person saving the card. This server SDK call creates the intent:

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

const ionic = new Ionic({ token: process.env.IONIC_SECRET_KEY });
const intent = await ionic.setupIntents.create({
  "Idempotency-Key": requestKey,
  currency: "usd",
  customer: "cus_BBBBBBBBBBBBBB",
});

requestKey represents the application-assigned key for this operation. A repeated operation uses the same key and body within the idempotency window. A new call without a supplied key receives a new SDK-generated key and can create another intent. The creation response includes the intent’s id and client_secret. Secret-key retrieval does not return the client secret’s value. The browser needs the matching publishable key and authorized access to that secret. Keep client secrets out of URLs, logs, and analytics. Register the page’s origin in Developers → Web domains for the same mode. The mount target is an empty element already in the document. Substitute the publishable key and SetupIntent secret from your backend:

<div id="payment"></div>

import { loadIonic } from "@ionicfi/js";

const ionic = await loadIonic("pk_v1_test_...");
const blocks = ionic.blocks({ clientSecret: "seti_..._secret_..." });
await blocks.create("payment").mount("#payment");

Method	Contract
`ionic.confirmSetup({ blocks })`	Confirms the bound SetupIntent in response to a customer submission. Returns `setupIntent` and/or `error`.
`ionic.retrieveSetupIntent(clientSecret)`	Reads the existing intent without a Blocks instance.
`blocks.destroy()`	Removes the UI and listeners without canceling an operation already submitted.

The default consent checkbox begins unchecked. Confirmation requires the customer’s consent. In external consent mode, confirmParams.savePaymentMethod must carry that explicit choice.

Saved-card result

The server API GET /v1/setup_intents/{id} returns the current SetupIntent.

Field	Meaning
`merchant_id`, `customer`, `livemode`	Ownership and mode; must match the intended save request.
`status: requires_confirmation`	The intent is awaiting confirmation.
`status: processing`	The outcome is pending.
`status: succeeded`	Setup completed; a usable saved-card result also requires a non-null `payment_method`.
`status: canceled`	The intent cannot be confirmed.
`payment_method`	The saved payment method ID when available.

A browser success callback alone is insufficient to associate a saved card with a customer. A lost response does not imply failure. The existing intent’s state remains available through retrieval; your application owns persistence and recovery. See Blocks retry behavior. Only a SetupIntent in requires_confirmation can be canceled. Cancellation does not revoke a card that has already been saved. The SetupIntent API documents the operation and state errors.

Saved payment methods

GET /v1/payment_methods/{id} returns the saved method’s details and customer. GET /v1/payment_methods?customer=cus_… lists a customer’s methods. Blocks collects a new card; it does not provide a saved-card selector. Passing customer at SetupIntent creation associates the saved method with that customer. Attaching a method later is write-once and does not establish consent for future charges. A future payment is a separate PaymentIntent operation, subject to the customer’s consent and the method’s capabilities. The PaymentIntent API documents payment_method, customer, and initiated_by. Supplying a payment method at creation can attempt a charge immediately. For advanced card fields, the server-side SetupIntent confirm endpoint accepts a single-use payment_token. Blocks uses confirmSetup instead; these are separate confirmation interfaces.

What’s next

Manage customers

Create customers and attach payment methods.

Bill the saved card

Charge the saved card each period with a subscription.

Read the Blocks reference

Look up every option, event, result shape, and error code.

Payments

Manage payments

Save a card for later

Create a SetupIntent

Saved-card result

Saved payment methods

What’s next

Manage customers

Bill the saved card

Read the Blocks reference

​Create a SetupIntent

​Card collection and consent

​Saved-card result

​Saved payment methods

​What’s next

Manage customers

Bill the saved card

Read the Blocks reference

Create a SetupIntent

Card collection and consent

Saved-card result

Saved payment methods

What’s next