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.
| Checkout | checkout.stage_changed | checkout.closed payload |
|---|---|---|
LRS order opened with orderId on the Unified SDK | Sent | v1 payload (this page) |
LRS order opened with the legacy LRS SDK (LrsCheckoutApi) | Sent | v1 payload (this page) |
LRS payment session (paymentSessionId) | Not sent | {} |
| Standard checkout (orders, subscriptions) | Not sent | {} |
| Flutter, React Native, Android and iOS SDKs | Not exposed yet | Not 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.
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();Sent when the customer reaches a new payment stage, or a new step within the current stage.
- Sent at most once for each
stageandsteppair in one checkout open. stagenever 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.
| Field | Type | Required | Values | Description |
|---|---|---|---|---|
v | integer | Yes | 1 | Payload version. See Versioning and compatibility. |
flow | string | Yes | payment. kyc is reserved. | What the checkout is for. stage is a stage of this flow. Only payment is sent today. |
method | string | No | Known: lrs. New values can be added. | The payment method. |
resource.type | string | Yes | order, kyc, session | The kind of object the checkout was opened for. order for an LRS order. |
resource.id | string | Yes | For example order_XXXX | The ID of that object. |
paymentId | string | No | For example payt_XXXX | The payment attempt. Present from the attempt_created stage onward. |
journeyId | string | Yes | Opaque | Identifies one checkout open. Every event from the same open carries the same value. A new open() gets a new value. |
stage | string | Yes | Known values in Payment stages | The stage the customer reached. New stages can be added. |
step | string | No | Known values in Steps | The screen within the stage. Absent when the stage has no steps. New steps can be added. |
provider | string | No | Known (LRS): HDFC, IDFC, ICICI, AXIS, KOTAK | The 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. |
journeyType | string | No | redirect, native | redirect: the customer approves on the provider's page. native: the whole authentication happens inside checkout. Present from method_selected onward. |
errorCode | string | No | Open string | Only on stage: failed, and not always present there. A Glomo payment error code or a checkout error code, for example BANK_DECLINED. |
segment.index | integer | No | 1 or more | Reserved. Not sent today. See Reserved. |
segment.total | integer | No | 1 or more, at least segment.index | Reserved. Not sent today. |
at | string | Yes | ISO 8601 date-time, UTC, milliseconds | When 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:
errorCode | Meaning |
|---|---|
PAYMENT_INITIATION_FAILED | Checkout could not create the payment or start it with the bank. |
BANK_REDIRECT_UNAVAILABLE | Checkout had no bank page to send the customer to. |
BANK_CONNECTION_FAILED | Checkout could not reach the bank, or could not open the bank's page. |
DOCUMENT_UPLOAD_FAILED | The 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.
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"
}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
callbackUrlredirect takes the customer away from your page; - the customer closes the browser tab.
| Field | Type | Required | Values | Description |
|---|---|---|---|---|
v | integer | Yes | 1 | Payload version. |
flow | string | Yes | payment. kyc is reserved. | As on checkout.stage_changed. |
method | string | No | Known: lrs. New values can be added. | As on checkout.stage_changed. |
resource.type | string | Yes | order, kyc, session | As on checkout.stage_changed. |
resource.id | string | Yes | For example order_XXXX | As on checkout.stage_changed. |
paymentId | string | No | For example payt_XXXX | Present when a payment attempt was created before checkout closed. |
journeyId | string | Yes | Opaque | Same value as the checkout.stage_changed events from this checkout open. |
lastStage | string | No | Known values in Payment stages | The last stage sent in this checkout open. Absent if none was sent. |
lastStep | string | No | Known values in Steps | The step sent with lastStage, when there was one. |
reason | string | Yes | Known values in Close reasons | Why checkout closed. New reasons can be added. |
at | string | Yes | ISO 8601 date-time, UTC, milliseconds | When checkout closed, from the customer's device clock. |
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.
reason | When it is sent |
|---|---|
completed | The customer closed checkout after the payment journey finished. Wait for the payment webhook for the outcome. |
user_cancelled | The 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_dismissed | The customer closed checkout from a screen that closes without a confirmation prompt, for example while waiting for the bank. |
error | Checkout closed from its error screen, or after an error it could not recover from. |
confirmation_timeout | Checkout stopped waiting for the provider to confirm the payment. The payment can still complete. Wait for the payment webhook. |
{
"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"
}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.
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.
| Order | stage | Meaning | Steps |
|---|---|---|---|
| 1 | opened | Checkout is showing its first screen. | consent, bank_list, or none |
| 2 | method_selected | The customer chose how to pay. For LRS, the bank. provider and journeyType are set from here on. | none |
| 3 | details_submitted | The customer submitted their details and moved on to pay. | none |
| 4 | attempt_created | Glomo created a payment attempt. paymentId is set from here on. | none |
| 5 | customer_auth | The customer is authenticating inside checkout. | otp, document_upload, txn_summary, agreements |
| 6 | provider_handoff | The customer was sent to the provider's page to approve the payment. Sent only for journeys with a provider page. | none |
| 7 | awaiting_confirmation | Checkout is waiting for the provider to confirm the payment. | none |
| 8 | confirmed | The provider confirmed the payment. payment.success follows. | none |
| 9 | failed | The 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 |
These are all the steps sent today. New steps can be added within v1, so ignore a step you do not recognise.
stage | step | Screen |
|---|---|---|
opened | consent | The customer is asked for consent. |
opened | bank_list | The customer is choosing a bank. |
customer_auth | otp | One-time password from the bank. |
customer_auth | document_upload | The customer uploads a document the bank asks for. |
customer_auth | txn_summary | The customer reviews the transaction summary. |
customer_auth | agreements | The customer accepts the bank's terms. |
- 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
stageandsteppair is sent at most once perjourneyId.checkout.closedis sent at most once perjourneyId. - In order, within one event name.
checkout.stage_changedevents for onejourneyIdarrive in stage order. Do not rely on ordering between different event names, for examplecheckout.stage_changedandpayment.failure. - Deduplicate on
journeyId+stage+stepif you forward events to your server. - Isolated listeners. An exception thrown in one listener does not stop the others.
callbackUrl. With acallbackUrl,checkout.stage_changedandcheckout.closedstill reach your.on()listeners. The redirect onpayment.successorpayment.failureusually leaves your page beforecheckout.closedis sent.- Authoritative state comes from payment webhooks, never from client events.
vis the payload version. It is1for 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,provideranderrorCode. 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: 2alongside 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.
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.
| Signal | Where | Signed | Use it for |
|---|---|---|---|
payment.success, payment.failure | Browser, .on() or callbackUrl | payment.success is | Showing the result to the customer. Verify the signature on your server. |
checkout.stage_changed | Browser, .on() | No | Live progress and drop-off analytics. |
checkout.closed | Browser, .on() | No | Knowing that checkout closed, where the customer was, and why. |
Payment webhook, including progress | Your server | Yes | The 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) |
|---|---|
lastStage | progress.last_stage |
lastStep | progress.last_step |
at | progress.at |
The stage values are the same strings. The server records a subset of the stages. See Payment progress.
These are defined in v1 but not sent today. Do not build on them yet.
flow: kycwith stagesopened,in_progress,submitted,under_review,action_required,approved,rejected,expired,failed.segment(index,total), for checkouts that run several parts in one session.