Event Overview
Event Type:LRS_VERIFICATION_NEEDEDCategory: Payment Verification
Description: An LRS payment needs verification details before it can settle This webhook fires when a payment settling under an LRS purpose code is missing details required for its purpose code. Unlike the generic verification events, it names exactly which fields and documents are outstanding.
This event replaces the others for LRS payments. A payment that receives
LRS_VERIFICATION_NEEDED will not also receive PAYMENT_DETAILS_MISSING or VERIFICATION_NEEDED. Two events carrying different lists for the same outstanding work would leave you chasing both.Fires for all five LRS purpose codes —
S0305 and S1107 (education), and
S0306, S0304 and S0303 (travel). The codes it names differ per purpose
code; see Get Verification Requirements
for what each one asks for.When the webhook is sent
- On a successful payment, once the payment is recognised as LRS — its purpose code determines this.
- After you supply verification details, if the purpose code was not known earlier. A purpose code is often chosen at submission time, so a payment can only be recognised as LRS then; until it is, the generic events apply.
- When a complete set does not pass verification. Supplying everything the list named is not the end of it: the PAN still has to verify, the sender still has to match the account holder, and the credit still has to cover the amount. A payment that fails one of those comes back in this same event, with two extra keys — see After a submit that did not pass.
- Your merchant account (or parent, for sub-merchants) has an active API credential with a non-empty webhook URL
- The payment is actually missing something — a payment with everything already supplied gets no event
Delivery Details
Headers
Signature verification (recommended):
Compute
HMAC-SHA256(encryption_key, raw_body) where raw_body is the exact UTF-8 request body as received. Compare the hex result with the X-Webhook-Signature header to ensure the webhook is from the platform and unchanged.
Payload Schema
The payment, every item it still owes and why, and where to send them. These are complete, unedited payloads — one per LRS purpose code. Nothing is trimmed, so what you see is what arrives.The three travel codes —
S0306, S0304, S0303 — carry identical
requirement sets. They differ in what the remittance is for, not in what
you must collect.The last tab is the same payment as the first, after the payer declared a
remitter_relation other than SELF. Two things changed: the relationship
self-declaration appeared as CONDITIONALLY_REQUIRED, and the remitter
identity fields dropped off the list, because declaring them satisfied them.Field Specifications
- Root Level Fields
- Data Object Fields
- Entries
string
required
Always
"LRS_VERIFICATION_NEEDED" for this webhook eventstring
required
ISO 8601 datetime when the webhook event was createdExample:
"2026-08-14T10:30:00.123456Z"string
required
Envelope version (e.g. “3.0.0”)
string
required
Unique identifier for this webhook event (UUID), useful for idempotencyExample:
"550e8400-e29b-41d4-a716-446655440000"object
required
The payment, what it owes, and where to send it
Entries carry no label. A code, a sentence, and a waiver flag is all an
entry has. For the human-readable name of a code — and for the exact wording a
payer must be shown to affirm
buyer_declaration — call
Get Verification Requirements,
which returns the whole requirement set rather than just what is outstanding.After a submit that did not pass
Sending everything the list named is not the same as passing. Once a set is complete it goes to the verification gateway, which verifies the remitter’s PAN against the name and date of birth, matches the credit’s sender to the account holder, recomputes TCS and checks that the money received covers what is being settled. Any of those can refuse. A refusal arrives as this same event — same type, same envelope, the same twoaction_required_* lists — because an LRS payment should learn what it owes in
one vocabulary whether the answer came from the requirement matrix or from the
checks that run after it. The message differs, and there are two extra keys:
reason instead:
The payment stays in Action Required and stays submittable. Nothing is lost:
everything you sent is still held against the payment. Fix what is named and
re-send only that — a partial send is merged with what is already there.
outstanding
Present only when the credit does not cover the payment. action_required_fields
tells you that it is short, under amount_to_be_settled; this is by how much,
in rupees.
You have two ways to clear it, and they are genuinely different: have the buyer
transfer the shortfall (then link that credit as a top-up when you re-submit), or
declare a smaller amount_to_be_settled. The same figure comes back on the
submit response,
so you do not have to wait for this event to act on it.
reason
A single machine-readable conclusion, present where one exists. It is a headline,
not the whole story — read action_required_fields either way.
A shortfall carries no
reason. Nor does any other refusal that came out of
the full check rather than from one of the conclusions above — those carry
outstanding and the two lists and nothing else. reason appears only when a
single named conclusion is the whole story, so treat its absence as normal and
act on action_required_fields either way.The codes a refusal names
A refusal reports itself in the same codes the requirement matrix uses, so a fix goes back through the same endpoint and the same key you collected it under:
Two entries are conclusions rather than codes, and there is nothing to re-send
under that name:
Alternatives arrive merged
Where two documents satisfy each other, you get one entry, not two:Optionals are listed until you send them
An optional item — the fee invoice onS0305 — appears with the message
“Optional for this purpose code.” and stops appearing once you supply it.
It is listed because an optional document nobody is told about is one nobody
sends. It never blocks completion: a payment with only optionals outstanding is
complete.
Conditionals can appear later
An item like the relationship self-declaration only shows up once its condition holds. Declaringremitter_relation as anything other than SELF brings it in,
so it can arrive in an event after you thought you had the full list. Its
message names the condition, so the arrival is explicable rather than arbitrary.
The reverse also happens: answering the remitter identity fields removes them
from the next event. The list is what is outstanding, not what the purpose code
asks for in total — for that, call
Get Verification Requirements.
Responding to the event
1
Collect what the entries name
Show the payer each
message for why the item is needed. A code containing / is one obligation — ask for either half.2
POST it to the verification endpoint
POST /pg/lrs/payments/{payment_id}/verification/ — Submit Verification Details takes fields and files in one call. Partial sends are merged, so you can send as things arrive.3
Read what is left
The response carries
fields / documents after the write, each entry flagged satisfied. When nothing is left unsatisfied the payment is verified automatically.Answering one requirement can reveal another. Declaring
remitter_relation as anything other than SELF adds the relationship self-declaration, because that document is only owed in that case. Always read the response rather than assuming the original list was final.Do not hardcode the codes
The requirement set is configuration and is revised as the underlying regulatory matrix is — new purpose codes become supported, a document turns waivable, a field stops being needed. Drive your form from Get Verification Requirements, and a revision reaches your integration without a release on your side. Hardcode the codes and it will not.Related
Submit Verification Details
Send the answer back, fields and files in one call.
Get Verification Requirements
The same list, on demand — for resuming or reconciling.