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.
Three attributes are required in every mode:
api-key: the API key from your account settings, issued for the currency account you are chargingmode: add, charge or invoicedescription: what the payment is for, shown in your Leapa dashboard and on the payer’s statementThree more are required in one mode each:
amount: required when mode is chargeinvoice-id: required when mode is invoicecurrency: required when mode is addSet currency in every mode
Only add enforces it, but the value is sent with every payment, and it
decides whether BurundiPay can appear.
| Property | Default | Dynamic |
|---|---|---|
api-keyrequired 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 default | No |
moderequired 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 default | No |
descriptionrequired What the payment is for. Required in every mode, including add | No default | No |
currencyconditional 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 default | No |
amountconditional 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 default | No |
invoice-idconditional ID of the invoice to settle. Required when mode is invoice, ignored otherwise | No default | No |
customer-idoptional 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 default | No |
source-typeoptional 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 |
langoptional 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 |
themeoptional 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 default | No |
emailoptional Prefills the payer’s email and hides the field. Omit it and the payer types their own. Not allowed together with customer-id | No default | Yes |
first-nameoptional 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 | No default | Yes |
last-nameoptional 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 | No default | Yes |
doboptional Set to true to add a date of birth field, which is otherwise absent. A date passed here is neither shown nor sent | No default | Yes |
tosoptional Set to true to show a required checkbox above the button, linking to Leapa’s terms of service. Any other value hides it | No default | No |
badgeoptional 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 default | No |
button-textoptional 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 default | No |
debtor-aliasoptional 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 default | No |
debtor-accountoptional BurundiPay only. The payer’s bank account number, as an alternative to debtor-alias. Use together with debtor-bank-bic | No default | No |
debtor-bank-bicoptional BurundiPay only. The bank identifier code for debtor-account | No default | No |
idoptional 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 default | 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:
first-name, last-name and email by default, and all three are required.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.
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.
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 | 2,000 | 20,000,000 |
| XAF | 500 | 5,000,000 |
| KES | no limit checked | no limit checked |
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.
Two rows in that table have an edge worth knowing about:
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.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.