> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Advanced: tokenization-only card fields

> Session, field, and token contracts for applications that own server-side confirmation.

Ionic's card fields collect the card number, expiry, and CVC inside secure
frames and return an opaque, single-use token. Tokenization creates no payment
and saves no card. Your backend decides how to use the token with a
PaymentIntent or SetupIntent.

[Ionic Blocks](/guides/payment-fields) combines collection and confirmation.
Use the interfaces here when your integration owns token handling and
server-side confirmation.

## Session contract

The page's origin must be registered in **Developers → Web domains** for the
merchant and mode. Scheme, hostname, and port must match. The server creates a
short-lived session using its secret key:

```bash theme={null}
curl https://api.ionicfi.com/v1/tokenization_sessions \
  -H "Authorization: Bearer $IONIC_SECRET_KEY" \
  -H "Idempotency-Key: $FIELD_SESSION_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"parent_origin":"https://pay.example.com"}'
```

`FIELD_SESSION_REQUEST_ID` represents the key assigned to this operation.
The browser receives the matching publishable key and the session's `id`,
`group_id`, `generation`, `frame_url`, and `expires_at`. The returned frame URL
and expiry are part of the session contract; they must not be altered.

| Resource      | Host                                 |
| ------------- | ------------------------------------ |
| Browser SDK   | `https://js.ionicfi.com/v1/ionic.js` |
| Secure frames | `https://embed.ionicfi.com`          |
| Server API    | `https://api.ionicfi.com`            |

A page's Content Security Policy must permit the SDK in `script-src` and the
returned frame's origin in `frame-src`.

## Mount the fields

`ionic.mountPaymentFields(target, { session })` returns a promise for the field
controller. `target` is an empty element in the document or its selector;
`session` is the response described above.

| Option     | Contract                                                                 |
| ---------- | ------------------------------------------------------------------------ |
| `session`  | The tokenization session returned by your server.                        |
| `layout`   | `split`, `stacked`, or `inline`. Defaults to `split`.                    |
| `gap`      | Integer spacing from 0 to 32 pixels.                                     |
| `fields`   | `cardNumber`, `cardExpiry`, and `cardCvc` appearance options.            |
| `styles`   | `base`, `placeholder`, `focus`, and `invalid` style objects.             |
| `onChange` | Receives field completion, focus, errors, and provisional card metadata. |
| `onError`  | Receives field-session errors, including terminal failures.              |

The [field appearance options](/guides/blocks-reference#options) and
[style properties](/guides/blocks-reference#styles) are also used by Blocks.
`saveConsent` is a Blocks-only option.

Placeholders do not prefill card details. Changing appearance requires another
mount and clears the existing entry. Card-brand indicators are decorative;
they do not establish which cards the merchant can accept.

## Field controller

| Method              | Contract                                                                                                           |
| ------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `fields.tokenize()` | Validates the entered details and returns `{ token, brand?, last4? }`. Invalid fields reject with `field_invalid`. |
| `fields.clear()`    | Clears values, completion, metadata, and displayed validation errors.                                              |
| `fields.destroy()`  | Removes the mounted fields and their listeners.                                                                    |

`onChange` contains `complete`, `fields`, and `card`. Each field reports
`complete`, optional `focused`, and an optional `error: "field_invalid"`.
Completion is advisory; tokenization validates again. Leaving an incomplete
field does not itself mark that field invalid.

`card` is `null` or `{ bin, brand, funding, source }`. BIN is at most 6–8 digits;
funding is `credit`, `debit`, `prepaid`, or `unknown`; source is `lookup` or
`tokenize`. Metadata is provisional and may be suppressed or cleared after
edits. It does not authorize fees, card acceptance, or fulfillment.

An expired or terminally failed session requires new fields. Session replacement
does not establish the outcome of a payment previously submitted with its token.

## Token and confirmation interfaces

The token is intended for your backend and must stay out of URLs, logs, and
analytics. Your backend owns customer authorization, the amount, and the
association between a token and the intended payment operation.

| Operation                               | API contract                                                                                                    |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Create a payment for later confirmation | `POST /v1/payment_intents` with the authorized amount and currency, without a token or payment method.          |
| Confirm that payment                    | `POST /v1/payment_intents/{id}/confirm` with `payment_token`.                                                   |
| Read a payment                          | `GET /v1/payment_intents/{id}` returns `{ payment_intent, charges }`.                                           |
| Confirm card saving                     | `POST /v1/setup_intents/{id}/confirm` with `payment_token`, subject to consent and the SetupIntent's ownership. |

The [PaymentIntent reference](/api-reference/payment-intents) defines states and
capture behavior; [SetupIntents](/guides/save-cards) defines saving. Card fields
do not run additional authentication challenges.

Tokens are single-use. Repeating a create or confirm API operation requires its
original body and idempotency key within the [idempotency window](/api-reference/idempotency).
A missing response is an unknown result, not proof of failure. Another intent
or another token can represent a new operation and does not recover the old one.

Ionic provides intent state and signed events. Your application owns payment
persistence, concurrency, retry policy, and fulfillment. See
[Payment events](/guides/payment-fields#payment-events) for the ownership fields
and [Webhook delivery](/webhooks/idempotency-and-retries) for acknowledgment and
retry semantics.