npm package: @finivex/payment-checkout
Description: Embeddable payment checkout widget for Finivex Payment Gateway
Latest version: 1.0.1

# @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

```bash
npm install @finivex/payment-checkout
```

## Quick Start

### Script Tag (IIFE)

```html
<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

```js
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

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

## Additional APIs

### Refund a Transaction

```js
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

```js
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