Skip to main content

​
Event Overview

Event Type: VERIFICATION_NEEDED
Category: Payment Verification
Description: Payment verification status has been updated This webhook is triggered when the payment verification status is updated for collect-from-India payments (after receiving a verification update from the payment gateway).

​
When the webhook is sent

The webhook is sent in the following scenarios:
  1. Action Required (ACTION_REQUIRED): Additional or corrected information is needed
  2. Payment Verified (VERIFIED): Payment has been successfully verified
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

​
Delivery Details

AttributeValue
HTTP methodPOST
URLThe webhook URL configured on your merchant account’s API credentials
Content-Typeapplication/json
Timeout10 seconds
RetriesUp to 5 delivery attempts (backoff: 1 min, 5 min, 15 min, 60 min)

​
Headers

HeaderDescription
Content-Typeapplication/json
User-AgentEximpe-Webhook/1.0
X-Webhook-EventVERIFICATION_NEEDED
X-Webhook-TimestampUnix timestamp (string) at the time of the request
X-Webhook-SignatureHMAC-SHA256 signature of the request body (JSON string with keys sorted, no extra whitespace), using your API key as the secret. Hex-encoded.
Signature verification (recommended):
Compute HMAC-SHA256(api_key, raw_body) where raw_body is the exact UTF-8 request body as received. Compare the hex result with the X-Webhook-Signature header to ensure the webhook is from the platform and unchanged.

​
Payload Schema

{
  "event_type": "VERIFICATION_NEEDED",
  "event_time": "2025-02-13T10:30:00.123456Z",
  "version": "2.0.0",
  "sequence_number": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "payment_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "order_id": "98765432-10ab-cdef-9876-543210fedcba",
    "verification_status": "ACTION_REQUIRED",
    "message": "Payment verification action required",
    "action_required_fields": ["buyer_name", "hs_code"]
  }
}

​
Field Specifications

​
event_type
string
required
Always "VERIFICATION_NEEDED" for this webhook event
​
event_time
string
required
ISO 8601 datetime when the webhook event was createdExample: "2025-02-13T10:30:00.123456Z"
​
version
string
required
Envelope version (e.g. “2.0.0”)
​
sequence_number
string
required
Unique identifier for this webhook event (UUID), useful for idempotencyExample: "550e8400-e29b-41d4-a716-446655440000"
​
data
object
required
Verification status details (payment_id, order_id, verification_status, message, action_required_fields)

​
What to Do When You Receive This Webhook

  1. Respond with HTTP 2xx (e.g. 200 OK) as soon as you have accepted the payload, so the platform marks the delivery as successful and does not retry.
  2. Verify the signature using your API key and the raw request body (HMAC-SHA256, hex) to ensure authenticity.
  3. Use data.payment_id and data.order_id to reconcile with your system or fetch more details from the Partner API.
  4. Handle based on verification status:
    • VERIFIED: Update your system to reflect successful verification. Payment can proceed to settlement.
    • ACTION_REQUIRED:
      • Check data.action_required_fields to see what needs updating
      • Notify merchant/admin about required actions
      • Update the specified fields using the Upload Verification Details API

​
Action Required Fields Reference

When verification_status is ACTION_REQUIRED, the action_required_fields array contains field names that need attention:
Field NameDescription
buyer_nameFull name of the buyer/importer
buyer_addressComplete address of the buyer
buyer_postal_codePostal/ZIP code of the buyer
product_descriptionDescription of goods/services
invoice_numberInvoice or order number
hs_codeHarmonized System code for goods