Elements SDK reference: every export, option, event and error code of @pesepay/js, @pesepay/react, @pesepay/vue and @pesepay/angular # Elements SDK reference > Every export of the Pesepay Elements packages. Generated from each package’s type declarations. Shared types such as `Transaction` and the element options live in `@pesepay/js`; the framework packages add their components. | Package | What it holds | | ----------------------------------------------------------- | ----------------------------------------------------------------------- | | [`@pesepay/js`](/embedded-checkout/reference/js/) | The loader, the Pesepay instance, elements, events, results and errors. | | [`@pesepay/react`](/embedded-checkout/reference/react/) | ``, one component per element, and hooks. | | [`@pesepay/vue`](/embedded-checkout/reference/vue/) | ``, one component per element, and composables. | | [`@pesepay/angular`](/embedded-checkout/reference/angular/) | Standalone components and the injection helpers. | # @pesepay/angular > API reference for @pesepay/angular. Every public export of `@pesepay/angular`, generated from its type declarations. [@pesepay/angular on npm](https://www.npmjs.com/package/@pesepay/angular). ## Functions and components [Section titled “Functions and components”](#functions-and-components) | Name | Description | | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`injectElements`](/embedded-checkout/reference/angular/inject-elements/) | The elements group the enclosing `` created, as a signal. `null` while Pesepay loads and during server rendering. Read an element off it to pay with: `elements()?.getElement("card")`. Call it in an injection context, such as a constructor or a field initialiser. | | [`injectPesepay`](/embedded-checkout/reference/angular/inject-pesepay/) | The Pesepay instance the enclosing `` was given, as a signal. `null` while it loads and during server rendering. Call it in an injection context, such as a constructor or a field initialiser. | ## Components and classes [Section titled “Components and classes”](#components-and-classes) | Name | Description | | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`CardElement`](/embedded-checkout/reference/angular/card-element/) | Visa card fields in a Pesepay frame. Pay with `confirmPayment()` and `elements()?.getElement("card")`. | | [`CheckoutElement`](/embedded-checkout/reference/angular/checkout-element/) | The payment element with its own Pay button. It runs every step of the payment; listen for `(finished)`. A new `referenceNumber` replaces the element. | | [`Elements`](/embedded-checkout/reference/angular/elements/) | Creates one elements group for the element components inside it, and destroys it when it is destroyed. | | [`HostedCardElement`](/embedded-checkout/reference/angular/hosted-card-element/) | The card provider’s form for Mastercard and Zimswitch. One per page. | | [`MobileElement`](/embedded-checkout/reference/angular/mobile-element/) | EcoCash or O’mari phone number, and O’mari’s SMS code. | | [`PaymentElement`](/embedded-checkout/reference/angular/payment-element/) | Every method the transaction can be paid with. A new `referenceNumber` replaces the element. | | [`PesepayElementDirective`](/embedded-checkout/reference/angular/pesepay-element-directive/) | What every element component shares: it creates its element in the enclosing group once Pesepay has loaded, mounts it into its own host element, re-emits its events, passes changed `options` to `update()`, and destroys it with the component. | | [`ScanElement`](/embedded-checkout/reference/angular/scan-element/) | The InnBucks or PayGo code the customer scans. | # CardElement > Visa card fields in a Pesepay frame. Pay with `confirmPayment()` and `elements()?.getElement("card")`. Visa card fields in a Pesepay frame. Pay with [`confirmPayment()`](/embedded-checkout/reference/js/pesepay/#confirmpayment) and `elements()?.getElement("card")`. ```ts export declare class CardElement extends PesepayElementDirective<"card"> ``` ## Inputs and outputs [Section titled “Inputs and outputs”](#inputs-and-outputs) | Name | Type | Description | | --------- | ---------------------------------------------- | ----------------------------- | | `options` | `InputSignal` | Options for the card element. | # CheckoutElement > The payment element with its own Pay button. It runs every step of the payment; listen for `(finished)`. A new `referenceNumber` replaces the element. The payment element with its own Pay button. It runs every step of the payment; listen for `(finished)`. A new `referenceNumber` replaces the element. ```ts export declare class CheckoutElement extends PesepayElementDirective<"checkout"> ``` ## Inputs and outputs [Section titled “Inputs and outputs”](#inputs-and-outputs) | Name | Type | Description | | ---------- | ----------------------------------------- | ------------------------------------------------------------------------ | | `finished` | `OutputEmitterRef` | The payment has ended. Sent once. | | `options` | `InputSignal` | Options for the checkout element, with the transaction to pay. Required. | # Elements > Creates one elements group for the element components inside it, and destroys it when it is destroyed. Creates one elements group for the element components inside it, and destroys it when it is destroyed. Export it to a template variable to pay from the component that renders it: `#checkout="pesepayElements"`, then `checkout.instance()` and `checkout.elements()`. Both are `null` until Pesepay loads. Nothing loads before the first render in the browser: on the server the elements inside render empty. ```ts export declare class Elements ``` ## Inputs and outputs [Section titled “Inputs and outputs”](#inputs-and-outputs) | Name | Type | Description | | ---------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `elements` | `Signal` | The elements group, created once Pesepay has loaded. | | `instance` | `Signal` | The Pesepay instance once it has loaded. | | `options` | `InputSignal` | Applied to every element inside. A change is passed to `elements.update()`. | | `pesepay` | `InputSignal \| null \| undefined>` | What [`loadPesepay()`](/embedded-checkout/reference/js/load-pesepay/) returns: the promise itself, or the instance once it has resolved. Leave it out and Pesepay loads with the default options; pass `loadPesepay({ ... })` to set any of them. Call [`loadPesepay()`](/embedded-checkout/reference/js/load-pesepay/) once, in a field, not in the template. Fixed on first render: a different value later is ignored with a warning. | # HostedCardElement > The card provider's form for Mastercard and Zimswitch. One per page. The card provider’s form for Mastercard and Zimswitch. One per page. ```ts export declare class HostedCardElement extends PesepayElementDirective<"hostedCard"> ``` ## Inputs and outputs [Section titled “Inputs and outputs”](#inputs-and-outputs) | Name | Type | Description | | --------- | --------------------------------------- | ------------------------------------------------------------------------ | | `options` | `InputSignal` | Options for the hostedCard element, with the checkout to show. Required. | # injectElements > The elements group the enclosing `` created, as a signal. `null` while Pesepay loads and during server rendering. Read an element off it to pay with: `elements()?.getElement("card")`. Call it in an injection context, such as a constructor or a field initialiser. The elements group the enclosing `` created, as a signal. `null` while Pesepay loads and during server rendering. Read an element off it to pay with: `elements()?.getElement("card")`. Call it in an injection context, such as a constructor or a field initialiser. ```ts export declare function injectElements(): Signal; ``` # injectPesepay > The Pesepay instance the enclosing `` was given, as a signal. `null` while it loads and during server rendering. Call it in an injection context, such as a constructor or a field initialiser. The Pesepay instance the enclosing `` was given, as a signal. `null` while it loads and during server rendering. Call it in an injection context, such as a constructor or a field initialiser. ```ts export declare function injectPesepay(): Signal; ``` # MobileElement > EcoCash or O'mari phone number, and O'mari's SMS code. EcoCash or O’mari phone number, and O’mari’s SMS code. ```ts export declare class MobileElement extends PesepayElementDirective<"mobile"> ``` ## Inputs and outputs [Section titled “Inputs and outputs”](#inputs-and-outputs) | Name | Type | Description | | --------- | ------------------------------------------------ | -------------------------------------------------------------------------- | | `options` | `InputSignal` | Options for the mobile element. | | `status` | `OutputEmitterRef` | Where a sent EcoCash payment stands, while the element waits for approval. | # PaymentElement > Every method the transaction can be paid with. A new `referenceNumber` replaces the element. Every method the transaction can be paid with. A new `referenceNumber` replaces the element. ```ts export declare class PaymentElement extends PesepayElementDirective<"payment"> ``` ## Inputs and outputs [Section titled “Inputs and outputs”](#inputs-and-outputs) | Name | Type | Description | | --------- | -------------------------------------- | -------------------------------------------------------------------------- | | `options` | `InputSignal` | Options for the payment element, with the transaction to pay. Required. | | `status` | `OutputEmitterRef` | Where a sent EcoCash payment stands, while the element waits for approval. | # PesepayElementDirective > What every element component shares: it creates its element in the enclosing group once Pesepay has loaded, mounts it into its own host element, re-emits its events, passes changed `options` to `update()`, and destroys it with the component. What every element component shares: it creates its element in the enclosing group once Pesepay has loaded, mounts it into its own host element, re-emits its events, passes changed `options` to `update()`, and destroys it with the component. ```ts export declare abstract class PesepayElementDirective ``` ## Inputs and outputs [Section titled “Inputs and outputs”](#inputs-and-outputs) | Name | Type | Description | | --------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `blur` | `OutputEmitterRef["blur"]>` | A field lost focus. | | `elementChange` | `OutputEmitterRef["change"]>` | The customer changed a value: `change` in `@pesepay/js`. Typed for the element, so a card’s carries `brand`. Not named `change`: Angular would also deliver the DOM `change` events that bubble out of the card provider’s form. | | `escape` | `OutputEmitterRef["escape"]>` | The customer pressed Escape. | | `focus` | `OutputEmitterRef["focus"]>` | A field gained focus. | | `loadError` | `OutputEmitterRef["loaderror"]>` | The element could not load. `loaderror` in `@pesepay/js`. | | `options` | `Signal` | The element’s options. Required where the element needs one. | | `ready` | `OutputEmitterRef["ready"]>` | The element has rendered. | # ScanElement > The InnBucks or PayGo code the customer scans. The InnBucks or PayGo code the customer scans. ```ts export declare class ScanElement extends PesepayElementDirective<"scan"> ``` ## Inputs and outputs [Section titled “Inputs and outputs”](#inputs-and-outputs) | Name | Type | Description | | --------- | ---------------------------------------------- | ----------------------------- | | `options` | `InputSignal` | Options for the scan element. | # @pesepay/js > API reference for @pesepay/js. Every public export of `@pesepay/js`, generated from its type declarations. [@pesepay/js on npm](https://www.npmjs.com/package/@pesepay/js). ## Functions and components [Section titled “Functions and components”](#functions-and-components) | Name | Description | | --------------------------------------------------------------------- | ------------------------------------------------------------ | | [`isPesepayError`](/embedded-checkout/reference/js/is-pesepay-error/) | Narrows an unknown caught value to a Pesepay error. | | [`loadPesepay`](/embedded-checkout/reference/js/load-pesepay/) | Loads the Pesepay runtime and returns a configured instance. | ## Interfaces [Section titled “Interfaces”](#interfaces) | Name | Description | | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`BaseChangeEvent`](/embedded-checkout/reference/js/base-change-event/) | Sent when the customer changes the input. A field nobody has typed in is `empty`, not invalid, so you need not show “required” before the customer starts. `error` is the one message to show. | | [`BaseElementOptions`](/embedded-checkout/reference/js/base-element-options/) | Options shared by every element. Events are not options: listen with `element.on("change", handler)`. | | [`CardChangeEvent`](/embedded-checkout/reference/js/card-change-event/) | The card element’s `change` event. | | [`CardCheckout`](/embedded-checkout/reference/js/card-checkout/) | What opens the provider’s hosted card form. | | [`CardElement`](/embedded-checkout/reference/js/card-element/) | Card number, expiry and CVC fields for Visa, in a frame on a Pesepay origin. Pay with `confirmCardPayment()`. | | [`CheckoutChangeEvent`](/embedded-checkout/reference/js/checkout-change-event/) | The checkout element’s `change` event: the payment element’s, sent as `"checkout"`. | | [`CheckoutElement`](/embedded-checkout/reference/js/checkout-element/) | The payment element with its own Pay button. It runs every step itself: the O’mari code, the wait for an EcoCash approval or a scanned code, and the result when the customer comes back from 3-D Secure or the card form. Listen for `finished`. It is not passed to `confirmPayment()`. | | [`CheckoutFinishedEvent`](/embedded-checkout/reference/js/checkout-finished-event/) | Sent once, when the checkout element’s payment has ended. Confirm the result on your server before you fulfil the order. | | [`ConfirmCardPaymentData`](/embedded-checkout/reference/js/confirm-card-payment-data/) | A card that needs 3-D Secure always navigates the browser to the customer’s bank. Your page never holds the card, so it cannot do that step itself. | | [`ConfirmHostedCardPaymentData`](/embedded-checkout/reference/js/confirm-hosted-card-payment-data/) | The hosted card form holds the card, the checkout already fixes the method, and the provider takes no customer details or metadata, so this takes only the element. | | [`ConfirmMobilePaymentData`](/embedded-checkout/reference/js/confirm-mobile-payment-data/) | What `confirmMobilePayment()` takes. | | [`ConfirmPaymentElementData`](/embedded-checkout/reference/js/confirm-payment-element-data/) | The payment element pays with whichever method the customer chose, so it takes no options that only some methods can use. | | [`ConfirmPaymentOptionsMap`](/embedded-checkout/reference/js/confirm-payment-options-map/) | The options each element’s payment can use, by element type. | | [`ConfirmScanPaymentData`](/embedded-checkout/reference/js/confirm-scan-payment-data/) | What `confirmScanPayment()` takes. | | [`ContactChangeEvent`](/embedded-checkout/reference/js/contact-change-event/) | The mobile element’s `change` event. | | [`CustomerDetails`](/embedded-checkout/reference/js/customer-details/) | The customer paying, sent with the payment. | | [`ElementEscapeEvent`](/embedded-checkout/reference/js/element-escape-event/) | Sent when the customer presses Escape inside the element. | | [`ElementFocusEvent`](/embedded-checkout/reference/js/element-focus-event/) | Sent when a field in the element gains focus. | | [`ElementLoadErrorEvent`](/embedded-checkout/reference/js/element-load-error-event/) | Sent when the element could not load. Show `error`, or send the customer to `fallbackUrl`. | | [`ElementMap`](/embedded-checkout/reference/js/element-map/) | The element each `ElementType` creates. | | [`ElementOptionsMap`](/embedded-checkout/reference/js/element-options-map/) | The options each element type takes, by `ElementType`. | | [`ElementReadyEvent`](/embedded-checkout/reference/js/element-ready-event/) | Sent once the element has rendered and can take input. | | [`Elements`](/embedded-checkout/reference/js/elements/) | A group of elements that share a theme and fonts. | | [`ElementsOptions`](/embedded-checkout/reference/js/elements-options/) | Options applied to every element in a group. | | [`ElementStatusEvent`](/embedded-checkout/reference/js/element-status-event/) | Sent by the mobile and payment elements as a mobile money payment progresses. | | [`FontSource`](/embedded-checkout/reference/js/font-source/) | A web font for the card fields. | | [`HandleRedirectOptions`](/embedded-checkout/reference/js/handle-redirect-options/) | Options for `handleRedirectResult()`. | | [`HostedCardElement`](/embedded-checkout/reference/js/hosted-card-element/) | The card provider’s own form, for Mastercard and Zimswitch. It renders in your page; the card number and CVV stay in the provider’s iframes. One per page: creating a second throws. | | [`HostedCardElementOptions`](/embedded-checkout/reference/js/hosted-card-element-options/) | Options for `elements.create("hostedCard")`. | | [`LoadOptions`](/embedded-checkout/reference/js/load-options/) | Options for `loadPesepay()`: the config, plus where and how long to load the runtime. | | [`MobileElement`](/embedded-checkout/reference/js/mobile-element/) | A phone number field for EcoCash or O’mari. Pay with `confirmMobilePayment()`. | | [`MobileElementOptions`](/embedded-checkout/reference/js/mobile-element-options/) | Options for `elements.create("mobile")`. | | [`PayableAmount`](/embedded-checkout/reference/js/payable-amount/) | What the customer pays with the selected method. | | [`PaymentChangeEvent`](/embedded-checkout/reference/js/payment-change-event/) | `empty` until the customer picks a method. `complete` once the method is priced and its fields are filled in. | | [`PaymentElement`](/embedded-checkout/reference/js/payment-element/) | Every method the transaction can be paid with, grouped as mobile money, card and scan to pay. The chosen method shows its fields and the total with its fee. Pay with `confirmPayment()`. It renders in your page; card numbers stay in Pesepay’s or the card provider’s frames. | | [`PaymentElementOptions`](/embedded-checkout/reference/js/payment-element-options/) | Options for `elements.create("payment")`. | | [`PaymentMethod`](/embedded-checkout/reference/js/payment-method/) | A payment method Pesepay offers for a transaction’s currency. | | [`Pesepay`](/embedded-checkout/reference/js/pesepay/) | What `loadPesepay()` resolves to. | | [`PesepayConfig`](/embedded-checkout/reference/js/pesepay-config/) | Options for `loadPesepay()`. | | [`PesepayElementBase`](/embedded-checkout/reference/js/pesepay-element-base/) | What every element can do: mount, update, focus, clear and send events. `create()` does not mount, so you can set an element up before its container exists. Each element’s page lists the events it sends. | | [`PesepayError`](/embedded-checkout/reference/js/pesepay-error/) | The shape of `result.error`. An interface, not a class — the class ships in the CDN runtime. Narrow on `code`, not `instanceof`. | | [`PesepayTheme`](/embedded-checkout/reference/js/pesepay-theme/) | How elements look. Set it in `loadPesepay()`, in `elements()` or on one element: each layer overrides the one before. | | [`RedirectingPaymentData`](/embedded-checkout/reference/js/redirecting-payment-data/) | Options for a confirm that may need the customer to leave the page. | | [`ScanCode`](/embedded-checkout/reference/js/scan-code/) | What the customer pays with in the provider’s app. | | [`ScanElement`](/embedded-checkout/reference/js/scan-element/) | Shows the QR code and short code the customer pays with in the InnBucks or PayGo app. It has no input: it is empty until `confirmScanPayment()` returns the code. | | [`ScanElementOptions`](/embedded-checkout/reference/js/scan-element-options/) | Options for `elements.create("scan")`. | | [`Transaction`](/embedded-checkout/reference/js/transaction/) | A Pesepay transaction, as the SDK reads it. | | [`TransactionAmount`](/embedded-checkout/reference/js/transaction-amount/) | A transaction’s amount. | | [`WaitForTransactionOptions`](/embedded-checkout/reference/js/wait-for-transaction-options/) | Options for `waitForTransaction()`. | ## Types [Section titled “Types”](#types) | Name | Description | | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`AnyPesepayElement`](/embedded-checkout/reference/js/any-pesepay-element/) | Any element `elements.create()` can return. | | [`CardBrand`](/embedded-checkout/reference/js/card-brand/) | Card brands the SDK can detect. `unknown` (unmatched BIN, or a partial number) is not an error. Detecting a brand is not being able to charge it — the card element pays Visa only. Mastercard raises `use_mastercard_option` and the rest raise `card_brand_not_supported`. | | [`CardCheckoutBrand`](/embedded-checkout/reference/js/card-checkout-brand/) | The hosted form’s card brand: Mastercard, or Zimswitch’s domestic cards. | | [`CardElementOptions`](/embedded-checkout/reference/js/card-element-options/) | Options for `elements.create("card")`: the options every element takes. | | [`CardField`](/embedded-checkout/reference/js/card-field/) | The fields inside a card element, used to scope focus, blur and errors. | | [`CheckoutElementOptions`](/embedded-checkout/reference/js/checkout-element-options/) | Options for `elements.create("checkout")`: the same as the payment element’s. | | [`CheckoutOutcome`](/embedded-checkout/reference/js/checkout-outcome/) | How a checkout element’s payment ended. `unknown` is also sent when no answer came in time: the customer may still pay, so don’t let them pay again until your server has the result. | | [`ConfirmableElement`](/embedded-checkout/reference/js/confirmable-element/) | Any element `confirmPayment()` takes: every element but the checkout element, which pays with its own button. | | [`ConfirmPaymentData`](/embedded-checkout/reference/js/confirm-payment-data/) | What `confirmPayment()` takes. An element typed as a union, such as `CardElement \| MobileElement`, takes only the options every member can use. An option the element’s payment cannot use is refused rather than dropped: `redirect` with a card or scan element, and anything but `signal` with a hostedCard or payment element. | | [`ConfirmResult`](/embedded-checkout/reference/js/confirm-result/) | The transaction, or an error: never both. After `if (result.error) return;`, TypeScript knows `result.transaction` is set. | | [`ElementBlurEvent`](/embedded-checkout/reference/js/element-blur-event/) | Sent when a field in the element loses focus. | | [`ElementPaymentStatus`](/embedded-checkout/reference/js/element-payment-status/) | Where a sent mobile money payment stands. After `processing`, the element shows “Check your phone” and waits for the customer’s approval itself. | | [`ElementType`](/embedded-checkout/reference/js/element-type/) | The kind of element `elements.create()` makes. | | [`LogLevel`](/embedded-checkout/reference/js/log-level/) | How much the SDK writes to the browser console. `"silent"` writes nothing. | | [`MobileProvider`](/embedded-checkout/reference/js/mobile-provider/) | EcoCash approves on the customer’s phone. O’mari sends an SMS code that the customer types into the element, so its payment takes two confirms. | | [`MobileStep`](/embedded-checkout/reference/js/mobile-step/) | Which input a mobile element shows: the phone number, then O’mari’s SMS code. | | [`NextAction`](/embedded-checkout/reference/js/next-action/) | What the customer must do before the payment can finish. | | [`PaymentMethodsResult`](/embedded-checkout/reference/js/payment-methods-result/) | What `listPaymentMethods()` returns: the methods and the amount, or an error. | | [`PesepayErrorCode`](/embedded-checkout/reference/js/pesepay-error-code/) | Every code a `PesepayError` can carry. Branch on these, not on `message`. | | [`PesepayErrorParam`](/embedded-checkout/reference/js/pesepay-error-param/) | Which field a `validation_error` or `card_error` refers to, when one applies. | | [`PesepayErrorType`](/embedded-checkout/reference/js/pesepay-error-type/) | Broad category. Determines how a merchant should react, not what went wrong. | | [`ScanProvider`](/embedded-checkout/reference/js/scan-provider/) | Pay-by-code apps. The customer scans a QR code with the provider’s app, or types its short code there. InnBucks pays in USD and PayGo in ZiG (Zimbabwe Gold). | | [`SelectPaymentMethodResult`](/embedded-checkout/reference/js/select-payment-method-result/) | What `selectPaymentMethod()` returns: the priced amount, or an error. | | [`ThemeLabels`](/embedded-checkout/reference/js/theme-labels/) | Where field labels go. `"hidden"` still names each field to screen readers. | | [`ThemePreset`](/embedded-checkout/reference/js/theme-preset/) | A ready-made set of colours, spacing and states. `"night"` is dark, `"flat"` is borderless on a tinted fill. Labels and fonts stay yours. | | [`TransactionOutcome`](/embedded-checkout/reference/js/transaction-outcome/) | What a transaction’s status means for your checkout. Derived from `TransactionStatus` by one table, so you do not have to keep your own. | | [`TransactionStatus`](/embedded-checkout/reference/js/transaction-status/) | Pesepay’s own status for a transaction, exactly as the API reports it. | ## Constants [Section titled “Constants”](#constants) | Name | Description | | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | [`PESEPAY_ERROR_CODES`](/embedded-checkout/reference/js/pesepay-error-codes/) | Every error code the SDK can return, as an array you can loop over, for example to check that your own messages cover them all. | # AnyPesepayElement > Any element `elements.create()` can return. Any element `elements.create()` can return. ```ts export type AnyPesepayElement = ConfirmableElement | CheckoutElement; ``` # BaseChangeEvent > Sent when the customer changes the input. A field nobody has typed in is `empty`, not invalid, so you need not show "required" before the customer starts. `error` is the one message to show. Sent when the customer changes the input. A field nobody has typed in is `empty`, not invalid, so you need not show “required” before the customer starts. `error` is the one message to show. ```ts export interface BaseChangeEvent ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ------------- | ---------------------------------------------------------------- | ------------------------------------------------- | | `complete` | `boolean` | True once every field is filled in and valid. | | `elementType` | [`ElementType`](/embedded-checkout/reference/js/element-type/) | The element that sent the event. | | `empty` | `boolean` | True while nothing has been entered. | | `error?` | [`PesepayError`](/embedded-checkout/reference/js/pesepay-error/) | The one message to show, if the input is invalid. | # BaseElementOptions > Options shared by every element. Events are not options: listen with `element.on("change", handler)`. Options shared by every element. Events are not options: listen with `element.on("change", handler)`. ```ts export interface BaseElementOptions ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ------------------ | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | `ariaDescribedBy?` | `string` | Id of an element in your page that describes this one, such as your own error message. | | `ariaLabel?` | `string` | Accessible name for the element. | | `className?` | `string` | A class added to the element’s container, beside `pesepay-element`. | | `disabled?` | `boolean` | Disables input. Toggle it with `update({ disabled })`. | | `placeholder?` | `string` | Placeholder text: the card number’s, or the scan element’s before it has a code. | | `theme?` | [`PesepayTheme`](/embedded-checkout/reference/js/pesepay-theme/) | Theme for this element, over the group’s and the config’s. | # CardBrand > Card brands the SDK can detect. `unknown` (unmatched BIN, or a partial number) is not an error. Detecting a brand is not being able to charge it — the card element pays Visa only. Mastercard raises `use_mastercard_option` and the rest raise `card_brand_not_supported`. Card brands the SDK can detect. `unknown` (unmatched BIN, or a partial number) is not an error. Detecting a brand is not being able to charge it — the card element pays Visa only. Mastercard raises `use_mastercard_option` and the rest raise `card_brand_not_supported`. ```ts export type CardBrand = "visa" | "mastercard" | "amex" | "discover" | "diners" | "jcb" | "unionpay" | "maestro" | "unknown"; ``` # CardChangeEvent > The card element's `change` event. The card element’s `change` event. ```ts export interface CardChangeEvent extends BaseChangeEvent ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- | | `brand` | [`CardBrand`](/embedded-checkout/reference/js/card-brand/) | The brand detected from the number so far. | | `country?` | `string` | The issuing country, when the card number identifies one. Not set yet. | | `elementType` | `"card"` | Always `"card"`. | Also has everything [`BaseChangeEvent`](/embedded-checkout/reference/js/base-change-event/) has. # CardCheckout > What opens the provider's hosted card form. What opens the provider’s hosted card form. ```ts export interface CardCheckout ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ----------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | `brand` | [`CardCheckoutBrand`](/embedded-checkout/reference/js/card-checkout-brand/) | The card brand the form takes. | | `checkoutId` | `string` | Identifies the checkout to the provider’s form. | | `referenceNumber` | `string` | The transaction this checkout pays. | | `returnUrl?` | `string` | The transaction’s `returnUrl`, where the form brings the customer back to. | # CardCheckoutBrand > The hosted form's card brand: Mastercard, or Zimswitch's domestic cards. The hosted form’s card brand: Mastercard, or Zimswitch’s domestic cards. ```ts export type CardCheckoutBrand = "MASTER" | "PRIVATE_LABEL"; ``` # CardElement > Card number, expiry and CVC fields for Visa, in a frame on a Pesepay origin. Pay with `confirmCardPayment()`. Card number, expiry and CVC fields for Visa, in a frame on a Pesepay origin. Pay with [`confirmCardPayment()`](/embedded-checkout/reference/js/pesepay/#confirmcardpayment). ```ts export interface CardElement extends PesepayElementBase ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ------------- | -------- | ---------------- | | `elementType` | `"card"` | Always `"card"`. | ## Events [Section titled “Events”](#events) Listen with `on()`, `once()` or `off()`, by event name. Each handler receives the event’s payload. | Event | Payload | Description | | ----------- | ------------------------------------------------------------------------------------ | ------------------------------------------- | | `change` | [`CardChangeEvent`](/embedded-checkout/reference/js/card-change-event/) | The input changed, with the detected brand. | | `blur` | [`ElementBlurEvent`](/embedded-checkout/reference/js/element-blur-event/) | A field lost focus. | | `escape` | [`ElementEscapeEvent`](/embedded-checkout/reference/js/element-escape-event/) | The customer pressed Escape. | | `focus` | [`ElementFocusEvent`](/embedded-checkout/reference/js/element-focus-event/) | A field gained focus. | | `loaderror` | [`ElementLoadErrorEvent`](/embedded-checkout/reference/js/element-load-error-event/) | The element could not load. | | `ready` | [`ElementReadyEvent`](/embedded-checkout/reference/js/element-ready-event/) | The element has rendered. | Also has everything [`PesepayElementBase`](/embedded-checkout/reference/js/pesepay-element-base/) has. # CardElementOptions > Options for `elements.create("card")`: the options every element takes. Options for `elements.create("card")`: the options every element takes. ```ts export type CardElementOptions = BaseElementOptions; ``` # CardField > The fields inside a card element, used to scope focus, blur and errors. The fields inside a card element, used to scope focus, blur and errors. ```ts export type CardField = "number" | "expiry" | "cvc"; ``` # CheckoutChangeEvent > The checkout element's `change` event: the payment element's, sent as `"checkout"`. The checkout element’s `change` event: the payment element’s, sent as `"checkout"`. ```ts export interface CheckoutChangeEvent extends Omit ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ------------- | ------------ | -------------------- | | `elementType` | `"checkout"` | Always `"checkout"`. | # CheckoutElement > The payment element with its own Pay button. It runs every step itself: the O'mari code, the wait for an EcoCash approval or a scanned code, and the result when the customer comes back from 3-D Secure or the card form. Listen for `finished`. It is not passed to `confirmPayment()`. The payment element with its own Pay button. It runs every step itself: the O’mari code, the wait for an EcoCash approval or a scanned code, and the result when the customer comes back from 3-D Secure or the card form. Listen for `finished`. It is not passed to [`confirmPayment()`](/embedded-checkout/reference/js/pesepay/#confirmpayment). ```ts export interface CheckoutElement extends PesepayElementBase ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ------------- | ------------ | -------------------- | | `elementType` | `"checkout"` | Always `"checkout"`. | ## Events [Section titled “Events”](#events) Listen with `on()`, `once()` or `off()`, by event name. Each handler receives the event’s payload. | Event | Payload | Description | | ----------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------- | | `change` | [`CheckoutChangeEvent`](/embedded-checkout/reference/js/checkout-change-event/) | The chosen method or its fields changed. | | `blur` | [`ElementBlurEvent`](/embedded-checkout/reference/js/element-blur-event/) | A field lost focus. | | `escape` | [`ElementEscapeEvent`](/embedded-checkout/reference/js/element-escape-event/) | The customer pressed Escape. | | `finished` | [`CheckoutFinishedEvent`](/embedded-checkout/reference/js/checkout-finished-event/) | Sent only by the checkout element, once its payment has ended. | | `focus` | [`ElementFocusEvent`](/embedded-checkout/reference/js/element-focus-event/) | A field gained focus. | | `loaderror` | [`ElementLoadErrorEvent`](/embedded-checkout/reference/js/element-load-error-event/) | The element could not load. | | `ready` | [`ElementReadyEvent`](/embedded-checkout/reference/js/element-ready-event/) | The element has rendered. | Also has everything [`PesepayElementBase`](/embedded-checkout/reference/js/pesepay-element-base/) has. # CheckoutElementOptions > Options for `elements.create("checkout")`: the same as the payment element's. Options for `elements.create("checkout")`: the same as the payment element’s. ```ts export type CheckoutElementOptions = PaymentElementOptions; ``` # CheckoutFinishedEvent > Sent once, when the checkout element's payment has ended. Confirm the result on your server before you fulfil the order. Sent once, when the checkout element’s payment has ended. Confirm the result on your server before you fulfil the order. ```ts export interface CheckoutFinishedEvent ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ------------- | ---------------------------------------------------------------------- | ----------------------------- | | `elementType` | `"checkout"` | Always `"checkout"`. | | `outcome` | [`CheckoutOutcome`](/embedded-checkout/reference/js/checkout-outcome/) | How the payment ended. | | `transaction` | [`Transaction`](/embedded-checkout/reference/js/transaction/) | The transaction as last read. | # CheckoutOutcome > How a checkout element's payment ended. `unknown` is also sent when no answer came in time: the customer may still pay, so don't let them pay again until your server has the result. How a checkout element’s payment ended. `unknown` is also sent when no answer came in time: the customer may still pay, so don’t let them pay again until your server has the result. ```ts export type CheckoutOutcome = Exclude; ``` # ConfirmCardPaymentData > A card that needs 3-D Secure always navigates the browser to the customer's bank. Your page never holds the card, so it cannot do that step itself. A card that needs 3-D Secure always navigates the browser to the customer’s bank. Your page never holds the card, so it cannot do that step itself. ```ts export interface ConfirmCardPaymentData extends ConfirmDataBase ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | -------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `element` | [`CardElement`](/embedded-checkout/reference/js/card-element/) | The card element holding the card. | | `customer?` | [`CustomerDetails`](/embedded-checkout/reference/js/customer-details/) | The customer paying. | | `metadata?` | `Record` | Sent with the payment and echoed back on `transaction.metadata`. Stored against the transaction, so not a place for anything sensitive. | | `paymentMethodCode?` | `string` | Override the payment method code, such as `PZW211` for EcoCash USD. Leave it unset: the SDK picks it from the card’s brand, or from the element’s provider and the transaction’s currency. | | `signal?` | `AbortSignal` | Abandons the confirm. Resolves with an `outcome_unknown` error rather than throwing: a payment already sent cannot be recalled. | # ConfirmHostedCardPaymentData > The hosted card form holds the card, the checkout already fixes the method, and the provider takes no customer details or metadata, so this takes only the element. The hosted card form holds the card, the checkout already fixes the method, and the provider takes no customer details or metadata, so this takes only the element. ```ts export interface ConfirmHostedCardPaymentData ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | --------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `element` | [`HostedCardElement`](/embedded-checkout/reference/js/hosted-card-element/) | From `elements.create("hostedCard")`, for this transaction’s checkout. | | `signal?` | `AbortSignal` | Abandons the confirm before the form is sent. Once sent, the browser leaves for the customer’s bank. | # ConfirmMobilePaymentData > What `confirmMobilePayment()` takes. What [`confirmMobilePayment()`](/embedded-checkout/reference/js/pesepay/#confirmmobilepayment) takes. ```ts export interface ConfirmMobilePaymentData extends RedirectingPaymentData ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | --------- | ------------------------------------------------------------------ | -------------------------------------------- | | `element` | [`MobileElement`](/embedded-checkout/reference/js/mobile-element/) | The mobile element holding the phone number. | Also has everything [`RedirectingPaymentData`](/embedded-checkout/reference/js/redirecting-payment-data/) has. # ConfirmPaymentData > What `confirmPayment()` takes. An element typed as a union, such as `CardElement \| MobileElement`, takes only the options every member can use. An option the element's payment cannot use is refused rather than dropped: `redirect` with a card or scan element, and anything but `signal` with a hostedCard or payment element. What [`confirmPayment()`](/embedded-checkout/reference/js/pesepay/#confirmpayment) takes. An element typed as a union, such as `CardElement | MobileElement`, takes only the options every member can use. An option the element’s payment cannot use is refused rather than dropped: `redirect` with a card or scan element, and anything but `signal` with a hostedCard or payment element. ```ts export type ConfirmPaymentData = { element: E; } & ((E extends ConfirmableElement ? (options: ConfirmPaymentOptionsMap[E["elementType"]]) => void : never) extends (options: infer O) => void ? O : never); ``` # ConfirmPaymentElementData > The payment element pays with whichever method the customer chose, so it takes no options that only some methods can use. The payment element pays with whichever method the customer chose, so it takes no options that only some methods can use. ```ts export interface ConfirmPaymentElementData ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | --------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `element` | [`PaymentElement`](/embedded-checkout/reference/js/payment-element/) | From `elements.create("payment")`, for this transaction. | | `signal?` | `AbortSignal` | Abandons the confirm. Resolves with an `outcome_unknown` error rather than throwing: a payment already sent cannot be recalled. | # ConfirmPaymentOptionsMap > The options each element's payment can use, by element type. The options each element’s payment can use, by element type. ```ts export interface ConfirmPaymentOptionsMap ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | | `card` | `Omit & { redirect?: never; }` | Options for a card element. | | `hostedCard` | `Omit & { customer?: never; metadata?: never; paymentMethodCode?: never; redirect?: never; }` | Options for a hostedCard element. | | `mobile` | `Omit` | Options for a mobile element. | | `payment` | `Omit & { customer?: never; metadata?: never; paymentMethodCode?: never; redirect?: never; }` | Options for a payment element. | | `scan` | `Omit & { redirect?: never; }` | Options for a scan element. | # ConfirmResult > The transaction, or an error: never both. After `if (result.error) return;`, TypeScript knows `result.transaction` is set. The transaction, or an error: never both. After `if (result.error) return;`, TypeScript knows `result.transaction` is set. ```ts export type ConfirmResult = { transaction: Transaction; error?: never; } | { transaction?: never; error: PesepayError; }; ``` # ConfirmScanPaymentData > What `confirmScanPayment()` takes. What [`confirmScanPayment()`](/embedded-checkout/reference/js/pesepay/#confirmscanpayment) takes. ```ts export interface ConfirmScanPaymentData extends ConfirmDataBase ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | -------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `element` | [`ScanElement`](/embedded-checkout/reference/js/scan-element/) | The scan element that shows the code. | | `customer?` | [`CustomerDetails`](/embedded-checkout/reference/js/customer-details/) | The customer paying. | | `metadata?` | `Record` | Sent with the payment and echoed back on `transaction.metadata`. Stored against the transaction, so not a place for anything sensitive. | | `paymentMethodCode?` | `string` | Override the payment method code, such as `PZW211` for EcoCash USD. Leave it unset: the SDK picks it from the card’s brand, or from the element’s provider and the transaction’s currency. | | `signal?` | `AbortSignal` | Abandons the confirm. Resolves with an `outcome_unknown` error rather than throwing: a payment already sent cannot be recalled. | # ConfirmableElement > Any element `confirmPayment()` takes: every element but the checkout element, which pays with its own button. Any element [`confirmPayment()`](/embedded-checkout/reference/js/pesepay/#confirmpayment) takes: every element but the checkout element, which pays with its own button. ```ts export type ConfirmableElement = CardElement | MobileElement | ScanElement | HostedCardElement | PaymentElement; ``` # ContactChangeEvent > The mobile element's `change` event. The mobile element’s `change` event. ```ts export interface ContactChangeEvent extends BaseChangeEvent ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ------------- | ------------------------------------------------------------ | ------------------------------------------------------------------ | | `elementType` | `"mobile"` | Always `"mobile"`. | | `step` | [`MobileStep`](/embedded-checkout/reference/js/mobile-step/) | `otp` once O’mari has sent the code; relabel your pay button then. | Also has everything [`BaseChangeEvent`](/embedded-checkout/reference/js/base-change-event/) has. # CustomerDetails > The customer paying, sent with the payment. The customer paying, sent with the payment. ```ts export interface CustomerDetails ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | -------------- | -------- | ----------------------------- | | `email?` | `string` | The customer’s email address. | | `name?` | `string` | The customer’s full name. | | `phoneNumber?` | `string` | The customer’s phone number. | # ElementBlurEvent > Sent when a field in the element loses focus. Sent when a field in the element loses focus. ```ts export type ElementBlurEvent = ElementFocusEvent; ``` # ElementEscapeEvent > Sent when the customer presses Escape inside the element. Sent when the customer presses Escape inside the element. ```ts export interface ElementEscapeEvent ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ------------- | -------------------------------------------------------------- | -------------------------------- | | `elementType` | [`ElementType`](/embedded-checkout/reference/js/element-type/) | The element that sent the event. | # ElementFocusEvent > Sent when a field in the element gains focus. Sent when a field in the element gains focus. ```ts export interface ElementFocusEvent ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------ | | `elementType` | [`ElementType`](/embedded-checkout/reference/js/element-type/) | The element that sent the event. | | `field?` | `CardField \| "phone" \| "otp"` | The field that gained or lost focus, when the element has more than one. | # ElementLoadErrorEvent > Sent when the element could not load. Show `error`, or send the customer to `fallbackUrl`. Sent when the element could not load. Show `error`, or send the customer to `fallbackUrl`. ```ts export interface ElementLoadErrorEvent ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | -------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `elementType` | [`ElementType`](/embedded-checkout/reference/js/element-type/) | The element that failed. | | `error` | [`PesepayError`](/embedded-checkout/reference/js/pesepay-error/) | Why it failed. | | `fallbackUrl?` | `string` | Sent only by the payment and checkout elements: the Hosted checkout page for the same transaction. Send the customer there so they can still pay. | # ElementMap > The element each `ElementType` creates. The element each [`ElementType`](/embedded-checkout/reference/js/element-type/) creates. ```ts export interface ElementMap ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ------------ | --------------------------------------------------------------------------- | ----------------------- | | `card` | [`CardElement`](/embedded-checkout/reference/js/card-element/) | The card element. | | `checkout` | [`CheckoutElement`](/embedded-checkout/reference/js/checkout-element/) | The checkout element. | | `hostedCard` | [`HostedCardElement`](/embedded-checkout/reference/js/hosted-card-element/) | The hostedCard element. | | `mobile` | [`MobileElement`](/embedded-checkout/reference/js/mobile-element/) | The mobile element. | | `payment` | [`PaymentElement`](/embedded-checkout/reference/js/payment-element/) | The payment element. | | `scan` | [`ScanElement`](/embedded-checkout/reference/js/scan-element/) | The scan element. | # ElementOptionsMap > The options each element type takes, by `ElementType`. The options each element type takes, by [`ElementType`](/embedded-checkout/reference/js/element-type/). ```ts export interface ElementOptionsMap ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ------------ | ------------------------------------------------------------------------------------------ | ----------------------------------- | | `card` | [`CardElementOptions`](/embedded-checkout/reference/js/card-element-options/) | Options for the card element. | | `checkout` | [`CheckoutElementOptions`](/embedded-checkout/reference/js/checkout-element-options/) | Options for the checkout element. | | `hostedCard` | [`HostedCardElementOptions`](/embedded-checkout/reference/js/hosted-card-element-options/) | Options for the hostedCard element. | | `mobile` | [`MobileElementOptions`](/embedded-checkout/reference/js/mobile-element-options/) | Options for the mobile element. | | `payment` | [`PaymentElementOptions`](/embedded-checkout/reference/js/payment-element-options/) | Options for the payment element. | | `scan` | [`ScanElementOptions`](/embedded-checkout/reference/js/scan-element-options/) | Options for the scan element. | # ElementPaymentStatus > Where a sent mobile money payment stands. After `processing`, the element shows "Check your phone" and waits for the customer's approval itself. Where a sent mobile money payment stands. After `processing`, the element shows “Check your phone” and waits for the customer’s approval itself. ```ts export type ElementPaymentStatus = "awaiting_approval" | "succeeded" | "failed" | "reversed" | "unknown"; ``` # ElementReadyEvent > Sent once the element has rendered and can take input. Sent once the element has rendered and can take input. ```ts export interface ElementReadyEvent ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ------------- | -------------------------------------------------------------- | -------------------------------- | | `elementType` | [`ElementType`](/embedded-checkout/reference/js/element-type/) | The element that sent the event. | # ElementStatusEvent > Sent by the mobile and payment elements as a mobile money payment progresses. Sent by the mobile and payment elements as a mobile money payment progresses. ```ts export interface ElementStatusEvent ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | -------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `approveBy?` | `number` | With `awaiting_approval`: when the prompt expires, in epoch milliseconds. | | `elementType` | `"mobile" \| "payment"` | The element that sent the event. | | `status` | [`ElementPaymentStatus`](/embedded-checkout/reference/js/element-payment-status/) | `unknown` is also sent when no answer came in time: the customer may still approve, so don’t take the money again. Your webhook has the result. | | `transaction?` | [`Transaction`](/embedded-checkout/reference/js/transaction/) | The latest transaction seen; absent only when none could be read. | # ElementType > The kind of element `elements.create()` makes. The kind of element `elements.create()` makes. ```ts export type ElementType = "card" | "mobile" | "scan" | "hostedCard" | "payment" | "checkout"; ``` # Elements > A group of elements that share a theme and fonts. A group of elements that share a theme and fonts. One group holds at most one element of each type at a time: once it is destroyed, `create()` can make that type again. Two independent groups on one page is the supported way to render two card fields. ```ts export interface Elements ``` ## Methods [Section titled “Methods”](#methods) ### `create()` [Section titled “create()”](#create) ```ts create(type: T, options?: ElementOptionsMap[T]): ElementMap[T]; ``` Creates an element of this type. Throws if the group already has one: use `getElement()` to reuse it. | Parameter | Type | | ---------- | ---------------------- | | `type` | `T` | | `options?` | `ElementOptionsMap[T]` | ### `destroy()` [Section titled “destroy()”](#destroy) ```ts destroy(): void; ``` Destroys every element in the group. ### `getElement()` [Section titled “getElement()”](#getelement) ```ts getElement(type: T): ElementMap[T] | null; ``` The group’s element of this type, or `null` if it has none. | Parameter | Type | | --------- | ---- | | `type` | `T` | ### `update()` [Section titled “update()”](#update) ```ts update(options: ElementsOptions): void; ``` Re-applies group-level appearance to every element in the group. | Parameter | Type | | --------- | ---------------------------------------------------------------------- | | `options` | [`ElementsOptions`](/embedded-checkout/reference/js/elements-options/) | # ElementsOptions > Options applied to every element in a group. Options applied to every element in a group. ```ts export interface ElementsOptions ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | --------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `fonts?` | `FontSource[]` | Web fonts loaded inside the card fields, at most 8. Name the family in `theme.fonts.family`. The mobile and scan elements render in your page and use the fonts it already loads. | | `locale?` | `string` | BCP 47 tag, or “auto” to follow the browser. Reserved: `en` is the only catalogue that exists today. | | `theme?` | [`PesepayTheme`](/embedded-checkout/reference/js/pesepay-theme/) | Theme for every element in the group, over the config’s. | # FontSource > A web font for the card fields. A web font for the card fields. ```ts export interface FontSource ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | -------- | -------- | ------------------------------------------------------------------------------------------------------- | | `cssSrc` | `string` | A Google Fonts stylesheet URL, `https://fonts.googleapis.com/css2?family=…`. No other host is accepted. | # HandleRedirectOptions > Options for `handleRedirectResult()`. Options for [`handleRedirectResult()`](/embedded-checkout/reference/js/pesepay/#handleredirectresult). ```ts export interface HandleRedirectOptions extends WaitForTransactionOptions ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | --------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `maxRetries?` | `number` | Polls before giving up. Default: no limit, only `timeoutMs`. | | `poll?` | `boolean` | Keep checking until the payment has finished. Default true: the customer can be back before the payment has finished, so an unfinished status on arrival means “wait”, not “failed”. | | `pollInterval?` | `number` | Milliseconds between polls, replacing the default schedule (2, 3, 5 and 8 seconds, then every 10). Never less than 1000. | Also has everything [`WaitForTransactionOptions`](/embedded-checkout/reference/js/wait-for-transaction-options/) has. # HostedCardElement > The card provider's own form, for Mastercard and Zimswitch. It renders in your page; the card number and CVV stay in the provider's iframes. One per page: creating a second throws. The card provider’s own form, for Mastercard and Zimswitch. It renders in your page; the card number and CVV stay in the provider’s iframes. One per page: creating a second throws. ```ts export interface HostedCardElement extends PesepayElementBase ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ------------- | -------------- | ---------------------- | | `elementType` | `"hostedCard"` | Always `"hostedCard"`. | ## Events [Section titled “Events”](#events) Listen with `on()`, `once()` or `off()`, by event name. Each handler receives the event’s payload. | Event | Payload | Description | | ----------- | ------------------------------------------------------------------------------------ | ---------------------------- | | `blur` | [`ElementBlurEvent`](/embedded-checkout/reference/js/element-blur-event/) | A field lost focus. | | `change` | [`BaseChangeEvent`](/embedded-checkout/reference/js/base-change-event/) | The input changed. | | `escape` | [`ElementEscapeEvent`](/embedded-checkout/reference/js/element-escape-event/) | The customer pressed Escape. | | `focus` | [`ElementFocusEvent`](/embedded-checkout/reference/js/element-focus-event/) | A field gained focus. | | `loaderror` | [`ElementLoadErrorEvent`](/embedded-checkout/reference/js/element-load-error-event/) | The element could not load. | | `ready` | [`ElementReadyEvent`](/embedded-checkout/reference/js/element-ready-event/) | The element has rendered. | Also has everything [`PesepayElementBase`](/embedded-checkout/reference/js/pesepay-element-base/) has. # HostedCardElementOptions > Options for `elements.create("hostedCard")`. Options for `elements.create("hostedCard")`. ```ts export interface HostedCardElementOptions extends BaseElementOptions ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | -------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `cardCheckout` | [`CardCheckout`](/embedded-checkout/reference/js/card-checkout/) | From [`startCardCheckout()`](/embedded-checkout/reference/js/pesepay/#startcardcheckout). Keep it for a reload: each call makes a new checkout. | | `returnUrl?` | `string` | Where the form brings the customer back to, as an absolute http(s) URL. Defaults to `cardCheckout.returnUrl`, then this page. `referenceNumber` is added to it, so [`handleRedirectResult()`](/embedded-checkout/reference/js/pesepay/#handleredirectresult) can finish the payment there. | Also has everything [`BaseElementOptions`](/embedded-checkout/reference/js/base-element-options/) has. # isPesepayError > Narrows an unknown caught value to a Pesepay error. Narrows an unknown caught value to a Pesepay error. ```ts export declare function isPesepayError(value: unknown): value is PesepayError; ``` | Parameter | Type | | --------- | --------- | | `value` | `unknown` | # LoadOptions > Options for `loadPesepay()`: the config, plus where and how long to load the runtime. Options for [`loadPesepay()`](/embedded-checkout/reference/js/load-pesepay/): the config, plus where and how long to load the runtime. ```ts export interface LoadOptions extends Partial ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `scriptOrigin?` | `string` | Override the origin the runtime is loaded from. Intended for local development and self-hosting; changing it means you no longer receive patches from the Pesepay CDN. | | `timeout?` | `number` | Milliseconds to wait for the runtime script before rejecting. | # loadPesepay > Loads the Pesepay runtime and returns a configured instance. Loads the Pesepay runtime and returns a configured instance. Resolves to `null` when there is no DOM, so it is safe to call during server-side rendering (Next.js App Router, Nuxt, SvelteKit). Guard with `if (!pesepay) return;` on the client rather than branching on `window`. Concurrent calls share one script tag and one promise. Two calls with different options still produce two independent instances — nothing about a [`Pesepay`](/embedded-checkout/reference/js/pesepay/) instance is global. ```ts export declare function loadPesepay(options?: LoadOptions): Promise; ``` | Parameter | Type | | ---------- | -------------------------------------------------------------- | | `options?` | [`LoadOptions`](/embedded-checkout/reference/js/load-options/) | # LogLevel > How much the SDK writes to the browser console. `"silent"` writes nothing. How much the SDK writes to the browser console. `"silent"` writes nothing. ```ts export type LogLevel = "debug" | "info" | "warn" | "error" | "silent"; ``` # MobileElement > A phone number field for EcoCash or O'mari. Pay with `confirmMobilePayment()`. A phone number field for EcoCash or O’mari. Pay with [`confirmMobilePayment()`](/embedded-checkout/reference/js/pesepay/#confirmmobilepayment). ```ts export interface MobileElement extends PesepayElementBase ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ------------- | ---------- | ------------------ | | `elementType` | `"mobile"` | Always `"mobile"`. | ## Events [Section titled “Events”](#events) Listen with `on()`, `once()` or `off()`, by event name. Each handler receives the event’s payload. | Event | Payload | Description | | ----------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | | `change` | [`ContactChangeEvent`](/embedded-checkout/reference/js/contact-change-event/) | The input changed, with the current step. | | `blur` | [`ElementBlurEvent`](/embedded-checkout/reference/js/element-blur-event/) | A field lost focus. | | `escape` | [`ElementEscapeEvent`](/embedded-checkout/reference/js/element-escape-event/) | The customer pressed Escape. | | `focus` | [`ElementFocusEvent`](/embedded-checkout/reference/js/element-focus-event/) | A field gained focus. | | `loaderror` | [`ElementLoadErrorEvent`](/embedded-checkout/reference/js/element-load-error-event/) | The element could not load. | | `ready` | [`ElementReadyEvent`](/embedded-checkout/reference/js/element-ready-event/) | The element has rendered. | | `status` | [`ElementStatusEvent`](/embedded-checkout/reference/js/element-status-event/) | Sent only by the mobile and payment elements, as a mobile money payment progresses. | Also has everything [`PesepayElementBase`](/embedded-checkout/reference/js/pesepay-element-base/) has. # MobileElementOptions > Options for `elements.create("mobile")`. Options for `elements.create("mobile")`. ```ts export interface MobileElementOptions extends BaseElementOptions ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `phonePlaceholder?` | `string` | Placeholder for the phone number field. | | `provider?` | [`MobileProvider`](/embedded-checkout/reference/js/mobile-provider/) | The mobile money provider. Defaults to `"EcoCash"`. | | `resumeOtpFor?` | `string` | O’mari only: starts on the code step for this reference, for a page that was reloaded after the SMS went out. Pass it only when you know the SMS was sent and no code has been submitted: the transaction can’t get another. | Also has everything [`BaseElementOptions`](/embedded-checkout/reference/js/base-element-options/) has. # MobileProvider > EcoCash approves on the customer's phone. O'mari sends an SMS code that the customer types into the element, so its payment takes two confirms. EcoCash approves on the customer’s phone. O’mari sends an SMS code that the customer types into the element, so its payment takes two confirms. ```ts export type MobileProvider = "EcoCash" | "Omari"; ``` # MobileStep > Which input a mobile element shows: the phone number, then O'mari's SMS code. Which input a mobile element shows: the phone number, then O’mari’s SMS code. ```ts export type MobileStep = "phone" | "otp"; ``` # NextAction > What the customer must do before the payment can finish. What the customer must do before the payment can finish. * `redirect_to_url`: a mobile payment confirmed with `redirect: "if_required"` needs the customer to go elsewhere to finish it. * `enter_otp`: O’mari has sent the customer an SMS code. The element now asks for it; call [`confirmMobilePayment()`](/embedded-checkout/reference/js/pesepay/#confirmmobilepayment) again with the same element. * `scan_code`: the customer pays in the InnBucks or PayGo app, by scanning `qrImageUrl` or typing `code`. After [`confirmScanPayment()`](/embedded-checkout/reference/js/pesepay/#confirmscanpayment) the scan element shows both. [`retrieveTransaction()`](/embedded-checkout/reference/js/pesepay/#retrievetransaction) returns it too while the payment is unfinished, so a reloaded page can show the same code. * `card_checkout`: the customer pays in the provider’s hosted card form. [`startCardCheckout()`](/embedded-checkout/reference/js/pesepay/#startcardcheckout) returns this once only, so keep it for a reload. ```ts export type NextAction = { type: "redirect_to_url"; redirectToUrl: { url: string; }; } | { type: "enter_otp"; } | { type: "scan_code"; scanCode: ScanCode; } | { type: "card_checkout"; cardCheckout: CardCheckout; }; ``` # PayableAmount > What the customer pays with the selected method. What the customer pays with the selected method. ```ts export interface PayableAmount extends TransactionAmount ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ------- | -------- | ------------------------------------------------------------------ | | `fee` | `number` | The fee the customer pays on top of `value`. 0 when you absorb it. | | `total` | `number` | `value` plus `fee`: what the customer is charged. | Also has everything [`TransactionAmount`](/embedded-checkout/reference/js/transaction-amount/) has. # PaymentChangeEvent > `empty` until the customer picks a method. `complete` once the method is priced and its fields are filled in. `empty` until the customer picks a method. `complete` once the method is priced and its fields are filled in. ```ts export interface PaymentChangeEvent extends BaseChangeEvent ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ------------------- | ----------------------- | ------------------------------------------------------------------------ | | `amount` | `PayableAmount \| null` | What the chosen method charges, fee included. `null` until it is priced. | | `elementType` | `"payment"` | Always `"payment"`. | | `paymentMethodCode` | `string \| null` | The chosen method’s code, or `null` before the customer picks one. | Also has everything [`BaseChangeEvent`](/embedded-checkout/reference/js/base-change-event/) has. # PaymentElement > Every method the transaction can be paid with, grouped as mobile money, card and scan to pay. The chosen method shows its fields and the total with its fee. Pay with `confirmPayment()`. It renders in your page; card numbers stay in Pesepay's or the card provider's frames. Every method the transaction can be paid with, grouped as mobile money, card and scan to pay. The chosen method shows its fields and the total with its fee. Pay with [`confirmPayment()`](/embedded-checkout/reference/js/pesepay/#confirmpayment). It renders in your page; card numbers stay in Pesepay’s or the card provider’s frames. ```ts export interface PaymentElement extends PesepayElementBase ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ------------- | ----------- | ------------------- | | `elementType` | `"payment"` | Always `"payment"`. | ## Events [Section titled “Events”](#events) Listen with `on()`, `once()` or `off()`, by event name. Each handler receives the event’s payload. | Event | Payload | Description | | ----------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | | `change` | [`PaymentChangeEvent`](/embedded-checkout/reference/js/payment-change-event/) | The chosen method or its fields changed. | | `blur` | [`ElementBlurEvent`](/embedded-checkout/reference/js/element-blur-event/) | A field lost focus. | | `escape` | [`ElementEscapeEvent`](/embedded-checkout/reference/js/element-escape-event/) | The customer pressed Escape. | | `focus` | [`ElementFocusEvent`](/embedded-checkout/reference/js/element-focus-event/) | A field gained focus. | | `loaderror` | [`ElementLoadErrorEvent`](/embedded-checkout/reference/js/element-load-error-event/) | The element could not load. | | `ready` | [`ElementReadyEvent`](/embedded-checkout/reference/js/element-ready-event/) | The element has rendered. | | `status` | [`ElementStatusEvent`](/embedded-checkout/reference/js/element-status-event/) | Sent only by the mobile and payment elements, as a mobile money payment progresses. | Also has everything [`PesepayElementBase`](/embedded-checkout/reference/js/pesepay-element-base/) has. # PaymentElementOptions > Options for `elements.create("payment")`. Options for `elements.create("payment")`. ```ts export interface PaymentElementOptions extends Pick ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `referenceNumber` | `string` | The transaction to list methods for, price and pay. | | `returnUrl?` | `string` | Where Mastercard and Zimswitch bring the customer back to, as an absolute http(s) URL. Defaults to this page. See [`HostedCardElementOptions.returnUrl`](/embedded-checkout/reference/js/hosted-card-element-options/). | # PaymentMethod > A payment method Pesepay offers for a transaction's currency. A payment method Pesepay offers for a transaction’s currency. ```ts export interface PaymentMethod ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | -------------------- | --------------------------------------- | ----------------------------------------------------------------------------- | | `available` | `boolean` | False when the transaction’s amount is outside `limits`. | | `code` | `string` | Pass as `paymentMethodCode` to `selectPaymentMethod` and the confirm methods. | | `limits` | `{ minimum: number; maximum: number; }` | The amounts this method takes, in the transaction’s currency. | | `name` | `string` | Pesepay’s display name, e.g. “Ecocash USD”. | | `processingMessage?` | `string` | Pesepay’s text to show while the payment is processing. | | `requiredFields` | `string[]` | Names of the fields the method needs, e.g. `customerPhoneNumber`. | # PaymentMethodsResult > What `listPaymentMethods()` returns: the methods and the amount, or an error. What [`listPaymentMethods()`](/embedded-checkout/reference/js/pesepay/#listpaymentmethods) returns: the methods and the amount, or an error. ```ts export type PaymentMethodsResult = { paymentMethods: PaymentMethod[]; amount: TransactionAmount; error?: never; } | { paymentMethods?: never; amount?: never; error: PesepayError; }; ``` # Pesepay > What `loadPesepay()` resolves to. What [`loadPesepay()`](/embedded-checkout/reference/js/load-pesepay/) resolves to. ```ts export interface Pesepay ``` ## Methods [Section titled “Methods”](#methods) ### `cancelTransaction()` [Section titled “cancelTransaction()”](#canceltransaction) ```ts cancelTransaction(referenceNumber: string, options?: { signal?: AbortSignal; }): Promise; ``` Cancels a payment nothing can have been taken for: one not yet sent, or an O’mari payment waiting for its SMS code. Anything else already with a provider returns `cancel_not_allowed`, as does Mastercard or Zimswitch once selected, since their hosted form may have been submitted. A finished transaction comes back as it is. | Parameter | Type | | ----------------- | --------------------------- | | `referenceNumber` | `string` | | `options?` | `{ signal?: AbortSignal; }` | ### `confirmCardPayment()` [Section titled “confirmCardPayment()”](#confirmcardpayment) ```ts confirmCardPayment(referenceNumber: string, data: ConfirmCardPaymentData): Promise; ``` Pays with the card in a card element. See [`ConfirmCardPaymentData`](/embedded-checkout/reference/js/confirm-card-payment-data/) for 3-D Secure. | Parameter | Type | | ----------------- | -------------------------------------------------------------------------------------- | | `referenceNumber` | `string` | | `data` | [`ConfirmCardPaymentData`](/embedded-checkout/reference/js/confirm-card-payment-data/) | ### `confirmHostedCardPayment()` [Section titled “confirmHostedCardPayment()”](#confirmhostedcardpayment) ```ts confirmHostedCardPayment(referenceNumber: string, data: ConfirmHostedCardPaymentData): Promise; ``` Pays with the card in a `hostedCard` element (Mastercard or Zimswitch), from your own button. The form checks the card first: if it refuses, this returns `incomplete_details` and the form shows the customer why. Otherwise the browser leaves for the customer’s bank and comes back to the transaction’s return URL, where [`handleRedirectResult()`](/embedded-checkout/reference/js/pesepay/#handleredirectresult) finishes the job. A transaction that has already finished comes back as it is, unsent. | Parameter | Type | | ----------------- | --------------------------------------------------------------------------------------------------- | | `referenceNumber` | `string` | | `data` | [`ConfirmHostedCardPaymentData`](/embedded-checkout/reference/js/confirm-hosted-card-payment-data/) | ### `confirmMobilePayment()` [Section titled “confirmMobilePayment()”](#confirmmobilepayment) ```ts confirmMobilePayment(referenceNumber: string, data: ConfirmMobilePaymentData): Promise; ``` Pays from the phone number in the element. EcoCash finishes in one call. O’mari takes two: the first sends the customer an SMS code and returns the transaction with `nextAction.type` `enter_otp`, and the element then asks for that code. Call this again with the same element to pay. The element does not go back to the phone number: a second SMS would need a new transaction. | Parameter | Type | | ----------------- | ------------------------------------------------------------------------------------------ | | `referenceNumber` | `string` | | `data` | [`ConfirmMobilePaymentData`](/embedded-checkout/reference/js/confirm-mobile-payment-data/) | ### `confirmPayment()` [Section titled “confirmPayment()”](#confirmpayment) ```ts confirmPayment(referenceNumber: string, data: ConfirmPaymentData): Promise; ``` Pays with any element, by calling the confirm method for its type: [`confirmCardPayment()`](/embedded-checkout/reference/js/pesepay/#confirmcardpayment), [`confirmMobilePayment()`](/embedded-checkout/reference/js/pesepay/#confirmmobilepayment), [`confirmScanPayment()`](/embedded-checkout/reference/js/pesepay/#confirmscanpayment) or [`confirmHostedCardPayment()`](/embedded-checkout/reference/js/pesepay/#confirmhostedcardpayment). It returns what that method returns, `nextAction` included, so O’mari still takes a second call with the same element and a scan payment still returns its code. An option the element’s payment cannot use returns `parameter_invalid` rather than being dropped: `redirect` with a card or scan element, and `customer`, `metadata`, `paymentMethodCode` or `redirect` with a hostedCard or payment element. A payment element pays with the method the customer chose in it. A checkout element can’t be passed: it pays with its own button. | Parameter | Type | | ----------------- | ----------------------- | | `referenceNumber` | `string` | | `data` | `ConfirmPaymentData` | ### `confirmScanPayment()` [Section titled “confirmScanPayment()”](#confirmscanpayment) ```ts confirmScanPayment(referenceNumber: string, data: ConfirmScanPaymentData): Promise; ``` Starts an InnBucks or PayGo payment and shows its QR code and short code in the scan element. Returns the transaction at `processing` with `nextAction.type` `scan_code`; the customer then pays in their app, so follow with [`waitForTransaction()`](/embedded-checkout/reference/js/pesepay/#waitfortransaction). Returns `scan_code_unavailable` if the provider sent no code. | Parameter | Type | | ----------------- | -------------------------------------------------------------------------------------- | | `referenceNumber` | `string` | | `data` | [`ConfirmScanPaymentData`](/embedded-checkout/reference/js/confirm-scan-payment-data/) | ### `elements()` [Section titled “elements()”](#elements) ```ts elements(options?: ElementsOptions): Elements; ``` Creates a group of elements. Two groups on one page are fully independent, which is how you render two card fields. | Parameter | Type | | ---------- | ---------------------------------------------------------------------- | | `options?` | [`ElementsOptions`](/embedded-checkout/reference/js/elements-options/) | ### `handleRedirectResult()` [Section titled “handleRedirectResult()”](#handleredirectresult) ```ts handleRedirectResult(search?: string, options?: HandleRedirectOptions): Promise; ``` Resumes after a 3-D Secure redirect. Reads `referenceNumber` out of the URL — never out of memory, which does not survive a full-page navigation. A customer back from the hosted card form also needs no code of yours: this asks the provider for the result once, then waits as usual. Returns `{ error: { code: "no_redirect_result" } }` on a page that carries no Pesepay result, so it is safe to call unconditionally on load. | Parameter | Type | | ---------- | ----------------------------------------------------------------------------------- | | `search?` | `string` | | `options?` | [`HandleRedirectOptions`](/embedded-checkout/reference/js/handle-redirect-options/) | ### `listPaymentMethods()` [Section titled “listPaymentMethods()”](#listpaymentmethods) ```ts listPaymentMethods(referenceNumber: string, options?: { signal?: AbortSignal; }): Promise; ``` The payment methods Pesepay offers for the transaction’s currency, each marked `available` if the transaction’s amount is within its limits. ZiG (Zimbabwe Gold) has two codes, `ZiG` and `ZWG`, and Pesepay files each method under one of them, so a transaction in either lists the methods under both. | Parameter | Type | | ----------------- | --------------------------- | | `referenceNumber` | `string` | | `options?` | `{ signal?: AbortSignal; }` | ### `retrieveTransaction()` [Section titled “retrieveTransaction()”](#retrievetransaction) ```ts retrieveTransaction(referenceNumber: string, options?: { signal?: AbortSignal; }): Promise; ``` A single read, never a poll. [`waitForTransaction()`](/embedded-checkout/reference/js/pesepay/#waitfortransaction) is the one that waits. | Parameter | Type | | ----------------- | --------------------------- | | `referenceNumber` | `string` | | `options?` | `{ signal?: AbortSignal; }` | ### `selectPaymentMethod()` [Section titled “selectPaymentMethod()”](#selectpaymentmethod) ```ts selectPaymentMethod(referenceNumber: string, paymentMethodCode: string, options?: { signal?: AbortSignal; }): Promise; ``` Records the customer’s choice of method and returns what they will pay with it, fees included. Call it when the customer picks a method, to show the total. The confirm methods select again, so the charge always matches the method they pay with. | Parameter | Type | | ------------------- | --------------------------- | | `referenceNumber` | `string` | | `paymentMethodCode` | `string` | | `options?` | `{ signal?: AbortSignal; }` | ### `startCardCheckout()` [Section titled “startCardCheckout()”](#startcardcheckout) ```ts startCardCheckout(referenceNumber: string, paymentMethodCode: string, options?: { signal?: AbortSignal; }): Promise; ``` Selects Mastercard or Zimswitch and opens the provider’s hosted card form. Returns the transaction with `nextAction.type` `card_checkout`, or `card_checkout_unavailable` if the provider opened nothing. Each call makes a new checkout, and only the newest is tracked, so a customer paying on an older one could be charged and shown as failed. Call it once for each payment, and keep `cardCheckout` for a reload. | Parameter | Type | | ------------------- | --------------------------- | | `referenceNumber` | `string` | | `paymentMethodCode` | `string` | | `options?` | `{ signal?: AbortSignal; }` | ### `syncCardCheckout()` [Section titled “syncCardCheckout()”](#synccardcheckout) ```ts syncCardCheckout(referenceNumber: string, options?: { signal?: AbortSignal; }): Promise; ``` Asks the provider once for a customer back from the hosted card form, then returns the stored transaction. The provider limits these reads, so never poll this: follow with [`waitForTransaction()`](/embedded-checkout/reference/js/pesepay/#waitfortransaction). | Parameter | Type | | ----------------- | --------------------------- | | `referenceNumber` | `string` | | `options?` | `{ signal?: AbortSignal; }` | ### `waitForTransaction()` [Section titled “waitForTransaction()”](#waitfortransaction) ```ts waitForTransaction(referenceNumber: string, options?: WaitForTransactionOptions): Promise; ``` Waits until the transaction is no longer `processing` — for a mobile payment, while the customer approves it on their phone. Resolves with the transaction, or a `timeout` error once `timeoutMs` passes. Use this rather than a loop of your own: it backs off, and shares one poll between callers. | Parameter | Type | | ----------------- | -------------------------------------------------------------------------------------------- | | `referenceNumber` | `string` | | `options?` | [`WaitForTransactionOptions`](/embedded-checkout/reference/js/wait-for-transaction-options/) | # PesepayConfig > Options for `loadPesepay()`. Options for [`loadPesepay()`](/embedded-checkout/reference/js/load-pesepay/). ```ts export interface PesepayConfig ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ----------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `apiBaseUrl?` | `string` | The Pesepay API. Default: the live API. Test Embedded checkout with small live payments: the sandbox runs neither 3-D Secure nor the card providers’ forms. | | `applicationId?` | `string` | Leave unset. The card processor’s application id: the SDK already uses Pesepay’s, which every merchant shares. Set it only if Pesepay has issued you one of your own. | | `checkoutOrigin?` | `string` | Where the Hosted checkout page that `loaderror`’s `fallbackUrl` points to is served. Leave unset: it defaults to Pesepay’s. | | `elementsOrigin?` | `string` | Where the card fields’ frames load from. Leave unset: it defaults to Pesepay’s. | | `locale?` | `string` | BCP 47 tag, or `"auto"` to follow the browser. Reserved: `en` is the only language today. | | `logLevel?` | [`LogLevel`](/embedded-checkout/reference/js/log-level/) | How much the SDK writes to the console. See [`LogLevel`](/embedded-checkout/reference/js/log-level/). | | `publishableKey?` | `string` | Leave unset: Pesepay does not issue publishable keys yet, and every call the SDK makes is authorised by the transaction’s reference number. When set, it is sent as `X-Pesepay-Publishable-Key` on every request. Never put your integration or encryption key here. | | `requestTimeout?` | `number` | Milliseconds to wait for each API call the SDK makes. Default 30000, 30 seconds. | | `theme?` | [`PesepayTheme`](/embedded-checkout/reference/js/pesepay-theme/) | Theme for every element. Groups and elements can override it. | # PesepayElementBase > What every element can do: mount, update, focus, clear and send events. `create()` does not mount, so you can set an element up before its container exists. Each element's page lists the events it sends. What every element can do: mount, update, focus, clear and send events. `create()` does not mount, so you can set an element up before its container exists. Each element’s page lists the events it sends. Your page cannot read what the customer typed: card details stay in Pesepay’s frame. Pass the element to [`confirmCardPayment()`](/embedded-checkout/reference/js/pesepay/#confirmcardpayment) to pay. ```ts export interface PesepayElementBase ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ------------- | -------------------------------------------------------------- | -------------------- | | `elementType` | [`ElementType`](/embedded-checkout/reference/js/element-type/) | The kind of element. | ## Methods [Section titled “Methods”](#methods) ### `blur()` [Section titled “blur()”](#blur) ```ts blur(): void; ``` Removes focus from the element. ### `clear()` [Section titled “clear()”](#clear) ```ts clear(): void; ``` Clears what the customer has entered. ### `destroy()` [Section titled “destroy()”](#destroy) ```ts destroy(): void; ``` Unmounts and releases everything. The element cannot be reused. ### `focus()` [Section titled “focus()”](#focus) ```ts focus(): void; ``` Moves focus into the element. ### `mount()` [Section titled “mount()”](#mount) ```ts mount(target: string | HTMLElement): void; ``` Renders into a CSS selector or an element. Throws if the target is missing. | Parameter | Type | | --------- | ----------------------- | | `target` | `string \| HTMLElement` | ### `off()` [Section titled “off()”](#off) ```ts off(type: K, handler?: (event: Events[K]) => void): this; ``` Omitting the handler removes every listener for that event. | Parameter | Type | | ---------- | ---------------------------- | | `type` | `K` | | `handler?` | `(event: Events[K]) => void` | ### `on()` [Section titled “on()”](#on) ```ts on(type: K, handler: (event: Events[K]) => void): this; ``` Adds a listener. Returns the element, so calls chain. | Parameter | Type | | --------- | ---------------------------- | | `type` | `K` | | `handler` | `(event: Events[K]) => void` | ### `once()` [Section titled “once()”](#once) ```ts once(type: K, handler: (event: Events[K]) => void): this; ``` Adds a listener that runs once. Returns the element, so calls chain. | Parameter | Type | | --------- | ---------------------------- | | `type` | `K` | | `handler` | `(event: Events[K]) => void` | ### `unmount()` [Section titled “unmount()”](#unmount) ```ts unmount(): void; ``` Removes the element from the DOM. It can be mounted again. ### `update()` [Section titled “update()”](#update) ```ts update(options: Partial): void; ``` Changes some options. Options you leave out keep their values. | Parameter | Type | | --------- | ------------------ | | `options` | `Partial` | # PesepayError > The shape of `result.error`. An interface, not a class — the class ships in the CDN runtime. Narrow on `code`, not `instanceof`. The shape of `result.error`. An interface, not a class — the class ships in the CDN runtime. Narrow on `code`, not `instanceof`. ```ts export interface PesepayError extends Error ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | -------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `code` | [`PesepayErrorCode`](/embedded-checkout/reference/js/pesepay-error-code/) | The specific reason. Branch on this. | | `declineCode?` | `string` | Raw refusal reason from the processor, when one was given. | | `param?` | [`PesepayErrorParam`](/embedded-checkout/reference/js/pesepay-error-param/) | The option or field the error is about, when there is one. | | `requestId?` | `string` | Correlates a failure with Pesepay’s logs, from a `Pesepay-Request-Id` header when the response carried one. | | `statusCode?` | `number` | HTTP status, when the failure came from a response. | | `type` | [`PesepayErrorType`](/embedded-checkout/reference/js/pesepay-error-type/) | The broad category, such as `card_error` or `network_error`. | # PesepayErrorCode > Every code a `PesepayError` can carry. Branch on these, not on `message`. Every code a [`PesepayError`](/embedded-checkout/reference/js/pesepay-error/) can carry. Branch on these, not on `message`. ```ts export type PesepayErrorCode = (typeof PESEPAY_ERROR_CODES)[number]; ``` # PESEPAY_ERROR_CODES > Every error code the SDK can return, as an array you can loop over, for example to check that your own messages cover them all. Every error code the SDK can return, as an array you can loop over, for example to check that your own messages cover them all. ```ts PESEPAY_ERROR_CODES: readonly ["incomplete_number", "incomplete_expiry", "incomplete_cvc", "incomplete_phone", "incomplete_details", "invalid_number", "invalid_expiry_month", "invalid_expiry_year", "invalid_cvc", "invalid_phone", "number_too_long", "expiry_too_long", "cvc_too_long", "phone_too_long", "wrong_network_phone", "incomplete_otp", "invalid_otp", "card_brand_not_supported", "use_mastercard_option", "card_declined", "expired_card", "incorrect_cvc", "incorrect_number", "insufficient_funds", "processing_error", "authentication_failed", "parameter_missing", "parameter_invalid", "resource_missing", "payment_method_unsupported", "cancel_not_allowed", "no_redirect_result", "invalid_publishable_key", "unauthorized", "api_error", "unexpected_response", "scan_code_unavailable", "card_checkout_unavailable", "obfuscation_failed", "decryption_failed", "frame_load_error", "frame_timeout", "frame_error", "portal_not_allowed", "network_error", "timeout", "outcome_unknown", "rate_limit"] ``` # PesepayErrorParam > Which field a `validation_error` or `card_error` refers to, when one applies. Which field a `validation_error` or `card_error` refers to, when one applies. ```ts export type PesepayErrorParam = "number" | "expiry" | "cvc" | "phone" | "otp" | "account"; ``` # PesepayErrorType > Broad category. Determines how a merchant should react, not what went wrong. Broad category. Determines how a merchant should react, not what went wrong. ```ts export type PesepayErrorType = /** The card itself was refused, or cannot be used. Show the customer. */ "card_error" /** Decided locally, before any request. The customer can fix it by typing. */ | "validation_error" /** The merchant's integration is wrong. Show a developer, not a customer. */ | "invalid_request_error" /** Pesepay failed. Retrying may work. */ | "api_error" /** The request never completed. Retrying may work. */ | "network_error" /** Pesepay asked the SDK to slow down. Wait before retrying. */ | "rate_limit_error" /** The publishable key or transaction credential was rejected. */ | "authentication_error"; ``` # PesepayTheme > How elements look. Set it in `loadPesepay()`, in `elements()` or on one element: each layer overrides the one before. How elements look. Set it in [`loadPesepay()`](/embedded-checkout/reference/js/load-pesepay/), in [`elements()`](/embedded-checkout/reference/js/pesepay/#elements) or on one element: each layer overrides the one before. ```ts export interface PesepayTheme ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `colors?` | `{ primary?: string; primaryText?: string; border?: string; borderFocus?: string; background?: string; text?: string; error?: string; success?: string; placeholder?: string; }` | Colours, as CSS colour values. | | `fonts?` | `{ family?: string; size?: string; weight?: string; }` | Font family, size and weight, as CSS values. Load a web font for the card fields with [`ElementsOptions.fonts`](/embedded-checkout/reference/js/elements-options/). | | `labels?` | [`ThemeLabels`](/embedded-checkout/reference/js/theme-labels/) | Where field labels go. Defaults to `"hidden"` for the card fields and `"above"` for the mobile element. | | `preset?` | [`ThemePreset`](/embedded-checkout/reference/js/theme-preset/) | Starts from a preset. Every other token you set, in any theme layer, overrides the preset’s value. | | `spacing?` | `{ padding?: string; borderRadius?: string; borderWidth?: string; gap?: string; }` | Padding, corner radius and border width, as CSS lengths. | | `states?` | `{ disabled?: { opacity?: number; cursor?: string; }; focus?: { boxShadow?: string; borderColor?: string; }; invalid?: { borderColor?: string; color?: string; }; }` | Overrides for the disabled, focused and invalid states. | # RedirectingPaymentData > Options for a confirm that may need the customer to leave the page. Options for a confirm that may need the customer to leave the page. ```ts export interface RedirectingPaymentData extends ConfirmDataBase ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | -------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `redirect?` | `"always" \| "if_required"` | `"always"` (default) navigates the browser when the payment needs the customer elsewhere. `"if_required"` returns the transaction with `nextAction` set and leaves the navigation to you. | | `customer?` | [`CustomerDetails`](/embedded-checkout/reference/js/customer-details/) | The customer paying. | | `metadata?` | `Record` | Sent with the payment and echoed back on `transaction.metadata`. Stored against the transaction, so not a place for anything sensitive. | | `paymentMethodCode?` | `string` | Override the payment method code, such as `PZW211` for EcoCash USD. Leave it unset: the SDK picks it from the card’s brand, or from the element’s provider and the transaction’s currency. | | `signal?` | `AbortSignal` | Abandons the confirm. Resolves with an `outcome_unknown` error rather than throwing: a payment already sent cannot be recalled. | # ScanCode > What the customer pays with in the provider's app. What the customer pays with in the provider’s app. ```ts export interface ScanCode ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ------------ | -------- | --------------------------------------------------------------------------------------------------------- | | `code` | `string` | The short code to type in the app or USSD menu. | | `qrImageUrl` | `string` | An image of the QR code, for an ``: a `data:` URL for InnBucks, PayGo’s own https URL for PayGo. | # ScanElement > Shows the QR code and short code the customer pays with in the InnBucks or PayGo app. It has no input: it is empty until `confirmScanPayment()` returns the code. Shows the QR code and short code the customer pays with in the InnBucks or PayGo app. It has no input: it is empty until [`confirmScanPayment()`](/embedded-checkout/reference/js/pesepay/#confirmscanpayment) returns the code. ```ts export interface ScanElement extends PesepayElementBase ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ------------- | -------- | ---------------- | | `elementType` | `"scan"` | Always `"scan"`. | ## Events [Section titled “Events”](#events) Listen with `on()`, `once()` or `off()`, by event name. Each handler receives the event’s payload. | Event | Payload | Description | | ----------- | ------------------------------------------------------------------------------------ | ---------------------------- | | `blur` | [`ElementBlurEvent`](/embedded-checkout/reference/js/element-blur-event/) | A field lost focus. | | `change` | [`BaseChangeEvent`](/embedded-checkout/reference/js/base-change-event/) | The input changed. | | `escape` | [`ElementEscapeEvent`](/embedded-checkout/reference/js/element-escape-event/) | The customer pressed Escape. | | `focus` | [`ElementFocusEvent`](/embedded-checkout/reference/js/element-focus-event/) | A field gained focus. | | `loaderror` | [`ElementLoadErrorEvent`](/embedded-checkout/reference/js/element-load-error-event/) | The element could not load. | | `ready` | [`ElementReadyEvent`](/embedded-checkout/reference/js/element-ready-event/) | The element has rendered. | Also has everything [`PesepayElementBase`](/embedded-checkout/reference/js/pesepay-element-base/) has. # ScanElementOptions > Options for `elements.create("scan")`. Options for `elements.create("scan")`. ```ts export interface ScanElementOptions extends BaseElementOptions ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ----------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------- | | `provider?` | [`ScanProvider`](/embedded-checkout/reference/js/scan-provider/) | The app the customer pays in. Defaults to `"InnBucks"`; set `"PayGo"` for PayGo. | Also has everything [`BaseElementOptions`](/embedded-checkout/reference/js/base-element-options/) has. # ScanProvider > Pay-by-code apps. The customer scans a QR code with the provider's app, or types its short code there. InnBucks pays in USD and PayGo in ZiG (Zimbabwe Gold). Pay-by-code apps. The customer scans a QR code with the provider’s app, or types its short code there. InnBucks pays in USD and PayGo in ZiG (Zimbabwe Gold). ```ts export type ScanProvider = "InnBucks" | "PayGo"; ``` # SelectPaymentMethodResult > What `selectPaymentMethod()` returns: the priced amount, or an error. What [`selectPaymentMethod()`](/embedded-checkout/reference/js/pesepay/#selectpaymentmethod) returns: the priced amount, or an error. ```ts export type SelectPaymentMethodResult = { amount: PayableAmount; error?: never; } | { amount?: never; error: PesepayError; }; ``` # ThemeLabels > Where field labels go. `"hidden"` still names each field to screen readers. Where field labels go. `"hidden"` still names each field to screen readers. ```ts export type ThemeLabels = "above" | "floating" | "hidden"; ``` # ThemePreset > A ready-made set of colours, spacing and states. `"night"` is dark, `"flat"` is borderless on a tinted fill. Labels and fonts stay yours. A ready-made set of colours, spacing and states. `"night"` is dark, `"flat"` is borderless on a tinted fill. Labels and fonts stay yours. ```ts export type ThemePreset = "night" | "flat"; ``` # Transaction > A Pesepay transaction, as the SDK reads it. A Pesepay transaction, as the SDK reads it. ```ts export interface Transaction ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ----------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `amount?` | [`TransactionAmount`](/embedded-checkout/reference/js/transaction-amount/) | The amount, once it is known. | | `description?` | `string` | The `reasonForPayment` the merchant created the transaction with. | | `merchantName?` | `string` | The name of the merchant’s Pesepay application. | | `merchantReference?` | `string` | Your own reference, as you created the transaction with it. | | `message?` | `string` | Human-readable status from Pesepay. Not stable enough to branch on. | | `metadata?` | `Record` | The `metadata` sent with the payment. | | `nextAction?` | [`NextAction`](/embedded-checkout/reference/js/next-action/) | What the customer must do next, while the payment is unfinished. | | `outcome` | [`TransactionOutcome`](/embedded-checkout/reference/js/transaction-outcome/) | What `status` means for your checkout. See [`TransactionOutcome`](/embedded-checkout/reference/js/transaction-outcome/). | | `paymentMethodCode?` | `string` | The payment method selected for this transaction, e.g. `PZW211`. | | `paymentMethodMessage?` | `string` | The provider’s own reason, when it gave one. Its wording can change. | | `referenceNumber` | `string` | Pesepay’s reference for the transaction. | | `returnUrl?` | `string` | The merchant’s `returnUrl`. Only an absolute http(s) URL is passed on. | | `status` | [`TransactionStatus`](/embedded-checkout/reference/js/transaction-status/) | Pesepay’s own status. Branch on `outcome`, not this. | # TransactionAmount > A transaction's amount. A transaction’s amount. ```ts export interface TransactionAmount ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `currency` | `string` | The currency code: `USD`, or `ZiG` or `ZWG` for ZiG (Zimbabwe Gold). Pesepay files each ZiG payment method under one of the two codes. | | `total?` | `number` | What the customer pays, fee included. Set once a payment method is selected. | | `value` | `number` | Major units, so 1.5 means $1.50. | # TransactionOutcome > What a transaction's status means for your checkout. Derived from `TransactionStatus` by one table, so you do not have to keep your own. What a transaction’s status means for your checkout. Derived from [`TransactionStatus`](/embedded-checkout/reference/js/transaction-status/) by one table, so you do not have to keep your own. * `succeeded` — the customer paid. * `failed` — the customer did not pay: declined, cancelled, closed or expired. * `processing` — not finished; wait, or let [`handleRedirectResult()`](/embedded-checkout/reference/js/pesepay/#handleredirectresult) or [`waitForTransaction()`](/embedded-checkout/reference/js/pesepay/#waitfortransaction) wait for you. * `unknown` — Pesepay could not find out what happened, or reported a status this SDK does not recognise. **Not a failure.** The customer may have paid. Confirm on your server before letting them pay again. * `reversed` — paid, then the money was returned. ```ts export type TransactionOutcome = "succeeded" | "failed" | "processing" | "unknown" | "reversed"; ``` # TransactionStatus > Pesepay's own status for a transaction, exactly as the API reports it. Pesepay’s own status for a transaction, exactly as the API reports it. Branch on [`Transaction.outcome`](/embedded-checkout/reference/js/transaction/) instead. Several of these mean the same thing to a checkout, and three — `TIME_OUT`, `SERVICE_UNAVAILABLE` and `ERROR` — mean Pesepay did not get the provider’s answer, not that the payment failed: their outcome is `unknown`. ```ts export type TransactionStatus = "INITIATED" | "PENDING" | "PROCESSING" | "PARTIALLY_PAID" | "SUCCESS" | "FAILED" | "DECLINED" | "INSUFFICIENT_FUNDS" | "AUTHORIZATION_FAILED" | "CANCELLED" | "TERMINATED" | "CLOSED" | "CLOSED_PERIOD_ELAPSED" | "TIME_OUT" | "SERVICE_UNAVAILABLE" | "ERROR" | "REVERSED"; ``` # WaitForTransactionOptions > Options for `waitForTransaction()`. Options for [`waitForTransaction()`](/embedded-checkout/reference/js/pesepay/#waitfortransaction). ```ts export interface WaitForTransactionOptions ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `signal?` | `AbortSignal` | Stops waiting early, with a `timeout` error. The payment itself carries on. | | `timeoutMs?` | `number` | How long to wait before returning a `timeout` error. Default 180000, three minutes. A timeout means the SDK stopped looking, not that the payment failed. | # @pesepay/react > API reference for @pesepay/react. Every public export of `@pesepay/react`, generated from its type declarations. [@pesepay/react on npm](https://www.npmjs.com/package/@pesepay/react). ## Functions and components [Section titled “Functions and components”](#functions-and-components) | Name | Description | | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`CardElement`](/embedded-checkout/reference/react/card-element/) | Visa card fields in a Pesepay frame. Pay with `confirmPayment()` and `elements.getElement("card")`. | | [`CheckoutElement`](/embedded-checkout/reference/react/checkout-element/) | The payment element with its own Pay button. It runs every step of the payment; handle `onFinished`. A new `referenceNumber` replaces the element. | | [`Elements`](/embedded-checkout/reference/react/elements/) | Creates one elements group for the components inside it, and destroys it when it unmounts. | | [`HostedCardElement`](/embedded-checkout/reference/react/hosted-card-element/) | The card provider’s form for Mastercard and Zimswitch. One per page. | | [`MobileElement`](/embedded-checkout/reference/react/mobile-element/) | EcoCash or O’mari phone number, and O’mari’s SMS code. | | [`PaymentElement`](/embedded-checkout/reference/react/payment-element/) | Every method the transaction can be paid with. A new `referenceNumber` replaces the element. | | [`ScanElement`](/embedded-checkout/reference/react/scan-element/) | The InnBucks or PayGo code the customer scans. | | [`useElements`](/embedded-checkout/reference/react/use-elements/) | The elements group `` created, or `null` while Pesepay loads and during server rendering. Read an element off it to pay with: `elements.getElement("card")`. | | [`usePesepay`](/embedded-checkout/reference/react/use-pesepay/) | The Pesepay instance `` was given, or `null` while it loads and during server rendering. | ## Interfaces [Section titled “Interfaces”](#interfaces) | Name | Description | | ------------------------------------------------------------------------------ | ------------------------------------------------- | | [`ElementEventProps`](/embedded-checkout/reference/react/element-event-props/) | An element’s event callbacks, one prop per event. | | [`ElementsProps`](/embedded-checkout/reference/react/elements-props/) | Props for ``. | ## Types [Section titled “Types”](#types) | Name | Description | | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`CardElementProps`](/embedded-checkout/reference/react/card-element-props/) | Props for ``. | | [`CheckoutElementProps`](/embedded-checkout/reference/react/checkout-element-props/) | Props for ``. | | [`ElementFinishedProps`](/embedded-checkout/reference/react/element-finished-props/) | `onFinished`, on the checkout element: its payment has ended. | | [`ElementProps`](/embedded-checkout/reference/react/element-props/) | Props shared by every element component. `options` is required where the element needs one: `cardCheckout` for `hostedCard`, `referenceNumber` for `payment` and `checkout`. | | [`ElementStatusProps`](/embedded-checkout/reference/react/element-status-props/) | `onStatus`, on the elements that report a sent payment’s progress: mobile and payment. | | [`HostedCardElementProps`](/embedded-checkout/reference/react/hosted-card-element-props/) | Props for ``. | | [`MobileElementProps`](/embedded-checkout/reference/react/mobile-element-props/) | Props for ``. | | [`PaymentElementProps`](/embedded-checkout/reference/react/payment-element-props/) | Props for ``. | | [`ScanElementProps`](/embedded-checkout/reference/react/scan-element-props/) | Props for ``. | # CardElement > Visa card fields in a Pesepay frame. Pay with `confirmPayment()` and `elements.getElement("card")`. Visa card fields in a Pesepay frame. Pay with [`confirmPayment()`](/embedded-checkout/reference/js/pesepay/#confirmpayment) and `elements.getElement("card")`. ```ts CardElement: (props: CardElementProps) => ReactElement ``` | Parameter | Type | | --------- | ---------------------------------------------------------------------------- | | `props` | [`CardElementProps`](/embedded-checkout/reference/react/card-element-props/) | # CardElementProps > Props for ``. Props for ``. ```ts export type CardElementProps = ElementProps<"card">; ``` # CheckoutElement > The payment element with its own Pay button. It runs every step of the payment; handle `onFinished`. A new `referenceNumber` replaces the element. The payment element with its own Pay button. It runs every step of the payment; handle `onFinished`. A new `referenceNumber` replaces the element. ```ts CheckoutElement: (props: CheckoutElementProps) => ReactElement ``` | Parameter | Type | | --------- | ------------------------------------------------------------------------------------ | | `props` | [`CheckoutElementProps`](/embedded-checkout/reference/react/checkout-element-props/) | # CheckoutElementProps > Props for ``. Props for ``. ```ts export type CheckoutElementProps = ElementProps<"checkout">; ``` # ElementEventProps > An element's event callbacks, one prop per event. An element’s event callbacks, one prop per event. ```ts export interface ElementEventProps ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | -------------- | -------------------------------------- | ------------------------------------------------------------- | | `onBlur?` | `(event: Events["blur"]) => void` | A field lost focus. | | `onChange?` | `(event: Events["change"]) => void` | The customer changed a value. A card’s event carries `brand`. | | `onEscape?` | `(event: Events["escape"]) => void` | The customer pressed Escape. | | `onFocus?` | `(event: Events["focus"]) => void` | A field gained focus. | | `onLoadError?` | `(event: Events["loaderror"]) => void` | The element could not load. `loaderror` in `@pesepay/js`. | | `onReady?` | `(event: Events["ready"]) => void` | The element has rendered. | # ElementFinishedProps > `onFinished`, on the checkout element: its payment has ended. `onFinished`, on the checkout element: its payment has ended. ```ts export type ElementFinishedProps = T extends "checkout" ? { onFinished?: (event: CheckoutFinishedEvent) => void; } : object; ``` # ElementProps > Props shared by every element component. `options` is required where the element needs one: `cardCheckout` for `hostedCard`, `referenceNumber` for `payment` and `checkout`. Props shared by every element component. `options` is required where the element needs one: `cardCheckout` for `hostedCard`, `referenceNumber` for `payment` and `checkout`. ```ts export type ElementProps = { id?: string; className?: string; } & ElementEventProps> & ElementStatusProps & ElementFinishedProps & (object extends ElementOptionsMap[T] ? { options?: ElementOptionsMap[T]; } : { options: ElementOptionsMap[T]; }); ``` # ElementStatusProps > `onStatus`, on the elements that report a sent payment's progress: mobile and payment. `onStatus`, on the elements that report a sent payment’s progress: mobile and payment. ```ts export type ElementStatusProps = T extends "mobile" | "payment" ? { onStatus?: (event: ElementStatusEvent) => void; } : object; ``` # Elements > Creates one elements group for the components inside it, and destroys it when it unmounts. Creates one elements group for the components inside it, and destroys it when it unmounts. On the server, and until the promise resolves, the elements inside render an empty container: [`loadPesepay()`](/embedded-checkout/reference/js/load-pesepay/) resolves `null` where there is no DOM. ```ts export declare function Elements(input: ElementsProps): ReactElement; ``` | Parameter | Type | | -------------------------------- | --------------------------------------------------------------------- | | `{ pesepay, options, children }` | “ | | `input` | [`ElementsProps`](/embedded-checkout/reference/react/elements-props/) | # ElementsProps > Props for ``. Props for ``. ```ts export interface ElementsProps ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ----------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `children?` | `ReactNode` | The element components, and anything that pays with them. | | `options?` | [`ElementsOptions`](/embedded-checkout/reference/js/elements-options/) | Applied to every element inside. A change is passed to `elements.update()`. | | `pesepay?` | `Pesepay \| null \| PromiseLike` | What [`loadPesepay()`](/embedded-checkout/reference/js/load-pesepay/) returns: the promise itself, or the instance once it has resolved. Leave it out and Pesepay loads with the default options; pass `loadPesepay({ ... })` to set any of them. Call [`loadPesepay()`](/embedded-checkout/reference/js/load-pesepay/) once, outside the component, so it is not loaded again. Fixed on first render: a different value later is ignored with a warning. | # HostedCardElement > The card provider's form for Mastercard and Zimswitch. One per page. The card provider’s form for Mastercard and Zimswitch. One per page. ```ts HostedCardElement: (props: HostedCardElementProps) => ReactElement ``` | Parameter | Type | | --------- | ----------------------------------------------------------------------------------------- | | `props` | [`HostedCardElementProps`](/embedded-checkout/reference/react/hosted-card-element-props/) | # HostedCardElementProps > Props for ``. Props for ``. ```ts export type HostedCardElementProps = ElementProps<"hostedCard">; ``` # MobileElement > EcoCash or O'mari phone number, and O'mari's SMS code. EcoCash or O’mari phone number, and O’mari’s SMS code. ```ts MobileElement: (props: MobileElementProps) => ReactElement ``` | Parameter | Type | | --------- | -------------------------------------------------------------------------------- | | `props` | [`MobileElementProps`](/embedded-checkout/reference/react/mobile-element-props/) | # MobileElementProps > Props for ``. Props for ``. ```ts export type MobileElementProps = ElementProps<"mobile">; ``` # PaymentElement > Every method the transaction can be paid with. A new `referenceNumber` replaces the element. Every method the transaction can be paid with. A new `referenceNumber` replaces the element. ```ts PaymentElement: (props: PaymentElementProps) => ReactElement ``` | Parameter | Type | | --------- | ---------------------------------------------------------------------------------- | | `props` | [`PaymentElementProps`](/embedded-checkout/reference/react/payment-element-props/) | # PaymentElementProps > Props for ``. Props for ``. ```ts export type PaymentElementProps = ElementProps<"payment">; ``` # ScanElement > The InnBucks or PayGo code the customer scans. The InnBucks or PayGo code the customer scans. ```ts ScanElement: (props: ScanElementProps) => ReactElement ``` | Parameter | Type | | --------- | ---------------------------------------------------------------------------- | | `props` | [`ScanElementProps`](/embedded-checkout/reference/react/scan-element-props/) | # ScanElementProps > Props for ``. Props for ``. ```ts export type ScanElementProps = ElementProps<"scan">; ``` # useElements > The elements group `` created, or `null` while Pesepay loads and during server rendering. Read an element off it to pay with: `elements.getElement("card")`. The elements group `` created, or `null` while Pesepay loads and during server rendering. Read an element off it to pay with: `elements.getElement("card")`. ```ts export declare function useElements(): Elements | null; ``` # usePesepay > The Pesepay instance `` was given, or `null` while it loads and during server rendering. The Pesepay instance `` was given, or `null` while it loads and during server rendering. ```ts export declare function usePesepay(): Pesepay | null; ``` # @pesepay/vue > API reference for @pesepay/vue. Every public export of `@pesepay/vue`, generated from its type declarations. [@pesepay/vue on npm](https://www.npmjs.com/package/@pesepay/vue). ## Functions and components [Section titled “Functions and components”](#functions-and-components) | Name | Description | | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`useElements`](/embedded-checkout/reference/vue/use-elements/) | The elements group `` created. `null` while Pesepay loads and during server rendering. Read an element off it to pay with: `elements.value?.getElement("card")`. | | [`usePesepay`](/embedded-checkout/reference/vue/use-pesepay/) | The Pesepay instance `` was given. `null` while it loads and during server rendering. | ## Interfaces [Section titled “Interfaces”](#interfaces) | Name | Description | | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | [`ElementsProps`](/embedded-checkout/reference/vue/elements-props/) | Props for ``. | | [`ElementsSlotProps`](/embedded-checkout/reference/vue/elements-slot-props/) | What the default slot receives, so the component that renders `` can pay without a child component. Both are `null` until Pesepay loads. | ## Types [Section titled “Types”](#types) | Name | Description | | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [`ElementComponent`](/embedded-checkout/reference/vue/element-component/) | An element component. | | [`ElementEmits`](/embedded-checkout/reference/vue/element-emits/) | The events an element component emits. `loadError` is written `@load-error` in a template. | | [`ElementFinishedEmits`](/embedded-checkout/reference/vue/element-finished-emits/) | `finished`, on the checkout element: its payment has ended. | | [`ElementProps`](/embedded-checkout/reference/vue/element-props/) | Props of an element component. `options` is required where the element needs one: `cardCheckout` for `hostedCard`, `referenceNumber` for `payment` and `checkout`. `id` and `class` pass through to the container the element mounts into. | | [`ElementsSlots`](/embedded-checkout/reference/vue/elements-slots/) | The slots `` takes. | | [`ElementStatusEmits`](/embedded-checkout/reference/vue/element-status-emits/) | `status`, on the elements that report a sent payment’s progress: mobile and payment. | ## Constants [Section titled “Constants”](#constants) | Name | Description | | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | [`CardElement`](/embedded-checkout/reference/vue/card-element/) | Visa card fields in a Pesepay frame. Pay with `confirmPayment()` and `elements.getElement("card")`. | | [`CheckoutElement`](/embedded-checkout/reference/vue/checkout-element/) | The payment element with its own Pay button. It runs every step of the payment; listen for `@finished`. A new `referenceNumber` replaces the element. | | [`Elements`](/embedded-checkout/reference/vue/elements/) | Creates one elements group for the components inside it, and destroys it when it unmounts. | | [`HostedCardElement`](/embedded-checkout/reference/vue/hosted-card-element/) | The card provider’s form for Mastercard and Zimswitch. One per page. | | [`MobileElement`](/embedded-checkout/reference/vue/mobile-element/) | EcoCash or O’mari phone number, and O’mari’s SMS code. | | [`PaymentElement`](/embedded-checkout/reference/vue/payment-element/) | Every method the transaction can be paid with. A new `referenceNumber` replaces the element. | | [`ScanElement`](/embedded-checkout/reference/vue/scan-element/) | The InnBucks or PayGo code the customer scans. | # CardElement > Visa card fields in a Pesepay frame. Pay with `confirmPayment()` and `elements.getElement("card")`. Visa card fields in a Pesepay frame. Pay with [`confirmPayment()`](/embedded-checkout/reference/js/pesepay/#confirmpayment) and `elements.getElement("card")`. ```ts CardElement: ElementComponent<"card"> ``` # CheckoutElement > The payment element with its own Pay button. It runs every step of the payment; listen for `@finished`. A new `referenceNumber` replaces the element. The payment element with its own Pay button. It runs every step of the payment; listen for `@finished`. A new `referenceNumber` replaces the element. ```ts CheckoutElement: ElementComponent<"checkout"> ``` # ElementComponent > An element component. An element component. ```ts export type ElementComponent = DefineSetupFnComponent, ElementEmits> & ElementStatusEmits & ElementFinishedEmits>; ``` # ElementEmits > The events an element component emits. `loadError` is written `@load-error` in a template. The events an element component emits. `loadError` is written `@load-error` in a template. ```ts export type ElementEmits = { ready: (event: Events["ready"]) => void; change: (event: Events["change"]) => void; focus: (event: Events["focus"]) => void; blur: (event: Events["blur"]) => void; escape: (event: Events["escape"]) => void; loadError: (event: Events["loaderror"]) => void; }; ``` # ElementFinishedEmits > `finished`, on the checkout element: its payment has ended. `finished`, on the checkout element: its payment has ended. ```ts export type ElementFinishedEmits = T extends "checkout" ? { finished: (event: CheckoutFinishedEvent) => void; } : unknown; ``` # ElementProps > Props of an element component. `options` is required where the element needs one: `cardCheckout` for `hostedCard`, `referenceNumber` for `payment` and `checkout`. `id` and `class` pass through to the container the element mounts into. Props of an element component. `options` is required where the element needs one: `cardCheckout` for `hostedCard`, `referenceNumber` for `payment` and `checkout`. `id` and `class` pass through to the container the element mounts into. ```ts export type ElementProps = object extends ElementOptionsMap[T] ? { options?: ElementOptionsMap[T]; } : { options: ElementOptionsMap[T]; }; ``` # ElementStatusEmits > `status`, on the elements that report a sent payment's progress: mobile and payment. `status`, on the elements that report a sent payment’s progress: mobile and payment. ```ts export type ElementStatusEmits = T extends "mobile" | "payment" ? { status: (event: ElementStatusEvent) => void; } : unknown; ``` # Elements > Creates one elements group for the components inside it, and destroys it when it unmounts. Creates one elements group for the components inside it, and destroys it when it unmounts. On the server, and until the promise resolves, the elements inside render an empty container: nothing loads before the component is mounted. ```ts Elements: DefineSetupFnComponent ``` # ElementsProps > Props for ``. Props for ``. ```ts export interface ElementsProps ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ---------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `options?` | [`ElementsOptions`](/embedded-checkout/reference/js/elements-options/) | Applied to every element inside. A change is passed to `elements.update()`. | | `pesepay?` | `Pesepay \| null \| PromiseLike` | What [`loadPesepay()`](/embedded-checkout/reference/js/load-pesepay/) returns: the promise itself, or the instance once it has resolved. Leave it out and Pesepay loads with the default options; pass `loadPesepay({ ... })` to set any of them. Call [`loadPesepay()`](/embedded-checkout/reference/js/load-pesepay/) once, outside the component, so it is not loaded again. Fixed on first render: a different value later is ignored with a warning. | # ElementsSlotProps > What the default slot receives, so the component that renders `` can pay without a child component. Both are `null` until Pesepay loads. What the default slot receives, so the component that renders `` can pay without a child component. Both are `null` until Pesepay loads. ```ts export interface ElementsSlotProps ``` ## Properties [Section titled “Properties”](#properties) | Name | Type | Description | | ---------- | ----------------------- | -------------------------------------------------- | | `elements` | `ElementsGroup \| null` | The group the element components inside belong to. | | `pesepay` | `Pesepay \| null` | The loaded Pesepay instance. | # ElementsSlots > The slots `` takes. The slots `` takes. ```ts export type ElementsSlots = SlotsType<{ default?: (props: ElementsSlotProps) => VNode[]; }>; ``` # HostedCardElement > The card provider's form for Mastercard and Zimswitch. One per page. The card provider’s form for Mastercard and Zimswitch. One per page. ```ts HostedCardElement: ElementComponent<"hostedCard"> ``` # MobileElement > EcoCash or O'mari phone number, and O'mari's SMS code. EcoCash or O’mari phone number, and O’mari’s SMS code. ```ts MobileElement: ElementComponent<"mobile"> ``` # PaymentElement > Every method the transaction can be paid with. A new `referenceNumber` replaces the element. Every method the transaction can be paid with. A new `referenceNumber` replaces the element. ```ts PaymentElement: ElementComponent<"payment"> ``` # ScanElement > The InnBucks or PayGo code the customer scans. The InnBucks or PayGo code the customer scans. ```ts ScanElement: ElementComponent<"scan"> ``` # useElements > The elements group `` created. `null` while Pesepay loads and during server rendering. Read an element off it to pay with: `elements.value?.getElement("card")`. The elements group `` created. `null` while Pesepay loads and during server rendering. Read an element off it to pay with: `elements.value?.getElement("card")`. ```ts export declare function useElements(): Readonly>; ``` # usePesepay > The Pesepay instance `` was given. `null` while it loads and during server rendering. The Pesepay instance `` was given. `null` while it loads and during server rendering. ```ts export declare function usePesepay(): Readonly>; ```