Handle outcomes

Programmatic API

const { open, close } = useSuqoCheckout()

open({
  sessionId: 'cks_9f2c41a8',
  onSuccess: (result) => {},  // { sessionId, params, message? }
  onFailure: (result) => {},  // { sessionId, status: 'failed' | 'cancelled', params, message? }
  onClose:   () => {},
}) // => Promise<SuqoOutcome>

close() // dismisses the sheet as though the buyer closed it — a no-op if nothing is open

close() settles the open session as { result: 'closed' }, the same outcome a buyer gets from the back button or a hardware back press — so a caller that drives both open() and close() sees one consistent shape regardless of who ended the sheet.

A result that arrives from the page after you call close() (the buyer dismissed, but the page had already verified the payment with the backend a frame later) still wins: a verified result always beats an earlier dismissal, because telling the app "nothing happened" while the buyer's money moved would be the one actionable lie this SDK could tell. Only one outcome is ever delivered either way.

cancelled is not failed

onFailure receives status: 'cancelled' when the buyer backed out at the gateway, and 'failed' when a payment was attempted and rejected. Check it: a buyer who changed their mind wants the basket offered again, while a rejected payment is worth looking into. Nothing is charged in either case.

params is the gateway's, verbatim

Every gateway names its transaction differently — eSewa a signed data blob, Khalti a pidx, ConnectIPS a TXNID, NPS a MerchantTxnId. params is passed through with no renaming or filtering, because you reconcile against whatever your own backend recorded, and normalising would throw away the only field you can match on.

message is what SUQO's backend said when it settled the payment — a field on the result object (result.message), kept apart from params so SUQO's keys never mix into the gateway's. It is undefined when the backend said nothing, so it is never copy this SDK invented; on a failure it is usually the only place the reason exists.

The outcome is a signal to navigate, not proof of fulfilment

onSuccess fires only after the checkout page verified the payment with SUQO's backend, so it is a real signal rather than a redirect's claim. Even so, the webhook is authoritative. Treat onSuccess as "move the buyer on", and let your own backend decide an order is paid from its own record. See Receive webhook events.