Learn Core concepts and prerequisites
Checkout SDK is a browser library that lets Merchants accept payments directly on their own Checkout page. Sensitive card data is collected through secured iFrames hosted on the payment platform’s domain, helping reduce the Merchant’s PCI DSS scope.
The SDK uses a modular core + features architecture. The core manages the payment session, state, and 3D Secure, while Payment methods are added as features. The current version includes the HPF feature for card payments.
The SDK is available through the @corefy/checkout-sdk npm package or a CDN bundle. It supports custom field styles, placeholders, and 3D Secure presentation, as well as ready-to-display messages, localisation keys, and typed errors.
Core concepts and flows
| Concept | Description |
|---|---|
Payment Request (pr_...) |
A Payment Request is the “invoice” your backend creates via the platform's private API before Checkout begins. Its id is passed to init(). |
Payment Method Scheme (pss_...) |
The Payment method scheme the funds will be charged through. Your backend obtains its id from the private API or the admin panel. The SDK does not provide a list of Methods; choosing the Scheme is your backend's decision. |
| Feature | A Payment method module. Currently hpf represents hosted card fields. A feature only comes alive after an explicit checkout.initFeature(type) call. |
| Bridge | A hidden service iFrame on the platform's domain through which the SDK talks to the Checkout backend. You never manage it yourself; the timeout / initTimeout settings apply to it. |
| Next action (directive) | An instruction describing “what should happen next” — show the form, show a loader, redirect to 3DS, allow a retry, and so on. Delivered via the next_action event. |
| Display status | A precomputed answer to “what should the user see right now” (getStatus()). You never interpret raw transaction statuses yourself. |
Review prerequisites
Before integrating SDK, you need:
| Value | Description |
|---|---|
apiKey |
The account's public API key located in the platform admin panel, under the Hosted Fields section. |
merchantAccountId |
The Merchant account identifier located in the platform admin panel. |
paymentRequestId ( |
The value is created by your backend via the private API for every payment. |
paymentMethodSchemeId ( |
The Payment method scheme identifier is obtained from the private API or the admin panel and passed to submit(), not to init(). |
baseUrl |
The value represents the platform domain (or your white-label domain) that hosts the fields, the bridge, and the Checkout API. For example: https://pay.example.com. |
The public apiKey is intended for use in the browser. Private API secret keys must never be exposed in frontend code.
Updated about 19 hours ago