VERIFICATION NEEDED

Event Overview

Event Type: VERIFICATION_NEEDED Category: Payment Verification Description: A payment needs verification details before it can settle This webhook names what a payment still owes before it can be filed. It is the general verification ask — every rail raises it, and it carries one body wherever it comes from.

One event, one body. VERIFICATION_NEEDED used to mean two different payloads depending on which rail the money arrived through: one shape from the card and collect flows, another from Virtual Bank Account credits that also carried the credit’s amount and account details. A partner needed two handlers for one event type. Every producer now builds the same seven keys, and the credit’s own facts ride PAYMENT_SUCCESSFUL, which is the event that exists to describe the money.

Not sent for LRS payments. A payment settling under an LRS purpose code receives LRS_VERIFICATION_NEEDED instead, which names documents as well as fields. It never receives both.A payment whose purpose code is not yet known still receives this one; the LRS event takes over once the code is declared.

When the webhook is sent

A Virtual Bank Account credit became a payment that is missing verification details. The event follows PAYMENT_SUCCESSFUL and names what is outstanding.
The verification gateway reported a change — the payment moved to ACTION_REQUIRED, IN_REVIEW or EXPIRED.
A verification submit was refused on a payment with no LRS checklist. The event names what to fix — the single item that failed, not everything the payment still owes. On a B2B services payment this covers the finalizing call’s own checks: the purpose code, the invoice amount, the declaration, and the documents cited for the invoice.
Ops sent a B2B services verification back for changes. The payment returns to ACTION_REQUIRED and staging reopens. message carries the Ops comment rather than the standard sentence, and action_required_fields names what the checklist still owes.
A B2B services submit passed. The set was filed — through Submit Verification Details or by the merchant in the dashboard — and the payment moved to Under Review to wait for an Ops decision. verification_status is "IN_REVIEW" and the list is empty. It fires again on each resubmit after a send-back.

A verified payment sends no webhook — VERIFIED means nothing is outstanding, so there is nothing to act on. Do not wait on it to confirm verification.

Ops approving or rejecting a B2B services verification raises nothing. Only the send-back does. Read those two from Get Verification Requirements — an approval leaves settlement_status at UNDER_REVIEW, a rejection moves it to NOT_APPLICABLE and raises a full refund.

Not every refused submit raises this event. It is raised only where the refusal maps to a checklist item. A call refused for a reason that names no item — a body we could not read, or staging already closed because the set has been filed — answers in the response and raises nothing. Treat the response as authoritative on your own calls, and this event as how you learn about changes you did not make.

The webhook is delivered only if your merchant account (or parent, for sub-merchants) has an active API credential with a non-empty webhook URL. Without one nothing reaches you — some producers skip recording the event at all, others record it and it is simply never sent, so an event you never received is not evidence of anything on our side either way.

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`	`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

{
  "event_type": "VERIFICATION_NEEDED",
  "event_time": "2026-02-13T10:30:00.123456",
  "version": "3.0.0",
  "sequence_number": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "payment_id": "PR7712349900",
    "order_id": "OD1122334455",
    "link_id": null,
    "verification_status": "ACTION_REQUIRED",
    "message": "Payment verification action required",
    "action_required_fields": ["buyer_name", "hs_code", "purpose_code"],
    "payment_verification_expiry": "2026-02-20T23:59:59"
  }
}

{
  "event_type": "VERIFICATION_NEEDED",
  "event_time": "2026-02-13T10:31:41.902244",
  "version": "3.0.0",
  "sequence_number": "550e8400-e29b-41d4-a716-446655440001",
  "data": {
    "payment_id": "PR7712349900",
    "order_id": "OD1122334455",
    "link_id": null,
    "verification_status": "ACTION_REQUIRED",
    "message": "Payment verification action required",
    "action_required_fields": [
      "business_model",
      "purpose_code",
      "buyer_name",
      "product_description",
      "invoice_number",
      "buyer_postal_code"
    ],
    "payment_verification_expiry": null
  }
}

{
  "event_type": "VERIFICATION_NEEDED",
  "event_time": "2026-02-13T10:32:18.550913",
  "version": "3.0.0",
  "sequence_number": "550e8400-e29b-41d4-a716-446655440002",
  "data": {
    "payment_id": "PR7712349900",
    "order_id": "OD1122334455",
    "link_id": null,
    "verification_status": "IN_REVIEW",
    "message": "Payment verification action required",
    "action_required_fields": [],
    "payment_verification_expiry": null
  }
}

{
  "event_type": "VERIFICATION_NEEDED",
  "event_time": "2026-02-13T10:33:02.117408",
  "version": "3.0.0",
  "sequence_number": "550e8400-e29b-41d4-a716-446655440003",
  "data": {
    "payment_id": "PR7712349900",
    "order_id": "OD1122334455",
    "link_id": null,
    "verification_status": "EXPIRED",
    "message": "Payment verification action required",
    "action_required_fields": ["invoice_file", "hs_code"],
    "payment_verification_expiry": "2026-02-12T23:59:59"
  }
}

message reads “Payment verification action required” on every one of these, including IN_REVIEW — it is not a description of the state. It is not fixed either: the sandbox ON_HOLD event says “Payment settlement is on hold”. Branch on verification_status, never on message.

Field Specifications

Root Level Fields
Data Object Fields

string

required

Always "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-02-13T10: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

Seven keys, always the same seven: payment_id, order_id, link_id, verification_status, message, action_required_fields, payment_verification_expiry

string

required

UID of the paymentExample: "PR7712349900"

string

required

UID of the order for this paymentExample: "OD1122334455"

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.Example: "PR4829301756"

string

required

The payment’s verification state. One of ACTION_REQUIRED, IN_REVIEW, EXPIRED — and ON_HOLD in sandbox. A verified payment sends no event, so VERIFIED never appears here.

string

required

A human-readable summary, usually "Payment verification action required". It varies with the state — the sandbox ON_HOLD event carries a different sentence — so it is safe to log but never to branch on.On a B2B services send-back it is the Ops comment, written by a person, and it is the only place that says why the payment came back. Surface it; do not pattern-match it.

array of strings

required

Plain field codes that need your action. It names whatever the checklist still owes, and is empty only when the checklist is genuinely satisfied.On a refused submit it is narrower — the single item that failed, not the full set. Treat that one as an error pointer rather than a to-do list: fixing the item it names can still leave the payment short, so read Get Verification Requirements for the whole picture before you file again.Empty means “the checklist is satisfied” — not “nothing to do”. Read it together with verification_status. On an IN_REVIEW event the two agree and there really is nothing for you: the payment is with a reviewer. On an ACTION_REQUIRED event — a B2B services send-back — the payment is open again because a person asked for a change, and message is the instruction. Branch on the status, not on the list length.Strings, not objects. LRS_VERIFICATION_NEEDED carries objects in a key of the same name, because it also has a sentence and a set of flags to say per item. If one handler reads both events, check the element type or route on event_type.

string | null

required

ISO 8601 datetime by which verification must be complete, or null when the gateway has not provided a deadline.Past this point the payment can no longer be verified: verification_status becomes EXPIRED and the collected amount is refunded to the buyer. Treat each event’s value as authoritative — it can move, and an event is sent when it does.The value is whatever the verification gateway named, carried through unchanged. It is null where the gateway named nothing: on an IN_REVIEW event, where nothing is being asked of you, and on the Virtual Bank Account rails, which have no deadline of this kind at all.null is not “no clock”. A payment that never completes its verification is refunded to the buyer regardless; this key only reports the gateway’s own stated deadline where one exists.Example: "2026-02-20T23:59:59"

Reading `action_required_fields`

The codes come from whichever check raised the event, and there are two vocabularies. Both are answered through an API, and the codes tell you which one.

Order fields

Raised by the verification gateway’s own report, and by the plain order-field check on a credit that has not been classified:

Field	Description
`buyer_name`	Full name of the buyer/importer
`buyer_address`	Complete address of the buyer
`buyer_postal_code`	Postal/ZIP code of the buyer
`product_description`	Description of goods/services
`invoice_number`	Invoice or order number
`invoice_file`	The commercial invoice
`hs_code`	Harmonized System code for goods
`country_of_origin`	Country the goods ship from

Supply these with Submit Payment Verification Details — with two exceptions. invoice_file is a file on the order, uploaded with POST /pg/orders/{order_id}/documents/ and document_type: INVOICE. country_of_origin is not settable through the API today; raise it with support if the gateway asks for it.

Classification

Two facts decide which checklist a payment answers to, and either one that has not been declared appears in the same list:

Field	Meaning
`purpose_code`	No FEMA/FETERS purpose code has been declared for this order.
`business_model`	Nothing has declared whether the buyer is `B2C` or `B2B`.

business_model is listed when nothing has declared it — not when it is empty. It is never empty; it defaults to B2C. A default nobody stood behind is worth telling you about, and sending "business_model": "B2C" is a real answer rather than a no-op.

Declaring the pair changes what you are asked for. Without a purpose code there is no checklist, so the event can only name the generic order fields. Declare both — through Submit Verification Details — and the payment’s real checklist takes over. If that checklist is an LRS one, the payment switches to LRS_VERIFICATION_NEEDED and stops receiving this event.

Checklist codes

Once a payment is classified and its checklist is not an LRS one, the list holds that checklist’s outstanding codes — buyer_city, buyer_state, buyer_email, iec, buyer_pan, invoice, and so on. Send these back through Submit Verification Details, under the same codes.

Declaring the classification does not raise a fresh event on a non-LRS payment. The follow-up ask is only re-sent when the new checklist is an LRS one, where it arrives as LRS_VERIFICATION_NEEDED. Otherwise, read the new checklist’s codes from Get Verification Requirements after you classify.

Do not hardcode the list. Get Verification Requirements returns the whole set for a payment, each item carrying its own satisfied flag, and it is revised as the underlying regulatory matrix is. Read it rather than reproducing it.

What to Do When You Receive This Webhook

Respond with HTTP 2xx (e.g. 200 OK) as soon as you have accepted the payload, so the delivery is not retried.
Verify the signature against the raw request body — prefer X-Webhook-Signature-V2.
Use payment_id and order_id to reconcile with your system.
Handle based on verification_status:
- ACTION_REQUIRED — read action_required_fields, collect what it names, and send it back. If you are unsure which endpoint takes a given code, GET the payment’s verification requirements: anything it lists is answered on that same path.
- IN_REVIEW — nothing to do. Record that the payment is under review.
- EXPIRED — the verification window closed and the amount is refunded to the buyer. action_required_fields records what lapsed, but nothing you send reopens it. Close the payment out on your side.
Watch payment_verification_expiry while the status is ACTION_REQUIRED and it is not null. It is the deadline the payment is working to, and it can move between events.

The event is not the only way to read this. Get Verification Requirements is authoritative and idempotent — call it any time an event was missed, arrived out of order, or you simply want to reconcile. It also reports settlement_status, which tells you whether sending anything is still possible.

Get Verification Requirements

The whole set, on demand, with settlement_status.

Submit Payment Verification Details

Where the order fields go.

LRS_VERIFICATION_NEEDED

The LRS payment’s version of this event.

PAYMENT_UNDER_REVIEW

Same body, empty list — nothing is owed any more.

Order

Payment

Merchant

Settlement

Refund

Subscriptions

Payment Links

Virtual Bank Accounts

LRS

B2B Services

Webhooks

Event Overview

When the webhook is sent

Delivery Details

Headers

Payload Schema

Field Specifications

Reading `action_required_fields`

Order fields

Classification

Checklist codes

What to Do When You Receive This Webhook

Get Verification Requirements

Submit Payment Verification Details

LRS_VERIFICATION_NEEDED

PAYMENT_UNDER_REVIEW

​Event Overview

​When the webhook is sent

​Delivery Details

​Headers

​Payload Schema

​Field Specifications

​Reading action_required_fields

​Order fields

​Classification

​Checklist codes

​What to Do When You Receive This Webhook

​Related

Get Verification Requirements

Submit Payment Verification Details

LRS_VERIFICATION_NEEDED

PAYMENT_UNDER_REVIEW

Event Overview

When the webhook is sent

Delivery Details

Headers

Payload Schema

Field Specifications

Reading `action_required_fields`

Order fields

Classification

Checklist codes

What to Do When You Receive This Webhook

Related