Configuration
All options passed to mount(selector, config).
Config options
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
amount | number | Yes | — | Amount in major units (25.5 is 25.50). With clientSecret, the session’s amount. |
currency | string | Yes | — | ISO 4217 code your business accepts (USD, ZWG, KES …). With clientSecret, the session’s currency. |
reference | string | Yes | — | Your order or invoice reference |
clientSecret | string | No | — | The client_secret of a checkout session your server created (POST /v1/checkout/sessions). Recommended: the server decides the amount. |
paymentLinkSlug | string | No | — | Pay a payment link (its own amount and settings) |
invoiceSlug | string | No | — | Pay an invoice (its balance decides what may be charged) |
description | string | No | — | Short description shown to the customer |
tabs | ('card' | 'mobile_wallet' | 'zimswitch' | 'qr')[] | No | Every method your business offers | Limit the payment methods shown |
layout | 'inline' | 'split' | No | Checkout Studio setting | Methods above the form, or beside it on wide screens |
theme | WatengaTheme | No | Checkout Studio design | Colours, border radius and font family |
appearance | WatengaAppearanceConfig | No | Checkout Studio design | The full Checkout Studio appearance, plus your own variables and element rules |
branding | boolean | No | Checkout Studio setting | false hides the “Powered by Watenga” footer |
buttonLabel | string | No | Pay | Pay button text (the amount is added) |
customerName | string | No | — | Prefill the customer’s name |
customerEmail | string | No | — | Prefill the customer’s email (receipts) |
customerPhone | string | No | — | Prefill the mobile-money number |
customFieldValues | Record<string, string> | No | — | Stored with the transaction; never sent to payment providers |
attribution | Record<string, string> | No | — | Campaign tags (utm_source …) recorded on payment-link payments |
returnUrl | string | No | The current page | Where the card step sends the customer back; the page gets watenga_payment and watenga_status |
beforePayment | () => boolean | No | — | Return false to stop a payment (for example, your form is invalid) |
onReady | () => void | No | — | The checkout is on the page and ready (once per mount) |
onSuccess | (txn: WatengaTransaction) => void | Yes | — | The payment is confirmed (confirm it on your server too: re-read the transaction or wait for the webhook) |
onPending | (pending) => void | No | — | A payment is waiting on the customer (a mobile-money prompt on their phone) |
onCancel | (cancelled) => void | No | — | The customer cancelled or declined; nothing was charged and the checkout stays open |
onError | (err: WatengaError) => void | Yes | — | The payment failed or the checkout could not load |
onClose | () => void | No | — | The customer closed the checkout (modal) |