# 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](/docs/widgets/integration).

<Callout type="note" title="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](/docs/widgets/integration#add-the-element) shows the banner.
</Callout>

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

<Callout type="warning" title="Set currency in every mode">
	Only `add` enforces it, but the value is sent with every payment, and it
	decides whether BurundiPay can appear.
</Callout>

## All attributes

<Table data={[
	{
		id: 1,
		prop: "api-key",
		dynamic: "No",
		req: { label: "required", color: "red" },
		defaultValue: null,
		description: "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",
	},

	{
		id: 2,
		prop: "mode",
		dynamic: "No",
		req: { label: "required", color: "red" },
		defaultValue: null,
		description: "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",
	},

	{
		id: 3,
		prop: "description",
		dynamic: "No",
		req: { label: "required", color: "red" },
		defaultValue: null,
		description: "What the payment is for. Required in every mode, including add",
	},

	{
		id: 4,
		prop: "currency",
		dynamic: "No",
		req: { label: "conditional", color: "orange" },
		defaultValue: null,
		description: "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",
	},

	{
		id: 5,
		prop: "amount",
		dynamic: "No",
		req: { label: "conditional", color: "orange" },
		defaultValue: null,
		description: "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",
	},

	{
		id: 6,
		prop: "invoice-id",
		dynamic: "No",
		req: { label: "conditional", color: "orange" },
		defaultValue: null,
		description: "ID of the invoice to settle. Required when mode is invoice, ignored otherwise",
	},

	{
		id: 7,
		prop: "customer-id",
		dynamic: "No",
		req: { label: "optional", color: "gray" },
		defaultValue: null,
		description: "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",
	},

	{
		id: 8,
		prop: "source-type",
		dynamic: "No",
		req: { label: "optional", color: "gray" },
		defaultValue: "all",
		description: "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",
	},

	{
		id: 9,
		prop: "lang",
		dynamic: "No",
		req: { label: "optional", color: "gray" },
		defaultValue: "en",
		description: "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",
	},

	{
		id: 10,
		prop: "theme",
		dynamic: "No",
		req: { label: "optional", color: "gray" },
		defaultValue: null,
		description: "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",
	},

	{
		id: 11,
		prop: "email",
		dynamic: "Yes",
		req: { label: "optional", color: "gray" },
		defaultValue: null,
		description: "Prefills the payer’s email and hides the field. Omit it and the payer types their own. Not allowed together with customer-id",
	},

	{
		id: 12,
		prop: "first-name",
		dynamic: "Yes",
		req: { label: "optional", color: "gray" },
		defaultValue: null,
		description: "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",
	},

	{
		id: 13,
		prop: "last-name",
		dynamic: "Yes",
		req: { label: "optional", color: "gray" },
		defaultValue: null,
		description: "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",
	},

	{
		id: 14,
		prop: "dob",
		dynamic: "Yes",
		req: { label: "optional", color: "gray" },
		defaultValue: null,
		description: "Set to true to add a date of birth field, which is otherwise absent. A date passed here is neither shown nor sent",
	},

	{
		id: 15,
		prop: "tos",
		dynamic: "No",
		req: { label: "optional", color: "gray" },
		defaultValue: null,
		description: "Set to true to show a required checkbox above the button, linking to Leapa’s terms of service. Any other value hides it",
	},

	{
		id: 16,
		prop: "badge",
		dynamic: "No",
		req: { label: "optional", color: "gray" },
		defaultValue: null,
		description: "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",
	},

	{
		id: 17,
		prop: "button-text",
		dynamic: "No",
		req: { label: "optional", color: "gray" },
		defaultValue: null,
		description: "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",
	},

	{
		id: 18,
		prop: "debtor-alias",
		dynamic: "No",
		req: { label: "optional", color: "gray" },
		defaultValue: null,
		description: "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",
	},

	{
		id: 19,
		prop: "debtor-account",
		dynamic: "No",
		req: { label: "optional", color: "gray" },
		defaultValue: null,
		description: "BurundiPay only. The payer’s bank account number, as an alternative to debtor-alias. Use together with debtor-bank-bic",
	},

	{
		id: 20,
		prop: "debtor-bank-bic",
		dynamic: "No",
		req: { label: "optional", color: "gray" },
		defaultValue: null,
		description: "BurundiPay only. The bank identifier code for debtor-account",
	},

	{
		id: 21,
		prop: "id",
		dynamic: "No",
		req: { label: "optional", color: "gray" },
		defaultValue: null,
		description: "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",
	},

]} />

## How the widget collects payer details

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](/docs/widgets/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](/docs/widgets/theming) documents both.

---

_Generated from the Leapa documentation at leapa.co/docs._