Skip to main content

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.
It 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

  1. On a successful payment, once the payment is recognised as LRS — its purpose code decides this.
  2. 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.
  3. 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.
  4. 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 a webhook URL configured
  • 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

Delivery: batched, up to about 2 minutes. See Delivery and duplicates.

Headers

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. Both signature headers are sent. Verify V2 (recommended) or V1 — see Verifying webhooks.

Payload Schema

The payment, its state, and every item it still owes and why.
The three travel codes carry identical checklists. A travel checklist owes no documents, and lists persons only when your account collects traveller details. The last tab is the same payment as the first, later in its life. The buyer, invoice, remitter and persons fields dropped off because sending them satisfied them, and a PAYING_FOR_SOMEONE_ELSE item appeared, because listing a person other than the remitter in persons makes relationship_declaration owed.

Field Specifications

string
required
Always "LRS_VERIFICATION_NEEDED" for this webhook event
string
required
UTC, no timezone suffix, e.g. "2026-08-14T10:30:00.123456". Parse tolerantly — fractional seconds can be absent.
string
required
API version of your account, e.g. "3.0.0"
string
required
Unique ID of this event (a UUID, not an ordering counter). A retry resends the same value; use it to de-duplicate.Example: "550e8400-e29b-41d4-a716-446655440000"
object
required
The payment, its state, and what it owes

This event lists only what is outstanding. Optional items, conditional items whose condition does not hold, and anything already supplied never appear. For the whole set, 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 is checked: the remitter’s PAN against the name and date of birth, the credit’s sender against the account holder, the TCS, and that the money received covers what is being settled. Any of those can refuse. A refusal arrives as this same event, with the same envelope and keys. Only the message and the entries differ.
The payment stays in Action Required and you can submit again. Everything you sent is still held against it: fix what is named and re-send only that, since a partial send is merged with what is already there. There is no separate outstanding or reason key. The shortfall’s rupee figure is in the outstanding entry’s message, a PAN mismatch in remitter_pan’s, and so on. Read the two lists the same way as for the requirement event.

The codes a refusal names

Each refusal is reported under the code you collected it under, so a fix goes back through the same endpoint and key: outstanding is a conclusion, not a code: there is nothing to re-send under that name. The credit is short by the amount its message states. The buyer tops up; link the top-up with top_up.

When a review sends it back

A filed verification is reviewed by EximPe, 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
The requirement flags are unchanged and sit alongside the new keys — an entry that is both conditional and rejected carries both:
An entry’s message is still the document’s label; rejection_reason is what went wrong with that file. Show the label to say what you are asking for, and the rejection reason to say why you are asking again.
A send-back can list 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:
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. On the education codes, listing a person other than the remitter in persons brings in relationship_declaration, so it can arrive in an event after you thought you had the full list. It 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

1

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.
2

Upload the files

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

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.
4

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.