Events
What the SDK tells your page, and when.
The SDK surfaces two callbacks. Under the hood they are driven by postMessage events from the hosted flow; if you use the direct iframe path you will handle those messages yourself.
onComplete(sale)
Fires exactly once, when Stripe reports the checkout paid. Certificates are issued shortly after; confirm them server-side before you rely on the sale. Amounts are in cents (amountTotalCents); amountTotal is a deprecated alias with the same cents value, kept for SDK 0.1.x code. Neither is ever sent as 0 when the amount is unknown: it is null. The modal stays open on the confirmation screen; the buyer closes it when they are done, and onClose does not fire afterwards.
coverport.mount('#insure-btn', {
key: 'pk_live_…',
onComplete: async (sale) => {
await fetch('/api/insurance/record', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
purchaseId: sale.purchaseId, // Stripe PaymentIntent id, pi_…
checkoutSessionId: sale.checkoutSessionId, // cs_…
amountTotalCents: sale.amountTotalCents, // cents: 12500 is $125.00; null if unknown
currency: sale.currency,
testMode: sale.testMode,
shipmentId: currentShipment.id, // your own correlation id
}),
});
},
});Client events are a signal, not the source of truth
onComplete runs in the buyer's browser and can be lost if the tab closes, and anyone can call your record endpoint with made-up values. Treat it as a hint to update your UI and to record a correlation id. Before you rely on a sale for billing or fulfilment, confirm it from your server: GET /api/purchases?paymentIntentId=<sale.purchaseId> returns the purchase once its certificates are issued. See Purchases and certificates.
onClose()
Fires when the modal is dismissed without a completed sale. Any of these trigger it:
- The close button in the corner of the modal
- A click on the backdrop
- The Escape key
- The hosted flow sending a
closemessage (for example, a "No thanks" action inside the flow) handle.destroy()while a modal is open
Use it to resume whatever the buyer was doing, or to log abandonment.
Ordering guarantees
| Scenario | Callbacks |
|---|---|
| Buyer completes purchase, then closes modal | onComplete only |
| Buyer closes modal before paying | onClose only |
open() called while a modal is showing | Old modal is removed silently, no onClose; new modal opens |
destroy() on a handle with an open modal | onClose (unless a sale had already completed) |