Blocks reference

This page is the reference for Ionic Blocks. For the integration itself, follow Build a payment page or Save a card for later. The same API is available from the https://js.ionicfi.com/v1/ionic.js script tag and from the @ionicfi/js loader.

Available Blocks

Ionic Blocks currently provides one Block, which collects the card number, expiry, and CVC and shows the save-card consent checkbox when saving is possible. It is available under two type names:

Type	Description
`payment`	The Payment Block. Use this type; it is the Block that carries whatever payment methods Ionic supports.
`card`	The same Block, declared card-only. Identical fields, consent, and behavior today.

The only difference at runtime is the wrapper attribute, data-ionic-block="payment" or data-ionic-block="card", which your CSS can target. Wallet buttons are available on hosted and embedded checkout. Listing previously saved cards and 3DS challenges are not available in Blocks; your application owns any saved-card selection UI, using the payment methods API.

Create a client

The script tag exposes Ionic(publishableKey, options). With the npm loader:

import { loadIonic } from "@ionicfi/js";
const ionic = await loadIonic("pk_v1_test_...", { account: "mer_BBBBBBBBBBBBBB" });

Argument	Type	Description
`publishableKey`	`string`	Your publishable key (`pk_v1_test_…` or `pk_v1_live_…`). A platform passes its platform publishable key.
`options.account`	`string`	Optional. The connected merchant’s ID (`mer_…`) for Connect. Fixed for the life of the client; create another client for another merchant.

A malformed key or account throws an invalid_request error synchronously.

Create Blocks

const blocks = ionic.blocks({ clientSecret });

Argument	Type	Description
`clientSecret`	`string`	The `client_secret` of a PaymentIntent (`pi_…_secret_…`) or SetupIntent (`seti_…_secret_…`) created on your server.

Returns an IonicBlocks instance bound to that intent, with create and destroy. The calls below describe individual methods; placeholders refer to values provided by your application. One instance serves one intent; a new intent requires a new instance. A malformed secret throws invalid_request.

Create a Block

const payment = blocks.create("payment", options);

Argument	Type	Description
`type`	`"payment"` \| `"card"`	The Block type. See Available Blocks.
`options`	`PaymentBlockOptions`	Optional. Layout, fields, styles, and consent placement, listed below.

Each IonicBlocks instance creates one Block. A second create call, an unknown type, or an unsupported saveConsent value throws invalid_request synchronously. The remaining options are validated when the Block mounts: an unknown option or an invalid value makes mount reject with collection_unavailable. Options are read at creation; to change them, destroy the Blocks instance and create a new one.

Options

Option	Type	Default	Description
`layout`	`"split"` \| `"stacked"` \| `"inline"`	`"split"`	`split` places the card number above expiry and CVC. `stacked` places each field on its own row. `inline` places all three on one row.
`gap`	`number`	Ionic default	Space between fields in pixels. An integer from 0 to 32.
`fields.cardNumber`	`FieldConfig`		Options for the card number field.
`fields.cardExpiry`	`FieldConfig`		Options for the expiry field.
`fields.cardCvc`	`FieldConfig`		Options for the CVC field.
`styles`	`FieldStyles`	Ionic default	Per-state styles, listed under Styles.
`saveConsent`	`"auto"` \| `"external"`	`"auto"`	`auto` renders the consent checkbox inside the Block when saving is possible. `external` leaves consent to your page; pass the choice as `confirmParams.savePaymentMethod`.

FieldConfig:

Key	Type	Description
`title`	`string`	Accessible name for the field.
`placeholder`	`string`	Placeholder text. Placeholders never prefill a value.
`hideIcon`	`boolean`	Hides the brand indicator on `cardNumber` or the icon on `cardCvc`.

Styles

styles takes one object per state. Each value is a CSS value string. Selectors, URLs, fonts loaded from other origins, and stylesheets are not accepted.

State	Applies to	Accepted properties
`base`	Every field at rest	Text and field properties
`focus`	The focused field	Text and field properties
`invalid`	A field with a visible validation error	Text and field properties
`placeholder`	Placeholder text	Text properties only

Text properties: color, fontFamily, fontSize, fontWeight, fontStyle, lineHeight, letterSpacing, textAlign. Field properties: backgroundColor, borderColor, borderRadius, borderStyle, borderWidth, boxShadow, outlineColor, outlineOffset, outlineStyle, outlineWidth, padding. An alternative configuration for the create call above:

const payment = blocks.create("payment", {
  layout: "stacked",
  gap: 8,
  fields: { cardNumber: { placeholder: "Card number", hideIcon: true } },
  styles: {
    base: { fontFamily: "Inter, sans-serif", fontSize: "16px", borderRadius: "6px" },
    placeholder: { color: "#8a8f98" },
    focus: { borderColor: "#111111", boxShadow: "0 0 0 1px #111111" },
    invalid: { borderColor: "#b42318" },
  },
});

Mount

await payment.mount("#payment");

Argument	Type	Description
`target`	`string` \| `HTMLElement`	A CSS selector or element. The element must be in the document and empty.

Resolves after the fields are ready and emits ready. Mounting a Block twice, or into an element that is missing, detached, or not empty, rejects with invalid_request. If the fields cannot load, or an option passed to create is invalid, mount rejects with collection_unavailable and emits the same error. When the intent is no longer collectable, for example after it has succeeded on a previous page load, mount renders a short status line instead of the fields and resolves. Your page can read the intent’s state from a change event or from retrievePaymentIntent.

Events

payment.on(eventName, listener) subscribes to a Block event. on returns a function that removes the listener. Exceptions thrown by a listener are ignored.

Event	Payload	When
`ready`	none	Mount initialization completed. The Block may show intent status instead of fields.
`change`	`BlockChange`	Field completion or card metadata changed, or the intent’s state was refreshed.
`error`	`BlockError`	The fields could not load, the collection session was replaced, or a mount failed. See Error codes.

BlockChange:

Field	Type	Description
`complete`	`boolean`	Whether every field passed its latest validation. Advisory; confirmation validates again.
`paymentIntent`	`BlockIntent`	The PaymentIntent’s current state, once known. Present for PaymentIntent Blocks.
`setupIntent`	`BlockIntent`	The SetupIntent’s current state, once known. Present for SetupIntent Blocks.
`card`	`CardMetadata` \| `null`	Optional. Present on field changes: provisional card metadata, or `null` when unavailable. Omitted when the event reports an intent-state refresh.

BlockIntent:

Field	Type	Description
`id`	`string`	The intent ID (`pi_…` or `seti_…`).
`object`	`"payment_intent"` \| `"setup_intent"`	The intent type.
`status`	`string`	`requires_payment_method`, `requires_confirmation`, `processing`, `requires_action`, `requires_capture`, `succeeded`, or `canceled`.
`amount`	`number`	Amount in minor units. PaymentIntents only.
`currency`	`string`	Three-letter currency code.
`payment_method`	`string`	The saved payment method ID (`pm_…`), when one exists.

CardMetadata carries the card’s bin (the first 6 to 8 digits, or null), brand (or null), funding (credit, debit, prepaid, or unknown), and source (lookup while the customer types, tokenize after submission). It is provisional and never a basis for fees, acceptance, or fulfillment.

Destroy

blocks.destroy();

Removes the Block’s UI and listeners. Both blocks.destroy() and payment.destroy() destroy the whole instance. A confirmation already sent continues to completion on the intent; destroying never creates a replacement intent. Call it when the payment view unmounts, and before creating a Blocks instance for another intent or merchant.

Confirm

Intent type	Method
PaymentIntent	`ionic.confirmPayment({ blocks, confirmParams })`
SetupIntent	`ionic.confirmSetup({ blocks, confirmParams })`

These are alternative operations for their respective intent types. The method is called in response to the customer’s submission after mounting.

Argument	Type	Description
`blocks`	`IonicBlocks`	The instance whose Block collected the card. `confirmPayment` requires a PaymentIntent instance and `confirmSetup` a SetupIntent instance; a mismatch returns `invalid_request`.
`confirmParams.billingDetails`	`BlockBillingDetails`	Optional. `name`, `email`, `phone`, and `address` with `line1`, `line2`, `city`, `state`, `postal_code`, and `country`.
`confirmParams.savePaymentMethod`	`boolean`	Only with `saveConsent: "external"`. `true` requests saving; `false` or omission does not. Passing it in `auto` mode returns `invalid_request`.

Results:

Field	Type	Description
`paymentIntent` / `setupIntent`	`BlockIntent`	The intent’s state after the call, when known.
`savedPaymentMethod`	`string`	`confirmPayment` only. The payment method ID when the card was saved in this response.
`error`	`BlockError`	Present when the call did not reach a successful state. Can accompany an intent, for example `payment_failed` with the intent back in `requires_payment_method`.

Behavior:

Concurrent calls share one in-flight confirmation; the second call receives the same promise.
Confirmation validates consent and card details before submitting a new attempt. Missing required consent returns consent_required; incomplete fields return incomplete_payment_details. An uncertain earlier attempt is checked before collecting new details.
Each attempt sends one idempotency key. After payment_status_unknown, calling again with the same blocks instance checks the existing intent and can replay the original request if the intent remains collectable. The attempt’s key, token, and saving choice are kept in memory on that instance; they do not survive a reload.
A card decline returns payment_failed with the intent in requires_payment_method; the customer corrects the card and your page calls confirm again on the same instance.
requires_action returns authentication_required. Blocks does not run 3DS challenges; the intent still requires action and has not succeeded.
Requests time out after 30 seconds.

Retrieve

Intent type	Method
PaymentIntent	`ionic.retrievePaymentIntent(clientSecret)`
SetupIntent	`ionic.retrieveSetupIntent(clientSecret)`

Reads the intent’s current state with the publishable key and client secret, without a Blocks instance. Returns the matching intent and/or error. savedPaymentMethod is not returned by retrieval. A malformed secret, request failure, or unreadable response returns payment_status_unknown; a well-formed secret of the other intent type returns invalid_request. See Payment events for server-side state.

Error codes

Errors are { type, code, message }. message is written for the customer and safe to display. type groups the codes: validation_error (the customer or your page can correct it), payment_error (the payment itself), and api_error (the form or the connection).

Code	Type	When	What to do
`invalid_request`	`validation_error`	A malformed key, secret, or `account`; `create` called twice, with an unknown type, or with an unsupported `saveConsent`; an invalid mount target; `savePaymentMethod` outside external consent mode; consent given on an intent that does not allow saving; a rejected request other than a decline.	Fix the integration.
`incomplete_payment_details`	`validation_error`	A field is empty or invalid at confirmation.	Keep the same Block; the fields show which entry needs attention.
`consent_required`	`validation_error`	A save-only intent was confirmed without consent.	Ask the customer to check the consent box, then confirm again.
`card_details_required`	`validation_error`	The collection session was replaced, for example after it expired, and the entered card was cleared.	Ask the customer to enter their card again on the same Block.
`payment_failed`	`payment_error`	The card was declined or the confirmation left the intent collectable.	Show `message`; let the customer try another card on the same intent.
`authentication_required`	`payment_error`	The intent requires an authentication step that Blocks does not run.	The intent still requires authentication and has not succeeded.
`payment_canceled`	`payment_error`	The intent is `canceled`.	Show `message`; create a new intent if the customer wants to pay again.
`not_ready`	`api_error`	Confirm was called before `mount` resolved, or while the fields were being refreshed.	Wait for mount to resolve or the field refresh to finish. A refresh does not emit another `ready` event.
`destroyed`	`api_error`	A call after `destroy`.	Create a new Blocks instance.
`collection_unavailable`	`api_error`	The secure fields could not load or stopped working, or an option passed to `create` is invalid.	Let the customer try again; mount a new Block if the error came from `mount`. Check the options if it repeats.
`payment_status_unknown`	`api_error`	No verifiable result arrived, for example a timeout during confirmation.	Call confirm again on the same instance or retrieve the intent. Do not create a new intent.

Start here

Accept payments

Ionic Blocks

Connect

Recurring billing

After the payment

Build commerce

Concepts

Available Blocks

Create a client

Create Blocks

Create a Block

Options

Styles

Mount

Events

Destroy

Confirm

Retrieve

Error codes

​Available Blocks

​Create a client

​Create Blocks

​Create a Block

​Options

​Styles

​Mount

​Events

​Destroy

​Confirm

​Retrieve

​Error codes

Available Blocks

Create a client

Create Blocks

Create a Block

Options

Styles

Mount

Events

Destroy

Confirm

Retrieve

Error codes