Pesepay
What loadPesepay() resolves to.
export interface PesepayMethods
Section titled “Methods”cancelTransaction()
Section titled “cancelTransaction()”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.
| Parameter | Type |
|---|---|
referenceNumber | string |
options? | { signal?: AbortSignal; } |
confirmCardPayment()
Section titled “confirmCardPayment()”confirmCardPayment(referenceNumber: string, data: ConfirmCardPaymentData): Promise<ConfirmResult>;Pays with the card in a card element. See ConfirmCardPaymentData for 3-D Secure.
| Parameter | Type |
|---|---|
referenceNumber | string |
data | ConfirmCardPaymentData |
confirmHostedCardPayment()
Section titled “confirmHostedCardPayment()”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.
| Parameter | Type |
|---|---|
referenceNumber | string |
data | ConfirmHostedCardPaymentData |
confirmMobilePayment()
Section titled “confirmMobilePayment()”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.
| Parameter | Type |
|---|---|
referenceNumber | string |
data | ConfirmMobilePaymentData |
confirmPayment()
Section titled “confirmPayment()”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.
| Parameter | Type |
|---|---|
referenceNumber | string |
data | ConfirmPaymentData<E> |
confirmScanPayment()
Section titled “confirmScanPayment()”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.
| Parameter | Type |
|---|---|
referenceNumber | string |
data | ConfirmScanPaymentData |
elements()
Section titled “elements()”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 |
handleRedirectResult()
Section titled “handleRedirectResult()”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.
| Parameter | Type |
|---|---|
search? | string |
options? | HandleRedirectOptions |
listPaymentMethods()
Section titled “listPaymentMethods()”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.
| Parameter | Type |
|---|---|
referenceNumber | string |
options? | { signal?: AbortSignal; } |
retrieveTransaction()
Section titled “retrieveTransaction()”retrieveTransaction(referenceNumber: string, options?: { signal?: AbortSignal; }): Promise<ConfirmResult>;A single read, never a poll. waitForTransaction() is the one that waits.
| Parameter | Type |
|---|---|
referenceNumber | string |
options? | { signal?: AbortSignal; } |
selectPaymentMethod()
Section titled “selectPaymentMethod()”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.
| Parameter | Type |
|---|---|
referenceNumber | string |
paymentMethodCode | string |
options? | { signal?: AbortSignal; } |
startCardCheckout()
Section titled “startCardCheckout()”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.
| Parameter | Type |
|---|---|
referenceNumber | string |
paymentMethodCode | string |
options? | { signal?: AbortSignal; } |
syncCardCheckout()
Section titled “syncCardCheckout()”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().
| Parameter | Type |
|---|---|
referenceNumber | string |
options? | { signal?: AbortSignal; } |
waitForTransaction()
Section titled “waitForTransaction()”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.
| Parameter | Type |
|---|---|
referenceNumber | string |
options? | WaitForTransactionOptions |