Skip to content

Checkout events

Checkout events tell your page where a customer is in checkout while it is open, and why it closed. There are two: checkout.stage_changed and checkout.closed. They are sent to the listeners you register with .on() on the Unified SDK.

Client events are best effort. For the authoritative state of a payment, use payment webhooks. For how far the customer got, use the payment's progress field.

Availability

Checkoutcheckout.stage_changedcheckout.closed payload
LRS order opened with orderId on the Unified SDKSentv1 payload (this page)
LRS order opened with the legacy LRS SDK (LrsCheckoutApi)Sentv1 payload (this page)
LRS payment session (paymentSessionId)Not sent{}
Standard checkout (orders, subscriptions)Not sent{}
Flutter, React Native, Android and iOS SDKsNot exposed yetNot exposed yet

The events are enabled per merchant and are off by default. To turn them on, contact your Glomo account manager. The same switch also adds progress to the payment webhook and API, so you do not need to ask twice.

To check whether the events are on for your account, look at the checkout.closed payload. It contains v: 1 when they are on, and is {} when they are off. It is also {} when checkout fails before it finishes loading, so a single {} does not prove the events are off.

Quick start

Register listeners before you call open(). A listener registered later misses the events that were already sent.

const checkout = new GlomoCheckoutApi({
  publicKey: 'live_XXXX',
  orderId: 'order_XXXX',
});

checkout.on('checkout.stage_changed', function (event) {
  // event.stage is one of the payment stages below; event.step narrows it down
  analytics.track('checkout_stage', {
    orderId: event.resource.id,
    journeyId: event.journeyId,
    stage: event.stage,
    step: event.step,
  });
});

checkout.on('checkout.closed', function (event) {
  if (event.v !== 1) return; // events off for this account, or checkout failed before loading: the payload is {}
  if (event.reason === 'completed') return; // the payment journey finished; wait for the webhook
  analytics.track('checkout_abandoned', {
    lastStage: event.lastStage,
    reason: event.reason,
  });
});

await checkout.open();

checkout.stage_changed

Sent when the customer reaches a new payment stage, or a new step within the current stage.

  • Sent at most once for each stage and step pair in one checkout open.
  • stage never goes backwards within one checkout open. A stage reached after a later stage is not sent, so stages can be skipped.
  • Retries are not reported. For example, a second OTP attempt sends nothing.

Fields

FieldTypeRequiredValuesDescription
vintegerYes1Payload version. See Versioning and compatibility.
flowstringYespayment. kyc is reserved.What the checkout is for. stage is a stage of this flow. Only payment is sent today.
methodstringNoKnown: lrs. New values can be added.The payment method.
resource.typestringYesorder, kyc, sessionThe kind of object the checkout was opened for. order for an LRS order.
resource.idstringYesFor example order_XXXXThe ID of that object.
paymentIdstringNoFor example payt_XXXXThe payment attempt. Present from the attempt_created stage onward.
journeyIdstringYesOpaqueIdentifies one checkout open. Every event from the same open carries the same value. A new open() gets a new value.
stagestringYesKnown values in Payment stagesThe stage the customer reached. New stages can be added.
stepstringNoKnown values in StepsThe screen within the stage. Absent when the stage has no steps. New steps can be added.
providerstringNoKnown (LRS): HDFC, IDFC, ICICI, AXIS, KOTAKThe provider the customer chose. For LRS, the bank. Present from method_selected onward. Absent for a provider not in the known list. New values can be added.
journeyTypestringNoredirect, nativeredirect: the customer approves on the provider's page. native: the whole authentication happens inside checkout. Present from method_selected onward.
errorCodestringNoOpen stringOnly on stage: failed, and not always present there. A Glomo payment error code or a checkout error code, for example BANK_DECLINED.
segment.indexintegerNo1 or moreReserved. Not sent today. See Reserved.
segment.totalintegerNo1 or more, at least segment.indexReserved. Not sent today.
atstringYesISO 8601 date-time, UTC, millisecondsWhen checkout sent the event, from the customer's device clock. Do not use it to order events across devices.

These are the checkout error codes errorCode can carry:

errorCodeMeaning
PAYMENT_INITIATION_FAILEDCheckout could not create the payment or start it with the bank.
BANK_REDIRECT_UNAVAILABLECheckout had no bank page to send the customer to.
BANK_CONNECTION_FAILEDCheckout could not reach the bank, or could not open the bank's page.
DOCUMENT_UPLOAD_FAILEDThe customer's document could not be uploaded.

Any other value is the error code of the payment or of the bank step that failed. See Error Codes. New values can be added.

Examples

First event of a checkout open where the consent screen is shown:

{
  "v": 1,
  "flow": "payment",
  "method": "lrs",
  "resource": { "type": "order", "id": "order_6f1c2a9b7XyZ1" },
  "journeyId": "a3f1c9e2-5b7d-4e8a-9c21-0f6b2d4e8a17",
  "stage": "opened",
  "step": "consent",
  "at": "2026-11-16T09:30:12.418Z"
}

The customer is on the OTP screen after a payment attempt was created:

{
  "v": 1,
  "flow": "payment",
  "method": "lrs",
  "resource": { "type": "order", "id": "order_6f1c2a9b7XyZ1" },
  "paymentId": "payt_6f1c2b04QmR8s",
  "journeyId": "a3f1c9e2-5b7d-4e8a-9c21-0f6b2d4e8a17",
  "stage": "customer_auth",
  "step": "otp",
  "provider": "HDFC",
  "journeyType": "native",
  "at": "2026-11-16T09:31:40.077Z"
}

The payment failed:

{
  "v": 1,
  "flow": "payment",
  "method": "lrs",
  "resource": { "type": "order", "id": "order_6f1c2a9b7XyZ1" },
  "paymentId": "payt_6f1c2b04QmR8s",
  "journeyId": "a3f1c9e2-5b7d-4e8a-9c21-0f6b2d4e8a17",
  "stage": "failed",
  "provider": "HDFC",
  "journeyType": "native",
  "errorCode": "BANK_DECLINED",
  "at": "2026-11-16T09:33:02.511Z"
}

checkout.closed

Sent once when checkout closes itself: when the customer closes it, when the customer cancels, after an error, and after the payment journey finishes.

It is not sent when:

  • your code calls close();
  • the customer closes the SDK's own loading or configuration-error screen;
  • a callbackUrl redirect takes the customer away from your page;
  • the customer closes the browser tab.

Closed event fields

FieldTypeRequiredValuesDescription
vintegerYes1Payload version.
flowstringYespayment. kyc is reserved.As on checkout.stage_changed.
methodstringNoKnown: lrs. New values can be added.As on checkout.stage_changed.
resource.typestringYesorder, kyc, sessionAs on checkout.stage_changed.
resource.idstringYesFor example order_XXXXAs on checkout.stage_changed.
paymentIdstringNoFor example payt_XXXXPresent when a payment attempt was created before checkout closed.
journeyIdstringYesOpaqueSame value as the checkout.stage_changed events from this checkout open.
lastStagestringNoKnown values in Payment stagesThe last stage sent in this checkout open. Absent if none was sent.
lastStepstringNoKnown values in StepsThe step sent with lastStage, when there was one.
reasonstringYesKnown values in Close reasonsWhy checkout closed. New reasons can be added.
atstringYesISO 8601 date-time, UTC, millisecondsWhen checkout closed, from the customer's device clock.

Close reasons

These are all the close reasons sent today. New reasons can be added within v1, so do not fail on a reason you do not recognise.

reasonWhen it is sent
completedThe customer closed checkout after the payment journey finished. Wait for the payment webhook for the outcome.
user_cancelledThe customer chose to leave and confirmed it, for example in the exit prompt or by declining consent. Closing does not cancel a payment attempt that was already created: read the payment status.
user_dismissedThe customer closed checkout from a screen that closes without a confirmation prompt, for example while waiting for the bank.
errorCheckout closed from its error screen, or after an error it could not recover from.
confirmation_timeoutCheckout stopped waiting for the provider to confirm the payment. The payment can still complete. Wait for the payment webhook.

Closed event example

{
  "v": 1,
  "flow": "payment",
  "method": "lrs",
  "resource": { "type": "order", "id": "order_6f1c2a9b7XyZ1" },
  "paymentId": "payt_6f1c2b04QmR8s",
  "journeyId": "a3f1c9e2-5b7d-4e8a-9c21-0f6b2d4e8a17",
  "lastStage": "customer_auth",
  "lastStep": "otp",
  "reason": "user_cancelled",
  "at": "2026-11-16T09:32:15.902Z"
}

Payload when the events are not enabled

Until checkout events are enabled for your account, and for the checkouts marked {} in Availability, checkout.closed is still sent and your listener receives an empty object, {}. Write your listener so that it works with both shapes.

Payment stages

Stages of flow: payment, in the order a customer reaches them:

opened -> method_selected -> details_submitted -> attempt_created -> customer_auth
       -> provider_handoff -> awaiting_confirmation -> confirmed
                                                    \-> failed  (can follow any stage)

These are all the stages sent today. New stages can be added within v1, so ignore a stage you do not recognise. Not every customer passes through every stage.

OrderstageMeaningSteps
1openedCheckout is showing its first screen.consent, bank_list, or none
2method_selectedThe customer chose how to pay. For LRS, the bank. provider and journeyType are set from here on.none
3details_submittedThe customer submitted their details and moved on to pay.none
4attempt_createdGlomo created a payment attempt. paymentId is set from here on.none
5customer_authThe customer is authenticating inside checkout.otp, document_upload, txn_summary, agreements
6provider_handoffThe customer was sent to the provider's page to approve the payment. Sent only for journeys with a provider page.none
7awaiting_confirmationCheckout is waiting for the provider to confirm the payment.none
8confirmedThe provider confirmed the payment. payment.success follows.none
9failedThe payment failed. errorCode may say why. Not sent when the customer cancels or when confirmation times out. Those appear only as the checkout.closed reason.none

Steps

These are all the steps sent today. New steps can be added within v1, so ignore a step you do not recognise.

stagestepScreen
openedconsentThe customer is asked for consent.
openedbank_listThe customer is choosing a bank.
customer_authotpOne-time password from the bank.
customer_authdocument_uploadThe customer uploads a document the bank asks for.
customer_authtxn_summaryThe customer reviews the transaction summary.
customer_authagreementsThe customer accepts the bank's terms.

Delivery and ordering

  • Best effort. Events travel from the checkout frame to your page in the browser. They are not retried or replayed, and they stop when the customer closes the tab or leaves the page.
  • Once. Each stage and step pair is sent at most once per journeyId. checkout.closed is sent at most once per journeyId.
  • In order, within one event name. checkout.stage_changed events for one journeyId arrive in stage order. Do not rely on ordering between different event names, for example checkout.stage_changed and payment.failure.
  • Deduplicate on journeyId + stage + step if you forward events to your server.
  • Isolated listeners. An exception thrown in one listener does not stop the others.
  • callbackUrl. With a callbackUrl, checkout.stage_changed and checkout.closed still reach your .on() listeners. The redirect on payment.success or payment.failure usually leaves your page before checkout.closed is sent.
  • Authoritative state comes from payment webhooks, never from client events.

Versioning and compatibility

  • v is the payload version. It is 1 for every payload described here.
  • Within v1, changes are additive only: new optional fields, new stages, new steps, new close reasons, and new values for method, provider and errorCode. The tables on this page list every value sent today.
  • A change that removes or renames a field, or changes the meaning of a value, ships as v: 2 alongside v1. It does not replace v1 in place.
  • Your code must ignore fields and values it does not recognise. It must not fail on them.

JSON Schema

The JSON Schema (draft-07) for the v1 payloads is at https://docs.glomo.one/schemas/checkout-events/v1.json. It has one definition per event: CheckoutStageChanged and CheckoutClosed.

stage, lastStage and reason are open strings in the schema, so values added within v1 still validate. Each field's description lists the values known today.

Relation to payment outcomes and webhooks

SignalWhereSignedUse it for
payment.success, payment.failureBrowser, .on() or callbackUrlpayment.success isShowing the result to the customer. Verify the signature on your server.
checkout.stage_changedBrowser, .on()NoLive progress and drop-off analytics.
checkout.closedBrowser, .on()NoKnowing that checkout closed, where the customer was, and why.
Payment webhook, including progressYour serverYesThe authoritative status, and the last stage recorded by Glomo, even when the page never received client events.

Client events use camelCase. The server uses snake_case under progress:

Client (checkout.closed)Server (progress)
lastStageprogress.last_stage
lastStepprogress.last_step
atprogress.at

The stage values are the same strings. The server records a subset of the stages. See Payment progress.

Reserved

These are defined in v1 but not sent today. Do not build on them yet.

  • flow: kyc with stages opened, in_progress, submitted, under_review, action_required, approved, rejected, expired, failed.
  • segment (index, total), for checkouts that run several parts in one session.