@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

Script Tag (IIFE)

<script src="https://unpkg.com/@finivex/payment-checkout/dist/checkout.iife.js"></script>
<script>
  PayGateway.checkout({
    apiKey: 'pk_...',
    apiSecret: 'sk_...',
    apiUrl: 'https://api.example.com',
    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_...',
  apiSecret: 'sk_...',
  apiUrl: 'https://api.example.com',
  amount: 25.00,
  currency: 'USD',
  transactionId: 'order_456',
  onSuccess: (result) => { /* handle success */ },
  onError: (error) => { /* handle error */ },
});

Configuration

| Option | Type | Required | Description | |---|---|---|---| | apiKey | string | Yes | Your public API key | | apiSecret | string | Yes | Your secret API key | | 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