Integration guide
Add Finyx checkout UI to a website. Payment methods render in your page (not an iframe). Card PAN never touches merchant DOM — Adyen Web and Airwallex Elements own those fields.
Use @finyxpay/ui in vanilla JavaScript, or @finyxpay/react-ui in React / Next.js.
Install
npm install @finyxpay/ui
# React / Next.js:
npm install @finyxpay/ui @finyxpay/react-ui
Import styles once:
import '@finyxpay/ui/styles.css';
// or, in a React app:
import '@finyxpay/react-ui/styles.css';
Init
Call init once with a public outlet API key. apiBase is optional.
import { init, createElement } from '@finyxpay/ui';
import '@finyxpay/ui/styles.css';
const finyx = await init({
apiKey: 'live.xxx',
// apiBase: 'https://custom-host', // optional override
appearance: { theme: 'default' },
});
createElementbeforeinitthrows.inittwice with the same key reuses the instance; a different key replaces it.- After
init, you can also call the module helpercreateElement(...)(Airwallex-style). - Script tag (UMD):
await Finyx.init(...)thenFinyx.createElement(...).
Drop-in checkout
Mount a full checkout: method list, then pay.
const checkout = await finyx.createElement('checkout', {
amount: 25.5,
currency: 'SGD',
orderId: 'ord_123',
items: [{ productID: '1', productName: 'Mug', quantity: 1, price: 25.5 }],
returnUrl: `${location.origin}/checkout/result`,
autoCapture: true,
});
checkout.mount('#finyx-checkout');
checkout.on('state-change', (state) => {
if (state.event === 'qr') { /* log state.paymentId, state.qrCode */ }
if (state.event === 'success') { /* navigate with state.paymentId */ }
if (state.event === 'error') { /* show state.message */ }
});
Shared pay options: amount, currency, orderId, items, returnUrl (optional), autoCapture, paymentMethod.
Events: ready, select (list only), change, state-change, success, error.
state-change carries the whole payment flow: created, qr (qrCode, expiresAt), redirect (url), expired, success (paymentId, orderId, resultCode, status), and error (message, optional code). One state-change listener can handle the outcome. success and error still fire with the same payloads. QR expiry emits expired, then error.
Custom composition
The store demo only mounts drop-in checkout. Build your own layout with the method list plus a family or atomic pay element.
Family elements
One component per group. Map the selected method with resolveElementType.
import { init, resolveElementType } from '@finyxpay/ui';
const finyx = await init({ apiKey: 'live.xxx' });
const list = await finyx.createElement('payment-method-list', {});
list.mount('#methods');
list.on('select', async (method) => {
const type = resolveElementType(method.type);
const pay = await finyx.createElement(type, {
amount: 25.5,
currency: 'SGD',
orderId: 'ord_123',
items: [/* ... */],
returnUrl: `${location.origin}/checkout/result`,
paymentMethod: method,
});
pay.mount('#pay');
pay.on('success', (result) => { /* navigate */ });
});
React:
const family = method ? resolveElementType(method.type) : null;
<PaymentMethodList onSelect={setMethod} />
{method && family === 'card' ? <Card {...payProps} paymentMethod={method} /> : null}
{method && family === 'qr' ? <QRPay {...payProps} paymentMethod={method} /> : null}
{method && family === 'wallet' ? <WalletPay {...payProps} paymentMethod={method} /> : null}
{method && family === 'alipay' ? <Alipay {...payProps} paymentMethod={method} /> : null}
{method && family === 'redirect' ? <RedirectPay {...payProps} paymentMethod={method} /> : null}
Atomic elements
One component per method type. Atomic names also work in vanilla: createElement('paynow', ...), createElement('alipaycn', ...), …
<PaymentMethodList onSelect={setMethod} />
{method?.type === 'card' ? <Card {...payProps} paymentMethod={method} /> : null}
{method?.type === 'paynow' ? <PayNow {...payProps} paymentMethod={method} /> : null}
{method?.type === 'wechatpay' ? <WeChatPay {...payProps} paymentMethod={method} /> : null}
{method?.type === 'applepay' ? <ApplePay {...payProps} paymentMethod={method} /> : null}
{method?.type === 'googlepay' ? <GooglePay {...payProps} paymentMethod={method} /> : null}
{method?.type === 'alipay' ? <Alipay {...payProps} paymentMethod={method} /> : null}
{method?.type === 'alipaycn' ? <AlipayCN {...payProps} paymentMethod={method} /> : null}
{method?.type === 'alipayhk' ? <AlipayHK {...payProps} paymentMethod={method} /> : null}
Element types
| Kind | Types |
|---|---|
| Drop-in / layout | checkout, payment-method-list, card, payment-result |
| Families | qr (PayNow, WeChat), wallet (Apple Pay, Google Pay), alipay (alipay / alipaycn / alipayhk), redirect |
| Atomics | paynow, wechatpay, applepay, googlepay, alipay, alipaycn, alipayhk |
resolveElementType map:
card→cardpaynow/wechatpay→qrapplepay/googlepay→walletalipay/alipaycn/alipayhk→alipay- anything else →
redirect
Adyen exposes a single alipay (no CN/HK split). Airwallex / v4 uses alipaycn and alipayhk. The Alipay family accepts all three.
React
import { FinyxProvider, Checkout, PayNow } from '@finyxpay/react-ui';
import '@finyxpay/react-ui/styles.css';
<FinyxProvider apiKey="live.xxx" apiBase={optional}>
<Checkout
{...payProps}
onStateChange={(state) => {
if (state.event === 'qr') log(state.paymentId, state.qrCode)
if (state.event === 'success') go(state.paymentId)
if (state.event === 'error') show(state.message)
}}
/>
<PayNow
{...payProps}
paymentMethod={method}
onStateChange={(state) => {
if (state.event === 'qr') log(state.qrCode, state.expiresAt)
if (state.event === 'success') go(state.paymentId)
if (state.event === 'error') show(state.message)
}}
/>
</FinyxProvider>
Family and atomic React examples are in Custom composition above. Import PaymentMethodList, Card, QRPay, WalletPay, Alipay, RedirectPay, PayNow, WeChatPay, ApplePay, GooglePay, AlipayCN, and AlipayHK from @finyxpay/react-ui, and resolveElementType from @finyxpay/ui.
Requires React 18+. Components are already marked 'use client' for Next.js App Router. useFinyx() throws if used outside FinyxProvider.
Props map to vanilla events: onReady, onSelect, onStateChange, onSuccess, onError.
API key → apiBase
apiBase is optional. If omitted, the host is inferred from the key prefix (apiKey.split('.')[0]):
| Prefix | Host |
|---|---|
dev | http://localhost:32022 |
test / playground | https://awx-api-pay-demo.koomi.app |
sandbox | https://api-sandbox.koomipay.com |
live | https://api.koomipay.com |
Unknown prefix without apiBase throws Invalid API Key. A non-empty apiBase always wins (trailing slash stripped).
Payments call POST /api/v4/payments with iframe3ds: true so Adyen 3-D Secure can return in-page instead of a full redirect.
Collection workflows (client-side card/wallets vs server-side QR/Alipay), autoCapture, and polling: Payment collection.
Appearance and wordmark
await init({
apiKey: 'live.xxx',
appearance: {
theme: 'default', // 'default' | 'minimal' | 'night'
showWordmark: true, // default true — “Powered by Finyx”
variables: { colorPrimary: '#dc2626' },
},
});
Or set tokens on .fy (the checkout root) after importing styles:
.fy {
--fy-color-primary: #dc2626;
--fy-color-bg: #fff;
--fy-color-text: #171717;
--fy-color-muted: #71717a;
--fy-color-danger: #dc2626;
--fy-color-border: #e4e4e7;
--fy-radius: .75rem;
--fy-font: ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
}
appearance.variables maps to the same tokens (colorPrimary → --fy-color-primary, colorBackground → --fy-color-bg, colorText, colorMuted, colorDanger, borderRadius, fontFamily). CSS on .fy also covers --fy-color-border.
Adyen 3DS
Airwallex already runs 3DS inside its Elements UI — this library does not wrap that.
Adyen redirect / redirect_iframe opens a full-viewport modal with an iframe. Native 3DS2 (IdentifyShopper / ChallengeShopper) mounts Adyen’s challenge in the same modal. The modal listens for window.postMessage from the v4 callback:
3DS-Success→ close +success3DS-Error→ close +error
How this fits authorize vs capture, QR polling, and method families: Payment collection.