@finivex/payment-checkout

Embeddable payment checkout widget for the Finivex Payment Gateway. Drop a single script tag into your page or import as an ES module to collect payments via multiple providers in Zimbabwe and beyond.

Supported Payment Methods

| Method | Flow | |---|---| | EcoCash | USSD push | | OneMoney | USSD push | | Omari | OTP verification | | InnBucks | QR code scan | | Visa / Mastercard / MPGS | Card redirect | | ZIPIT | Bank transfer redirect | | POS | Pending confirmation | | Wallet | Wallet balance | | Cash | Cash tendered |

Installation

npm install @finivex/payment-checkout

Quick Start

Before you embed: register your site's origin(s) under Portal → Settings → Allowed Origins. The API rejects cross-origin calls from unregistered origins. See the Allowed Origins guide in the portal.

Step 1 — Mint a session token on your backend

Your server calls the gateway with its API key + secret and gets back a short-lived sessionToken bound to a single transactionId + amount + currency. Never expose the secret to the browser.

curl -X POST https://gateway.finivex.online/api/pg/v1/payments/widget-session \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: pk_live_your_api_key' \
  -H 'X-API-Secret: sk_live_your_api_secret' \
  -d '{"transactionId":"order_123","amount":10.00,"currency":"USD"}'

Response:

{
  "success": true,
  "data": {
    "sessionToken": "eyJhbGciOiJIUzUxMiJ9...",
    "expiresAt": "2026-04-18T17:50:00Z",
    "transactionId": "order_123",
    "amount": 10.00,
    "currency": "USD"
  }
}

The token expires in 5 minutes and cannot be used for any transaction other than the one it was minted for.

Step 2 — Open the widget in the browser

Script tag (IIFE)

<script src="https://unpkg.com/@finivex/payment-checkout/dist/checkout.iife.js"></script>
<script>
  PayGateway.checkout({
    apiKey:        'pk_live_your_api_key',
    sessionToken:  'eyJhbGciOiJIUzUxMiJ9...',  // from step 1
    apiUrl:        'https://gateway.finivex.online/api/pg',
    amount:        10.00,
    currency:      'USD',
    transactionId: 'order_123',
    description:   'Payment for Order #123',
    merchantName:  'My Store',
    onSuccess: (result) => console.log('Paid!', result),
    onError:   (error)  => console.error('Failed', error),
    onCancel:  ()       => console.log('Cancelled'),
  });
</script>

ES module

import { checkout } from '@finivex/payment-checkout';

checkout({
  apiKey:        'pk_live_your_api_key',
  sessionToken:  sessionTokenFromServer,
  apiUrl:        'https://gateway.finivex.online/api/pg',
  amount:        25.00,
  currency:      'USD',
  transactionId: 'order_456',
  onSuccess: (result) => { /* handle success */ },
  onError:   (error)  => { /* handle error */ },
});

Legacy / same-origin only: the widget still accepts apiSecret instead of sessionToken for backwards compatibility with same-origin callers (e.g. the Finivex-hosted checkout page). Never ship apiSecret to a browser on a merchant site — cross-origin requests with X-API-Secret are rejected by CORS, and anyone viewing page source can steal the secret. Always use sessionToken.

Configuration

| Option | Type | Required | Description | |---|---|---|---| | apiKey | string | Yes | Your public API key (pk_live_…). Safe to embed in browser code. | | sessionToken | string | Yes (browser) | Short-lived JWT minted server-side via POST /v1/payments/widget-session. Required for cross-origin use. | | apiSecret | string | Legacy only | Deprecated for browser use. Retained for same-origin callers; will be removed in a future release. | | apiUrl | string | Yes | Payment gateway API base URL | | amount | number | Yes | Amount to charge (must be > 0) | | currency | 'USD' \| 'ZWG' | Yes | Payment currency | | transactionId | string | Yes | Unique transaction identifier | | description | string | No | Payment description shown to the customer | | merchantName | string | No | Merchant name displayed in the checkout modal | | customerPhone | string | No | Pre-fill customer phone number | | customerEmail | string | No | Pre-fill customer email | | callbackUrl | string | No | URL for server-to-server payment notifications | | methods | PaymentMethodType[] | No | Restrict available payment methods | | theme | Partial<ThemeConfig> | No | Customize look and feel | | locale | string | No | Locale for display strings | | onSuccess | (result: PaymentResult) => void | No | Called on successful payment | | onError | (error: PaymentError) => void | No | Called on payment failure | | onCancel | () => void | No | Called when the user closes the modal | | onStatusChange | (status: PaymentStatus) => void | No | Called on every status transition |

Theming

checkout({
  // ...required options
  theme: {
    primaryColor: '#4f46e5',
    fontFamily: '"Inter", sans-serif',
    borderRadius: '12px',
    logo: 'https://example.com/logo.png',
  },
});

Additional APIs

Refund a Transaction

import { refund } from '@finivex/payment-checkout';

await refund(
  { apiKey: 'pk_...', apiSecret: 'sk_...', apiUrl: 'https://api.example.com' },
  'txn_123',    // transactionId
  'Customer requested',  // reason
  'ECOCASH',    // original payment method
);

Check Provider Health

import { checkHealth } from '@finivex/payment-checkout';

const status = await checkHealth(
  { apiKey: 'pk_...', apiSecret: 'sk_...', apiUrl: 'https://api.example.com' },
  'ECOCASH',
);

Types

The package ships with full TypeScript definitions. Key exported types:

• CheckoutConfig -- full configuration object
• PaymentResult -- success callback payload
• PaymentError -- error callback payload
• PaymentMethodType -- union of supported method names
• CurrencyType -- 'USD' | 'ZWG'

License

MIT