LRS VERIFICATION NEEDED

Event Overview

Event Type: LRS_VERIFICATION_NEEDED Category: 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 its checklist calls for. 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 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 S0303, S0304 and S0306 (travel). What it names differs per code; see Get Verification Requirements for the whole set.

When the webhook is sent

On a successful payment, once the payment is recognised as LRS — its purpose code decides this.
After you declare a purpose code, if it was not known earlier. A 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, same shape, the problem folded into the relevant entry’s message — see After a submit that did not pass.
When a filed verification is sent back for changes. A review can return a verification rather than decide it — a document is the wrong one, a field needs correcting. The payment owes something again, so it is this event that carries the ask, with the reviewer’s comment in the top-level message — see When a review sends it back. A review that decides the verification raises VERIFICATION_STATUS instead.

The webhook is created only if:

Your merchant account (or parent, for sub-merchants) has an active API credential with a non-empty webhook URL
The payment is actually owed something — a payment with everything already supplied gets no event at all. Silence is the “nothing owed” signal.

Delivery Details

Attribute	Value
HTTP method	`POST`
URL	The webhook URL configured on your merchant account’s API credentials
Content-Type	`application/json`
Timeout	10 seconds
Retries	Up to 5 delivery attempts (backoff: 1 min, 5 min, 15 min, 60 min)
Pacing	Delivered on a per-merchant rate-capped queue, so a burst of payments arrives smoothly rather than all at once

Headers

Header	Description
`Content-Type`	`application/json`
`User-Agent`	`Eximpe-Webhook/1.0`
`X-Webhook-Event`	`LRS_VERIFICATION_NEEDED`
`X-Webhook-Timestamp`	Unix timestamp (string) at the time of the request
`X-Webhook-Signature`	`HMAC-SHA256(encryption_key, raw_body)`, hex-encoded
`X-Webhook-Signature-V2`	`t=<timestamp>,v2=<hex>` where the digest is `HMAC-SHA256(encryption_key, "<timestamp>." + raw_body)`

Verifying. The body is serialised once and those exact bytes are both sent and signed, so hashing the raw request body as received is correct — do not re-serialise the parsed JSON first. Prefer V2: the timestamp is inside the signed material, so a captured delivery cannot be replayed with a fresh one. V1 stays alongside it so nobody has to migrate on our schedule.

Payload Schema

The payment, its state, and every item it still owes and why. These are complete, unedited payloads — nothing is trimmed.

{
  "event_type": "LRS_VERIFICATION_NEEDED",
  "event_time": "2026-08-14T10:30:00.123456",
  "version": "3.0.0",
  "sequence_number": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "payment_id": "PR6938527534",
    "order_id": "OD3376378679",
    "link_id": null,
    "verification_status": "ACTION_REQUIRED",
    "message": "LRS payment: verification details are required before settlement.",
    "action_required_fields": [
      { "code": "buyer_name", "message": "Buyer / remitter name" },
      { "code": "buyer_address_line_1", "message": "Buyer address line 1" },
      { "code": "buyer_city", "message": "Buyer city" },
      { "code": "buyer_state", "message": "Buyer state" },
      { "code": "buyer_postal_code", "message": "Buyer PIN code" },
      { "code": "buyer_email", "message": "Buyer email" },
      { "code": "buyer_phone", "message": "Buyer phone" },
      { "code": "invoice_number", "message": "Invoice number" },
      { "code": "invoice_date", "message": "Invoice date" },
      { "code": "remitter_pan", "message": "Remitter PAN" },
      { "code": "remitter_dob", "message": "Remitter date of birth (as per PAN)" },
      { "code": "remitter_relation", "message": "Remitter's relation to the person the remittance is for" },
      { "code": "buyer_declaration", "message": "The LRS declaration the payer affirms: resident in India, within the LRS limit, permitted purpose" },
      { "code": "amount_to_be_settled", "message": "Amount to be settled for this payment, in INR" }
    ],
    "payment_verification_expiry": null,
    "action_required_documents": [
      { "code": "offer_letter", "message": "Letter of admission from the institution" },
      { "code": "passport", "message": "Student's passport" },
      { "code": "student_id_or_visa", "message": "Student visa or university ID card (either)" }
    ]
  }
}

{
  "event_type": "LRS_VERIFICATION_NEEDED",
  "event_time": "2026-08-14T10:31:12.884210",
  "version": "3.0.0",
  "sequence_number": "550e8400-e29b-41d4-a716-446655440001",
  "data": {
    "payment_id": "PR8125440971",
    "order_id": "OD5590284413",
    "link_id": null,
    "verification_status": "ACTION_REQUIRED",
    "message": "LRS payment: verification details are required before settlement.",
    "action_required_fields": ["… the same sixteen field entries as S0305 …"],
    "payment_verification_expiry": null,
    "action_required_documents": [
      { "code": "offer_letter", "message": "Letter of admission from the institution" },
      { "code": "student_id", "message": "University ID card" }
    ]
  }
}

{
  "event_type": "LRS_VERIFICATION_NEEDED",
  "event_time": "2026-08-14T10:32:41.005917",
  "version": "3.0.0",
  "sequence_number": "550e8400-e29b-41d4-a716-446655440002",
  "data": {
    "payment_id": "PR7042318866",
    "order_id": "OD8451220934",
    "link_id": null,
    "verification_status": "ACTION_REQUIRED",
    "message": "LRS payment: verification details are required before settlement.",
    "action_required_fields": ["… the same sixteen field entries as S0305 …"],
    "payment_verification_expiry": null,
    "action_required_documents": [
      { "code": "passenger_list", "message": "Passenger list — name and passport number of every traveller" },
      { "code": "traveller_passports", "message": "Passports of all travellers" },
      { "code": "traveller_visas", "message": "Visas of all travellers", "waivable": true },
      { "code": "ticket", "message": "Travel tickets", "waivable": true },
      { "code": "invoice", "message": "Invoice for the trip" }
    ]
  }
}

{
  "event_type": "LRS_VERIFICATION_NEEDED",
  "event_time": "2026-08-14T11:02:19.730558",
  "version": "3.0.0",
  "sequence_number": "550e8400-e29b-41d4-a716-446655440005",
  "data": {
    "payment_id": "PR6938527534",
    "order_id": "OD3376378679",
    "link_id": null,
    "verification_status": "ACTION_REQUIRED",
    "message": "LRS payment: verification details are required before settlement.",
    "action_required_fields": [
      { "code": "amount_to_be_settled", "message": "Amount to be settled for this payment, in INR" },
      { "code": "student_name", "message": "Name of the student the remittance is for", "condition": "PAYING_FOR_SOMEONE_ELSE" },
      { "code": "student_dob", "message": "Date of birth of the student the remittance is for", "condition": "PAYING_FOR_SOMEONE_ELSE" },
      { "code": "student_passport_number", "message": "Passport number of the student the remittance is for", "condition": "PAYING_FOR_SOMEONE_ELSE" }
    ],
    "payment_verification_expiry": null,
    "action_required_documents": [
      { "code": "relationship_declaration", "message": "Self-declaration of the remitter's relationship to the person the remittance is for", "condition": "PAYING_FOR_SOMEONE_ELSE" },
      { "code": "offer_letter", "message": "Letter of admission from the institution" }
    ]
  }
}

The three travel codes carry identical checklists. They differ in what the remittance is for, not in what you must collect.The last tab is the same payment as the first, later in its life. Two things changed: the buyer, invoice and remitter fields dropped off, because declaring them satisfied them; and four PAYING_FOR_SOMEONE_ELSE items appeared, because declaring remitter_relation as PARENT is what makes them owed.

Field Specifications

Root Level Fields
Data Object Fields
Entries

string

required

Always "LRS_VERIFICATION_NEEDED" for this webhook event

string

required

ISO 8601 datetime when the webhook event was created, in UTC and without an offset suffix.Example: "2026-08-14T10:30:00.123456"

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, its state, and what it owes

string

required

UID of the payment. Use it in the verification endpoint’s path.

string

required

UID of the order the payment belongs to.

string | null

required

ID of the payment link the payment was made through — the link_id that Create Payment Link returned. null when the payment was not made through a payment link; the key is always present.

string

required

The payment’s own settlement state at the moment the event was raised — normally ACTION_REQUIRED, or INFO_PENDING earlier in the flow.It is read live rather than asserted, because this event is sent both when a payment first owes its details and when a submit was refused, and it must say what is true at that moment.

string

required

Human-readable summary. Safe to log and safe to show; not a value to branch on.It is a fixed sentence on two of the triggers, and a reviewer’s words on the third:

Trigger	What `message` holds
The requirement list	A fixed sentence: “LRS payment: verification details are required before settlement.”
A submit that did not pass	A fixed sentence: “LRS payment: verification did not pass…”
A review sending the verification back	The reviewer’s comment, verbatim.

Only the send-back carries a person’s words here. Render it to a payer if you like; parsing it is not something to build on.

array

required

The fields still owed. See Entries below.

array

required

The documents still owed. Same entry shape.

string | null

required

A gateway-set verification deadline where one exists. Always null on the LRS rails, which have no such clock.The key is sent regardless so the payload shape does not change under you depending on which rail a payment arrived through — VERIFICATION_NEEDED carries a real date here.

Every entry in both lists carries code and message. The rest appear only when they apply, so their absence is meaningful: no waivable key means the item cannot be waived.

string

required

The identifier, and the key you send the answer back under — as a key in fields, or as a document’s code.

string

required

A sentence about the item, safe to render to a payer.On the requirement list it describes what the item is. On a refusal the same key says what went wrong instead — one key, always the plainest thing there is to say about the item in that context.On a send-back it stays the item’s label; what went wrong with a particular document is in that entry’s rejection_reason.

boolean

Present, and always true, on documents you may discharge with a waiver_reason instead of a file — a visa the destination does not require, a ticket not yet issued.The item is still listed until you do; waivable describes how it may be discharged, not whether it is required.

string

Present on items that are owed only in a named case. PAYING_FOR_SOMEONE_ELSE means remitter_relation has been declared as something other than SELF.An item with this key was not on the earlier event and is not arbitrary — the key names what brought it in.

boolean

Reserved. Optional items never block completion, so they are never outstanding, so they never appear on this event. Read them from Get Verification Requirements, which lists the whole set.

string

A group name — items sharing one substitute for each other. No checklist uses it today; where two documents are interchangeable the checklist gives them a single code instead (student_id_or_visa).

Three more keys appear on documents that already have a file against them — so an entry can name both what is owed and what was last sent under that code. They are absent when no document row exists for the slot, which is the ordinary case the first time a payment is asked for something. They are also absent on a refusal, whatever is held: that payload is built without the stored document, so its entries carry only code and message alongside the item’s own flags.

string

The upload identifier Upload Document returned for the file currently held in this slot — the same ref you submitted, so it maps onto your own record of what you sent.

string

Where this one document stands: PENDING (not reviewed individually), VERIFIED (accepted) or REJECTED (refused — replace it).

string

The reviewer’s text about this document, present only when they left some. It is the sentence to show a payer when you ask for a replacement file; the top-level message is about the verification as a whole.

This event lists only what is outstanding. Optional items and conditional items whose condition does not hold never appear, and neither does anything already supplied. For the whole set — including optionals you could still offer a payer — call Get Verification Requirements, which returns the same entries plus satisfied and provided.

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 eight keys. Nothing is added: an LRS payment should learn what it owes in one vocabulary and one shape, whether the answer came from the checklist or from the checks that run after it. Only the message and the entries differ.

{
  "event_type": "LRS_VERIFICATION_NEEDED",
  "event_time": "2026-08-16T10:30:00.123456",
  "version": "3.0.0",
  "sequence_number": "550e8400-e29b-41d4-a716-446655440010",
  "data": {
    "payment_id": "PR4497584646",
    "order_id": "OD4646580935",
    "link_id": null,
    "verification_status": "ACTION_REQUIRED",
    "message": "LRS payment: verification did not pass. The payment stays in Action Required until what is listed below is resolved.",
    "action_required_fields": [
      {
        "code": "outstanding",
        "message": "The credit received does not cover this payment: ₹12500.00 is still short."
      }
    ],
    "payment_verification_expiry": null,
    "action_required_documents": []
  }
}

{
  "event_type": "LRS_VERIFICATION_NEEDED",
  "event_time": "2026-08-16T10:31:44.882013",
  "version": "3.0.0",
  "sequence_number": "550e8400-e29b-41d4-a716-446655440011",
  "data": {
    "payment_id": "PR4497584646",
    "order_id": "OD4646580935",
    "link_id": null,
    "verification_status": "ACTION_REQUIRED",
    "message": "LRS payment: verification did not pass. The payment stays in Action Required until what is listed below is resolved.",
    "action_required_fields": [
      {
        "code": "remitter_pan",
        "message": "The remitter's PAN could not be verified against the name and date of birth given. Check all three and re-send."
      }
    ],
    "payment_verification_expiry": null,
    "action_required_documents": []
  }
}

{
  "event_type": "LRS_VERIFICATION_NEEDED",
  "event_time": "2026-08-16T10:33:02.417755",
  "version": "3.0.0",
  "sequence_number": "550e8400-e29b-41d4-a716-446655440012",
  "data": {
    "payment_id": "PR4497584646",
    "order_id": "OD4646580935",
    "link_id": null,
    "verification_status": "ACTION_REQUIRED",
    "message": "LRS payment: verification did not pass. The payment stays in Action Required until what is listed below is resolved.",
    "action_required_fields": [
      {
        "code": "remitter_pan",
        "message": "The name on the credit received does not match the verified holder of the declared PAN. A third-party credit cannot settle on someone else's PAN — declare the actual account holder's PAN as the remitter."
      }
    ],
    "payment_verification_expiry": null,
    "action_required_documents": []
  }
}

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.

There is no separate outstanding or reason key to branch on. Whatever they used to say now lives inside the relevant entry’s message — the shortfall’s rupee figure inside the outstanding entry, a PAN mismatch inside remitter_pan, and so on. Read the two lists the same way you already do for the requirement event; a refusal names the same thing in the same place, never a second structure to learn.

The codes a refusal names

The gateway’s own vocabulary is translated into the codes you collected under, so a fix goes back through the same endpoint and the same key:

Code	What it means	What to do
`remitter_pan`	Either the PAN did not verify, or the name on the credit received does not match its verified holder.	Verify the PAN with Verify PAN, and declare the PAN of whoever actually holds the account the credit came from.
`buyer_declaration`	The declaration was not affirmed.	Re-send it once the payer has consented.
`student_name` · `primary_person_name`	The remitter is not the person the remittance is for, so that person has to be named.	Send that person’s name, date of birth and — where the code asks for it — passport number. Education codes name them under `student_`, travel codes under `primary_person_`.
`purpose_code`	The code is not one this account may use, or not one we recognise.	Declared on the order — use an enabled, recognised code.
A document code	Appears in `action_required_documents`.	Upload the file again and re-submit its `ref`.

outstanding is a conclusion, not a code. It is the one entry with nothing to re-send under that name: the credit is short by the amount its message states. Either the buyer tops up — link the top-up with linked_payment_id — or a smaller amount_to_be_settled is declared.

When a review sends it back

A filed verification is reviewed by us, and a review has three outcomes. Two of them are verdicts and arrive as VERIFICATION_STATUS. The third is a send-back: the reviewer returns the verification for changes rather than deciding it, the payment owes something again, and that arrives here — same event, same shape. One thing is particular to this trigger:

message carries the reviewer’s comment verbatim, in place of the fixed sentence the other two triggers use.

Document entries carry ref, doc_status and rejection_reason wherever a row is already stored for an outstanding slot, so an entry names both the requirement and the fate of what you last sent against it. That is true here and on the requirement list alike — the re-ask after a document was rejected reads the same way. Only a refusal never carries the three.

A review sends the verification back

{
  "event_type": "LRS_VERIFICATION_NEEDED",
  "event_time": "2026-09-09T12:18:35.204118",
  "version": "3.0.0",
  "sequence_number": "550e8400-e29b-41d4-a716-446655440020",
  "data": {
    "payment_id": "PR3910984669",
    "order_id": "OD2615044268",
    "link_id": null,
    "verification_status": "ACTION_REQUIRED",
    "message": "Please replace the admission letter and resubmit.",
    "action_required_fields": [],
    "payment_verification_expiry": null,
    "action_required_documents": [
      {
        "code": "offer_letter",
        "message": "Letter of admission from the institution",
        "ref": "6757940683",
        "doc_status": "REJECTED",
        "rejection_reason": "Letter is for the wrong intake term."
      }
    ]
  }
}

The requirement flags are unchanged and sit alongside the new keys — an entry that is both conditional and rejected carries both:

{
  "code": "relationship_declaration",
  "message": "Self-declaration of the remitter's relationship to the person the remittance is for",
  "condition": "PAYING_FOR_SOMEONE_ELSE",
  "ref": "4480912337",
  "doc_status": "REJECTED",
  "rejection_reason": "The declaration is unsigned."
}

message on an entry is still the document’s label. The new rejection_reason is what went wrong with that file; message goes on describing what the item is. Show the label to say what you are asking for, and the rejection reason to say why you are asking again.

A send-back is sent on every send-back, including one that lists nothing. A reviewer can return a verification with the whole instruction in their comment and no item marked outstanding. Both lists then arrive as [] and message carries everything there is to act on:

"message": "The invoice date and the admission letter disagree. Please check with the payer and resubmit.",
"action_required_fields": [],
"action_required_documents": []

Empty lists on this event do not mean nothing is owed — that signal is PAYMENT_UNDER_REVIEW, a different event_type. Route on event_type before you read the lists.

Conditionals can appear later

An item like the relationship self-declaration only shows up once its condition holds. Declaring remitter_relation as anything other than SELF brings in several items at once — the fields naming the person the money is for (student_* on the education codes, primary_person_* on the travel ones) and relationship_declaration — so they can arrive in an event after you thought you had the full list. Each carries 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 checklist asks for in total.

Responding to the event

Collect what the entries name

Show the payer each message. Everything in action_required_documents needs a file — or, where waivable is true, a reason instead.

Upload the files

Upload Document returns a ref per file, under the same code the entry names.

Send the fields and the refs

Submit Verification Details takes fields and document refs in one call. Partial sends are merged, so you can send as things arrive.

Read what is left

The response carries outstanding — the codes still owed after that write. When it is empty and status is in_review, the payment is with us.

Respond 2xx as soon as you have accepted the payload, so the delivery is not retried, and verify the signature before acting on it.

Do not hardcode the codes

The checklist 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.

Submit Verification Details

Send the answer back, under these same codes.

Get Verification Requirements

The whole set, on demand — for resuming or reconciling.

Upload Document

Turn a file into a ref.

PAYMENT_UNDER_REVIEW

The event that says nothing is owed any more.

VERIFICATION_STATUS

The verdict once a filed verification is reviewed.

Order

Payment

Merchant

Settlement

Refund

Subscriptions

Payment Links

Virtual Bank Accounts

LRS

B2B Services

Webhooks

LRS VERIFICATION NEEDED

Event Overview

When the webhook is sent

Delivery Details

Headers

Payload Schema

Field Specifications

After a submit that did not pass

The codes a refusal names

When a review sends it back

Conditionals can appear later

Responding to the event

Do not hardcode the codes

Submit Verification Details

Get Verification Requirements

Upload Document

PAYMENT_UNDER_REVIEW

VERIFICATION_STATUS

​Event Overview

​When the webhook is sent

​Delivery Details

​Headers

​Payload Schema

​Field Specifications

​After a submit that did not pass

​The codes a refusal names

​When a review sends it back

​Conditionals can appear later

​Responding to the event

​Do not hardcode the codes

​Related

Submit Verification Details

Get Verification Requirements

Upload Document

PAYMENT_UNDER_REVIEW

VERIFICATION_STATUS

Event Overview

When the webhook is sent

Delivery Details

Headers

Payload Schema

Field Specifications

After a submit that did not pass

The codes a refusal names

When a review sends it back

Conditionals can appear later

Responding to the event

Do not hardcode the codes

Related