Skip to content

Pesepay

What loadPesepay() resolves to.

export interface Pesepay
cancelTransaction(referenceNumber: string, options?: {
signal?: AbortSignal;
}): Promise<ConfirmResult>;

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.

ParameterType
referenceNumberstring
options?{ signal?: AbortSignal; }
confirmCardPayment(referenceNumber: string, data: ConfirmCardPaymentData): Promise<ConfirmResult>;

Pays with the card in a card element. See ConfirmCardPaymentData for 3-D Secure.

ParameterType
referenceNumberstring
dataConfirmCardPaymentData
confirmHostedCardPayment(referenceNumber: string, data: ConfirmHostedCardPaymentData): Promise<ConfirmResult>;

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() finishes the job. A transaction that has already finished comes back as it is, unsent.

ParameterType
referenceNumberstring
dataConfirmHostedCardPaymentData
confirmMobilePayment(referenceNumber: string, data: ConfirmMobilePaymentData): Promise<ConfirmResult>;

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.

ParameterType
referenceNumberstring
dataConfirmMobilePaymentData
confirmPayment<E extends ConfirmableElement>(referenceNumber: string, data: ConfirmPaymentData<E>): Promise<ConfirmResult>;

Pays with any element, by calling the confirm method for its type: confirmCardPayment(), confirmMobilePayment(), confirmScanPayment() or 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.

ParameterType
referenceNumberstring
dataConfirmPaymentData<E>
confirmScanPayment(referenceNumber: string, data: ConfirmScanPaymentData): Promise<ConfirmResult>;

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(). Returns scan_code_unavailable if the provider sent no code.

ParameterType
referenceNumberstring
dataConfirmScanPaymentData
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.

ParameterType
options?ElementsOptions
handleRedirectResult(search?: string, options?: HandleRedirectOptions): Promise<ConfirmResult>;

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.

ParameterType
search?string
options?HandleRedirectOptions
listPaymentMethods(referenceNumber: string, options?: {
signal?: AbortSignal;
}): Promise<PaymentMethodsResult>;

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.

ParameterType
referenceNumberstring
options?{ signal?: AbortSignal; }
retrieveTransaction(referenceNumber: string, options?: {
signal?: AbortSignal;
}): Promise<ConfirmResult>;

A single read, never a poll. waitForTransaction() is the one that waits.

ParameterType
referenceNumberstring
options?{ signal?: AbortSignal; }
selectPaymentMethod(referenceNumber: string, paymentMethodCode: string, options?: {
signal?: AbortSignal;
}): Promise<SelectPaymentMethodResult>;

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.

ParameterType
referenceNumberstring
paymentMethodCodestring
options?{ signal?: AbortSignal; }
startCardCheckout(referenceNumber: string, paymentMethodCode: string, options?: {
signal?: AbortSignal;
}): Promise<ConfirmResult>;

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.

ParameterType
referenceNumberstring
paymentMethodCodestring
options?{ signal?: AbortSignal; }
syncCardCheckout(referenceNumber: string, options?: {
signal?: AbortSignal;
}): Promise<ConfirmResult>;

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().

ParameterType
referenceNumberstring
options?{ signal?: AbortSignal; }
waitForTransaction(referenceNumber: string, options?: WaitForTransactionOptions): Promise<ConfirmResult>;

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.

ParameterType
referenceNumberstring
options?WaitForTransactionOptions