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: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.
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.
The field appearance options and
style properties 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
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.
The PaymentIntent reference defines states and
capture behavior; SetupIntents 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.
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 for the ownership fields
and Webhook delivery for acknowledgment and
retry semantics.