Skip to main content
POST
Submit verification details

Overview

An LRS payment answers a longer list than an ordinary one: the remitter’s verified identity, the LRS declarations, the TCS collected, and a set of documents that depends on the purpose code. This page is that list, and what happens once it is complete.
Same endpoint as Submit Payment Verification Details. One URL answers every verification ask — fields, documents, partial sends and the response shape all work identically. Only what a payment is asked for differs, and that is what this page covers. If you do not handle LRS payments, the other page is all you need.
Send details keyed by the same codes that Get Verification Requirements and the LRS_VERIFICATION_NEEDED webhook use. There is nothing to map between them — every one of those places names an item under code: JSON only. fields is an object; documents is a list of {code, ref} naming files uploaded earlier through Upload Document. Files are never posted to this endpoint.

The loop

1

An event arrives

LRS_VERIFICATION_NEEDED lists what the payment owes — each entry a code and a sentence.
2

You upload any files

Upload Document returns a ref per file. Upload each as it arrives; nothing has to be held back.
3

You send what you have

Fields as a map, documents as {code, ref}. Partial is fine — later sends merge over earlier ones.
4

You read where the payment stands

The response says both: a status, and outstanding — the codes still owed after this write.

The body depends on the checklist

There is one endpoint and one envelope — fields, documents, persons, finalize — but what belongs inside them is decided by the payment’s checklist, not by you. That checklist comes from the order’s business model and purpose code together. You never have to work out which set applies: GET the same path and it tells you, or read the codes off the event. Declaring an LRS purpose code is what makes a payment an LRS one. Send business_model and purpose_code together in fields — see Submit Payment Verification Details for the rules that govern the pair — and if the code is one of the five below, the payment switches to LRS_VERIFICATION_NEEDED and starts being asked for everything on this page. The pair may ride in the same call as the rest. Complete bodies for every LRS purpose code, built from the live checklists:
The three travel codes take an identical body. They differ in what the remittance is for — other travel, medical treatment, pilgrimage — not in what you must collect. Travel asks for no documents, and asks for persons only when your account collects traveller details. Education is always asked for one person: the student. The parent or sponsor who pays is not a second entry — they are identified by remitter_pan and remitter_dob in fields. Sending a student who is not the remitter is what makes relationship_declaration owed. If the remitter is the student, send only [{ "is_remitter": true }] (with a passport_number on S0305) and it drops out. The remitter name and TCS are not fields; the name comes from Verify PAN and the TCS from the quote.

What differs, and what does not

The address lines are optional here; the PIN code is not. buyer_address_line_1, buyer_city and buyer_state never block completion on an LRS checklist, and a blank value sent for one is ignored rather than refused. The body examples above include them for completeness. buyer_postal_code is still required.
Do not branch on the purpose code in your own integration. Read the checklist instead. The codes above are what the matrix asks for today; it is configuration, and a revision reaches you through the API without a release on your side — but only if you are reading it rather than reproducing it.

Values

Field values are strings, numbers or booleans. An unknown key is a 400, not a silent drop. Omit a key rather than sending a blank value. A declaration must be a JSON boolean — the string "true" is refused with ERR_DECLARATION_001, Declaration must be true or false..

Documents

Each entry names one code and exactly one of ref or waiver_reason. Sending both, or neither, is a 400. Sending the same code twice in one call is a 400. Sending it again in a later call is fine — the newer ref or waiver replaces the earlier row.

Persons

persons is a top-level list in the request body, beside fields and documents — not an entry inside fields. Each entry describes one person on the remittance.
Sending persons again replaces the list; the newest send wins. Nothing about a person is ever returned to you — the GET reports only whether persons is satisfied and provided.

Verification level

Your EximPe contact configures whether travel payments collect traveller details; the checklist’s persons item tells you.

Person errors

A list that breaks one of these rules is refused as a whole, and each carries a code of its own: The rules on a single entry answer under 40359, with the message in details:

Linking a top-up

When the buyer was short, they can pay the rest as further payments. Link those payments to the short one with top_up, sent on the short payment’s own call:
  • Send the full list every time. An id you leave out is unlinked, and [] removes every link. Leave top_up out entirely and the links stay as they are. At most 20 ids per call.
  • It can go alone. Once the verification details are on file for this payment, top_up is all you need to send. Nothing else has to be repeated.
  • The link is declared by the short payment. A top-up never declares it on its own call.
  • It is read when the call files. With finalize: false, or while the set is still incomplete, top_up is not applied.
  • All or nothing. If any one id is refused, the whole call is refused and nothing changes.
  • The group clears on the call that covers what is owed — principal, our fee, the GST on it and the TCS, counting the short payment and every top-up. Nothing else needs to be sent. A credit that overpays does not block it; the excess is refunded, newest top-up first.
  • Membership is frozen once the group clears (ERR_LRS_MERCHANT_043). After that, the list can no longer change.
A link is refused, with a named error, when:
  • the short payment has no verification details on file yet (ERR_LRS_MERCHANT_044);
  • the short payment is itself a top-up of another payment (ERR_LRS_MERCHANT_045);
  • the short payment is not waiting for action, or is not short;
  • manual verification is not on for both the short payment and the top-up;
  • the short payment or the top-up was not collected by EximPe;
  • your account derives the amount to be settled;
  • the top-up is not waiting for action, or its counter is already posted;
  • the top-up belongs to another merchant;
  • the top-up is already in another group, or has top-ups of its own (ERR_LRS_MERCHANT_037, ERR_LRS_MERCHANT_038);
  • the top-up is the short payment itself.
A top-up made through hosted checkout must carry a PAN equal to the short payment’s PAN and, if its order has a purpose code, the same purpose code. A top-up that arrived by bank transfer to the virtual account must have a sender name that matches the remitter, otherwise the link is refused with 40361. A hosted-checkout top-up with a different PAN or purpose code is refused with ERR_LRS_MERCHANT_041 or ERR_LRS_MERCHANT_042.
A top-up payment is created like any LRS order. For a payment made through hosted checkout, create the order the way you create any LRS order, and the buyer verifies the PAN at checkout. The order must carry an LRS purpose code and business model. Otherwise there is no PAN check at checkout, and the link is refused for lack of a verified PAN (ERR_LRS_MERCHANT_040). There is no separate endpoint for top-ups.
A linked top-up cannot be submitted on its own (ERR_LRS_MERCHANT_047). Remove it from the short payment’s top_up list first.
A linked top-up shows its primary’s status. Reading it returns the primary’s settlement status and message, plus linked_primary_payment_id. The verification webhooks (LRS_VERIFICATION_NEEDED and the payment-details-missing event) are sent for the primary only, not for its top-ups.
The Rs 25,00,000 limit applies to the principal of one remittance — the principal declared on the short payment’s call. Top-ups pay toward it and do not add to it. A principal above it is refused with ERR_LRS_MERCHANT_052, and Quote LRS Amount returns refusal_reason: "lrs_remittance_cap_exceeded".

Refunding payments in a top-up group

Refunds follow the group’s state. A refusal comes back as a 400 with code ERR_REFUND_002 and the reason in details.
  • Before the group clears, refunding a top-up refunds it and unlinks it from the short payment.
  • After the group clears, a top-up cannot be refunded on its own (ERR_LRS_MERCHANT_049).
  • A short payment with top-ups can only be refunded in full (ERR_LRS_MERCHANT_050). A full refund also refunds every top-up, each to its own source.
  • Once the group has settled, none of its payments can be refunded (ERR_LRS_MERCHANT_051).
  • If the group is rejected, every credit in it is refunded.

Partial sends are merged

Send three fields today and two tomorrow and you have sent five. Nothing you sent earlier is wiped by a later call, and a field’s newest value wins. finalize defaults to true. It applies only to a complete set and never forces an incomplete one through, so a partial send is accepted either way — you do not have to set it. Pass finalize: false only to save without filing.
Once you have filed, sending is closed.

The response

Three keys, whatever you sent — and a fourth, refusal, on the one response that has something more to say: a complete set that did not pass verification.
string
required
Lower-case, always one of four. The first two answer is the checklist satisfied; the second two answer what happened when it was filed, and only appear on a call that actually filed.
array
required
The codes still owed after this write — the same codes you would get by filtering the GET on satisfied: false. Empty when nothing is.This is the list, not a pointer to one. You do not need a second call to learn what is left.
object
Why verification refused a set the checklist called complete. Present only alongside status: action_required — absent from every other response, so read it as a key that may not be there rather than one that is sometimes null.Where outstanding says what the checklist still wants, this says what verification found. Verification only runs once the checklist is satisfied, so a refusal always arrives with outstanding empty.reason is one of:Both name mismatches mean the buyer name and the PAN name disagree; correct whichever is wrong and send again.missing uses these tokens: purpose_code, remitter.pan, declarations, primary_person, tcs, outstanding (a shortfall), derived_amount_credit_too_small (the credit is too small to settle), and documents.<type> for each document still wanted — documents.passport, documents.offer_letter, and so on.The purpose-code and PAN verdicts are reached before anything else is looked at, so each carries exactly one entry in missing, and outstanding_rupees is "0.00". Only SENDER_NAME_MISMATCH and a null reason can carry a shortfall, or more than one entry.The same verdict also arrives as LRS_VERIFICATION_NEEDED.

outstanding is empty and status is action_required

The checklist is satisfied; verification refused. The verdict arrives as LRS_VERIFICATION_NEEDED, same event type and same shape as any other, with the conclusion folded into the relevant entry’s message — a shortfall’s rupee figure, a PAN that would not verify, a sender who is not the account holder.

Completion

finalize defaults to true and applies only to a complete set. It never forces an incomplete one through. Pass finalize: false only to save without filing. When a complete set is filed it goes through verification — PAN verification, the sender-to-account-holder match, the TCS recomputation and the exactly-once LRS counter posting. in_review means all of that passed. A complete LRS set is always filed. Sending the last outstanding item triggers verification on that same call, so the response answers in_review or action_required rather than complete. You only see complete here if you held the filing back with finalize: false. A refusal is a successful 200 that reports action_required. If verification cannot give a verdict the call errors and nothing is lost; send the same request again.

Errors

Every refusal is answered in the standard error envelope. Every refusal is a 400, whatever the reason, except a PAN check that could not run because the PAN provider is unavailable, which is a 503 (ERR_LRS_MERCHANT_006). The code inside the envelope is what tells refusals apart, not the status. A 400 on the send carries details keyed by the offending code, so one call reports every problem at once:
Value rules run on the send that carries the value, and name the same codes: Every value in a call is checked before any is written, so one bad value cannot half-apply a send. What is left for the call that files a complete set is verification’s own verdict — see refusal — and a call that errors because verification could not give a verdict (ERR_LRS_MERCHANT_021). Your details are still saved either way: fix the named code and re-send only that.

Where each value goes

Most fields flow into the verification and settlement record. Two are collected but held rather than forwarded, and it is worth knowing which:

Refunds

You can refund a payment while its verification is still open — a refund is not held back by verification.
  • A full refund closes the verification. Sending and filing are both refused once refunds for the whole amount exist — including one that is still in progress — and the payment moves to NOT_APPLICABLE.
  • The LRS limit comes back when the refund completes. When completed refunds cover the whole amount, the TCS counter and the limit that payment counted against are released, so the buyer can use them again. A partial refund leaves them as they were, and a payment that has already settled keeps its posting.

Submit Payment Verification Details

The same endpoint, for a payment that is not an LRS one.

Get Verification Requirements

What this payment needs, and what it already has.

Upload Document

Upload a file and reference it by ref.

LRS_VERIFICATION_NEEDED

The event that tells you a payment owes details — and the one that reports a refusal.

Quote LRS Amount

TCS and the all-in total, before the buyer transfers.

Authorizations

X-Client-ID
string
header
required

Client Application ID - Your unique application identifier used to authenticate API requests. You can find your Client ID in the Developer Settings section of the merchant dashboard.

X-Client-Secret
string
header
required

Client Secret Key - Your secret key used alongside the Client ID for secure authentication. Keep this confidential and never expose it in client-side code. Available in the Developer Settings section of the merchant dashboard.

X-Merchant-ID
string
header
required

Merchant Identifier - The unique ID for the merchant account. This is required for PSP (Payment Service Provider) merchants who manage multiple merchant accounts. You can find merchant IDs in the Merchant Management section of the dashboard.

X-API-Version
string
header
required

API Version - Optional, and not a credential. Send 3.0.0 for v3. If you omit it, the call still succeeds and the response echoes your account's default version in an X-API-Version header.

Path Parameters

payment_id
string
required

UID of the payment the details are for.

Body

application/json
fields
object

Answers keyed by checklist code, e.g. {"buyer_city": "Bengaluru", "invoice_number": "INV-2026-0041"}. Values are strings, numbers or booleans. Dates are YYYY-MM-DD; invoice_amount is a decimal string in rupees and declaration is a boolean. An unknown key is a 400 rather than a silent drop — a typo you never hear about would leave the payment waiting forever for a field you believe you sent. Omit a key rather than sending null or an empty string; a blank value is also a 400.

Example:
documents
object[]

Documents by reference, or waivers. Each entry names exactly one of ref and waiver_reason; sending both, neither, or the same code twice in one call is a 400.

persons
object[]

The people on an LRS remittance, sent beside fields and documents. Education (S0305, S1107): exactly one entry, the student; the payer is identified by remitter_pan in fields. Travel: every traveller, but only when your account collects traveller details. Sending persons again replaces the list. Not used on a B2B-services payment.

finalize
boolean
default:true

Whether to file a complete set for verification. Never forces an incomplete set through.

top_up
string[]

LRS only. The ids of the payments that top up this one, sent on the short payment's own call. Send the full list every time: an id left out is unlinked and [] removes every link. Once the details are on file it can be sent alone. Any refused id refuses the whole call. A B2B-services payment has no top-ups and ignores this key.

Example:

Response

Details received. The body says where the payment now stands and what is still owed.

success
boolean
Example:

true

message
string
Example:

"Verification details received"

data
object