Finyx Store

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' },
});
  • createElement before init throws.
  • init twice with the same key reuses the instance; a different key replaces it.
  • After init, you can also call the module helper createElement(...) (Airwallex-style).
  • Script tag (UMD): await Finyx.init(...) then Finyx.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

KindTypes
Drop-in / layoutcheckout, payment-method-list, card, payment-result
Familiesqr (PayNow, WeChat), wallet (Apple Pay, Google Pay), alipay (alipay / alipaycn / alipayhk), redirect
Atomicspaynow, wechatpay, applepay, googlepay, alipay, alipaycn, alipayhk

resolveElementType map:

  • card → card
  • paynow / wechatpay → qr
  • applepay / googlepay → wallet
  • alipay / 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]):

PrefixHost
devhttp://localhost:32022
test / playgroundhttps://awx-api-pay-demo.koomi.app
sandboxhttps://api-sandbox.koomipay.com
livehttps://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 + success
  • 3DS-Error → close + error

How this fits authorize vs capture, QR polling, and method families: Payment collection.