Widget attributes

Every attribute the leapa-customer element accepts, with defaults, requirements and limits.

This page lists every attribute <leapa-customer> reads, what each one does, and the rules the widget checks before it renders. If you are adding the widget for the first time, start with the quickstart.

One error at a time, and it is on the console

The widget validates its attributes on every render. A failed rule replaces the whole form with a red banner, which tells the payer to contact you and names nothing. The widget writes the failing attribute to your browser console instead, prefixed [LEAPA WIDGET]. It reports only the first failing rule, so fix them one at a time. The quickstart shows the banner.

Required attributes

Three attributes are required in every mode:

api-key: the API key from your account settings, issued for the currency account you are charging
mode: add, charge or invoice
description: what the payment is for, shown in your Leapa dashboard and on the payer’s statement

Three more are required in one mode each:

amount: required when mode is charge
invoice-id: required when mode is invoice
currency: required when mode is add

Set currency in every mode

Only add enforces it, but the value is sent with every payment, and it decides whether BurundiPay can appear.

All attributes

Attribute	Default	Dynamic
`api-key`required Your Leapa API key. It must be issued for the currency account you are charging, and for a country the widget serves. A key that is missing, unreadable, or issued for an unsupported country shows the payer a banner and names the reason on the console	—	No
`mode`required What the form does on submit: add saves a card, charge takes money now, invoice settles an invoice you already created. BurundiPay is offered in invoice mode only	—	No
`description`required What the payment is for. Required in every mode, including add	—	No
`currency`conditional BIF, USD, XAF or KES. Must match the currency account your API key belongs to. Enforced in add mode, and needed in every mode because it is sent with the payment. BurundiPay settles BIF only	—	No
`amount`conditional Amount in the currency’s main unit, not cents. Required when mode is charge. Optional for invoice, but pass it so BurundiPay can show the figure on the Pay button. Must sit inside the limits for the currency	—	No
`invoice-id`conditional ID of the invoice to settle. Required when mode is invoice, ignored otherwise	—	No
`customer-id`optional ID of an existing customer. When set, the widget hides the name and email fields and attaches the card to that customer. The billing address is still collected. Cannot be combined with email	—	No
`source-type`optional Which payment methods to offer: all, card, burundipay, burundipay-qr or burundipay-phone. A value the merchant’s country does not support shows a banner rather than falling back to card	`all`	No
`lang`optional UI language: en or fr. Translates every label, placeholder, validation message and backend error. The widget watches this attribute, so changing it after load re-renders in the new language	`en`	No
`theme`optional light, dark, or auto to follow the payer’s device. Unset leaves the background transparent so the widget sits on whatever your page paints behind it	—	No
`email`optional Prefills the payer’s email and hides the field. Omit it and the payer types their own. Not allowed together with customer-id	—	Yes
`first-name`optional Prefills the payer’s first name and hides the field. Omit it and the payer types their own. Must be used together with last-name	—	Yes
`last-name`optional Prefills the payer’s last name and hides the field. Omit it and the payer types their own. Must be used together with first-name	—	Yes
`dob`optional Set to true to add a date of birth field, which is otherwise absent. A date passed here is neither shown nor sent	—	Yes
`tos`optional Set to true to show a required checkbox above the button, linking to Leapa’s terms of service. Any other value hides it	—	No
`badge`optional Shows the Secured by Leapa badge under the form. Use light or dark to pick the artwork; true means light. Omit the attribute to hide it. The badge belongs to the whole widget, so it stays put when the payer switches method	—	No
`button-text`optional Replaces the card form’s submit button label. Without it the label follows the mode: Add source, Charge, or Pay invoice. BurundiPay ignores this and shows the amount instead	—	No
`debtor-alias`optional BurundiPay only. The payer’s phone number, so they do not type it. Prefills the phone rail; the payer still presses Pay before any request is sent	—	No
`debtor-account`optional BurundiPay only. The payer’s bank account number, as an alternative to debtor-alias. Use together with debtor-bank-bic	—	No
`debtor-bank-bic`optional BurundiPay only. The bank identifier code for debtor-account	—	No
`id`optional Standard HTML id. Give each widget a different id when you place more than one on a page, so your event listeners can tell them apart	—	No

The card form always collects the card number, expiry, security code and a billing address. The rest of the fields depend on four attributes, which is what the Dynamic column marks.

Three of them start visible and disappear when you fill them in:

The payer sees first-name, last-name and email by default, and all three are required.
Pass a real value and the widget prefills it and hides the field.
first-name and last-name must be set together. Passing one without the other is an error.

dob works the other way round. There is no date of birth field unless you write dob="true", and a date passed as dob="1990-04-12" is neither shown nor sent.

customer-id removes the three name and email fields in one go, because the customer record already holds them. The billing address is still collected, and email alongside customer-id is an error.

Payment methods by country

The merchant country comes from your API key, not from an attribute. It decides which methods exist before source-type narrows them:

Merchant country	Methods
Burundi (BI)	Card, BurundiPay
Cameroon (CM)	Card

BurundiPay needs three more conditions on top of the country, all of which must hold: mode="invoice", currency="BIF", and your Leapa account enabled for instant bank payments. BurundiPay covers what happens when one of them does not.

A key issued for any other country shows the payer a banner instead of a form, and names the country on your console.

Amount limits

Each currency has a minimum and a maximum. An amount outside them replaces the form with a banner:

Currency	Minimum	Maximum
USD	0.50	5,000.00
BIF	3,000	10,000,000
XAF	500	5,000,000

Write the amount in the main unit. For USD that means dollars: amount="25" charges 25.00 USD, not 25 cents. The widget converts USD to cents before it calls the API, so the charge object comes back as 2500. BIF and XAF have no minor unit and pass through unchanged.

One row in that table has an edge worth knowing about:

BIF: the widget’s own checks are 2,000 and 20,000,000, wider than the API’s. An amount from 2,000 to 2,999, or above 10,000,000, shows the form but the payment is refused when it reaches the API. Keep BIF amounts from 3,000 to 10,000,000.

Validation rules

Beyond the required attributes and the amount limits, the widget checks five combinations:

first-name and last-name must be used together. One without the other is an error.
customer-id and email cannot both be set. The customer ID already identifies the payer.
mode must be exactly add, charge or invoice.
currency must be exactly BIF, USD, XAF or KES.
source-type must be one of the five listed values, and must name a method the merchant’s country supports.

Colour, theme and layout

Two attributes change how the widget looks: theme and lang. Colours, spacing and control sizes come from CSS custom properties you can set from your own stylesheet. Theming documents both.

View as markdown

Last updated September 23, 2026