For AI agents: visit https://docs.corefy.com/llms.txt for an index of all pages formatted in Markdown and endpoints in OpenAPI. Append .md to any documentation page URL to get its markdown version.
The CheckoutInstance API provides the main interface for controlling the checkout lifecycle, managing features, submitting payments, and responding to payment state changes. Its API also exposes dedicated Hosted Payment Fields handles for field-level validation, state control, events, and dynamic customisation.
Methods
Method
Description
on(event, cb): Unsubscribe
Subscribe to an event ('ready' | 'next_action' | 'error'). Returns an unsubscribe function.
getState(): CheckoutState
The latest known snapshot of the payment state: stage (payment | processing | final | error), directives, display, final, raw statuses (for debugging only — do not interpret them).
getStatus(): DisplayStatus
What to show the user right now. Pull model; the push equivalent is the next_action directives.
feature<T>(type): T | undefined
A typed handle of a live feature (e.g. checkout.feature<HpfHandle>('hpf')). undefined for an unknown type and for any type before its initFeature() completes.
initFeature(type): Promise<void>
Creates and initializes a feature — the only way to bring it "alive" (mounts iframe fields, etc.). Idempotent: a repeated call for an already initialized type is a no-op; concurrent calls share a single initialization. Rejects with feature_error for an unknown type or a type outside the session configuration, as well as when the feature's own init failed (a later call may then try again).
submit(opts): Promise<void>
Collects the feature's payload (card data tokenization), creates a payment attempt, and starts consuming its state.
retry(): Promise<void>
Repeats the last submit() with the same options without customer involvement. Use it only when there is no form on the page to bring back; the normal retry path is the next "Pay" click (a new submit() re-reads the fields). Rejects with invalid_submit_options if no submit() has happened on this instance yet.
destroy(): void
Unmounts all iFrames and internal services. Idempotent. After it, any method call → a destroyed error.
Submit() options
Option
Type
Description
paymentMethodSchemeId *
string
The payment method scheme identifier (pss_…) — issued by your backend (private API / admin panel); the SDK has no list of methods. A missing/empty value → an immediate invalid_submit_options rejection before tokenization and any network activity. A syntactically valid but unknown ID is not checked locally — it comes back from processing as a 422 (process_failed / api_error).
featureType
string
Which feature provides the payment payload. If set, the feature must be initialized and have collect(), otherwise invalid_submit_options. If not set and exactly one initialized feature provides a payload — that one is used; if several — a rejection with invalid_submit_options listing the available types. Recommendation: always pass it explicitly.
