ACTION_REQUIRED — we have the funds but not the paperwork. We tell you exactly what it needs, you send it, and the payment completes itself once nothing is outstanding.
New to the rules? Read LRS & Compliance first. This page is the API walk-through.
PSPs send
X-Merchant-ID on every call here, naming the sub-merchant the payment belongs to. LRS is always scoped to the sub-merchant, never the PSP.Do it in this order
Every settlement blocker comes from doing one of these out of order. The quote is the important one: it is how you learn what to ask the buyer for, and that figure is bigger than the amount you are owed. The first two calls happen before any money moves. After that it is one call, repeated until nothing is outstanding — partial sends merge, so send each thing as you get it rather than waiting for the full set. The dashed lookup is there when you need it, not on the way through.When it does not go straight through
The two calls before the money moves
Steps 1 and 2 are not part of the verification loop, and both are easy to skip.- Verify PAN — do it first. Nothing downstream works until the PAN passes, and you do not want to have chased documents by then.
- Quote LRS Amount — this is what tells you how much to collect. It returns
total_payable_inr: the amount to be settled, plus our fee, the GST on that fee, and any tax. Ask the buyer for that figure and the payment covers itself.
Send what you have
Two calls, and they are independent. Upload each document when you get it and keep theref it returns; then send the fields and those refs together as JSON. Both hang off the payment, so nothing has to be held back until the set is complete.
Uploading a document is multipart/form-data — a file and a type:
fields, documents, finalize — and what belongs inside is set by the payment’s checklist, which its business model and purpose code choose together.
- Education
- Travel
Uploading is decoupled from any payment, so you can do it the moment a document arrives rather than holding it until you have the full set. A document can also be waived with a
waiver_reason instead of a ref, where the requirements allow it.Submit Verification Details
Complete bodies for every purpose code, both send modes, and every error.
If you need the full picture
The webhook already tells you what is missing, so this call is not part of the loop. Reach for it when you missed the webhook, when you are picking up a payment someone started days ago, or when you are building the screen you show the buyer and want every message up front. It is idempotent — call it whenever.fields and documents. Each entry carries a code, a message, satisfied and provided — so the ones still owed are those with satisfied: false. Those messages are written to be shown to a buyer, including the exact wording they must be shown to affirm buyer_declaration.
The response also carries settlement_status, the payment’s own state. Read it before you send: once a payment is UNDER_REVIEW or beyond, its verification has been filed and further sends are refused.
Get Verification Requirements
Full response, statuses, and what each purpose code asks for.
Four things that will bite you
Partial sends merge. Three fields today and two tomorrow is five fields. Nothing you sent earlier is wiped. Nobody collects a passport, a visa and an admission letter in the same instant, so do not wait until you have everything. An unknown key is a400, not a silent drop. A misspelled remitter_pan that we quietly ignored would leave the payment waiting forever for something you believe you sent. Every key is checked before any is written, so one typo cannot half-apply a call.
Omit a key rather than sending null or an empty string. A boolean is only satisfied by true — false reads as not yet answered.
The response tells you what is still owed. outstanding is the list of codes, and status is where the payment stands — lower-case, one of four:
action_required with an empty outstanding is the important pair: the checklist is satisfied, our checks refused. That verdict only arrives on the event.
The payment has a deadline
A payment that never completes its verification is refunded to the buyer. That is terminal — the window closes and nothing you send afterwards reopens it. Where the verification gateway names a deadline of its own, it arrives aspayment_verification_expiry on the event; on the Virtual Bank Account rails that key is null, because no gateway set a date. Either way, treat the arrival of the money as when the clock started, surface it in your own UI, and chase against it. It is the difference between a payment that settles and one that unwinds.