> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eximpe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MERCHANT CHANGES NEEDED

> Technical reference for the MERCHANT_CHANGES_NEEDED webhook event, including payload schema, field specifications, and implementation details.

***

## Event Overview

**Event Type**: `MERCHANT_CHANGES_NEEDED`\
**Category**: Onboarding\
**Description**: EximPe needs changes to a sub-merchant's application before it can be approved

This webhook is sent each time EximPe sends a sub-merchant's application back for changes. It is delivered to the parent merchant's webhook URL, and carries EximPe's reason and the parts of the application to fix. The sub-merchant's status is then `CHANGES_REQUESTED`.

It is sent every time EximPe asks for changes, including when the sub-merchant is already `CHANGES_REQUESTED` and EximPe asks again. Each delivery carries the latest reasons.

To act on it, fix the fields with [Update Merchant](https://docs.eximpe.com/api-reference/v3/merchant/update.md). Once the application is complete again, that edit resubmits it for review automatically; there is no separate resubmit call.

***

## Delivery Details

| Attribute | Value |
| - | - |
| **HTTP method** | `POST` |
| **URL** | The webhook URL configured for your merchant account |
| **Content-Type** | `application/json` |
| **Timeout** | 10 seconds |
| **Retries** | Up to 5 delivery attempts (backoff: 1 min, 5 min, 15 min, 60 min) |

### Headers

| Header | Description |
| - | - |
| `Content-Type` | `application/json` |
| `User-Agent` | `Eximpe-Webhook/1.0` |
| `X-Webhook-Event` | `MERCHANT_CHANGES_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.

Both signature headers are sent. Verify V2 (recommended) or V1 — see [Verifying webhooks](https://docs.eximpe.com/integration-guide/v3/web-integration/webhooks.md#check-the-message-is-really-from-us).

***

## Payload Schema

```json Example Payload theme={null}
{
    "event_type": "MERCHANT_CHANGES_NEEDED",
    "event_time": "2026-12-15T14:32:18.456789",
    "version": "3.0.0",
    "sequence_number": "5f0c2b1e-9a43-4d7e-8b61-2c7d9e4f1a90",
    "data": {
        "merchant_id": "1380229823",
        "legal_name": "TechStore Solutions Private Limited",
        "trade_name": "TechStore Online",
        "timestamp": "2026-12-15T14:32:18.456789",
        "reason": "The registration number does not match the incorporation certificate.",
        "section_reasons": [
            {
                "section": "company_details",
                "reason": "Registration number does not match the certificate."
            },
            {
                "section": "settlement_account",
                "reason": "Bank account name must match the legal name."
            }
        ]
    }
}
```

***

## Field Specifications

> [tab] Root Level Fields
>
> **event\_type** `string` *required*
>
> Always `"MERCHANT_CHANGES_NEEDED"` for this webhook event
>
> **event\_time** `string` *required*
>
> UTC, no timezone suffix, e.g. `"2026-12-15T14:32:18.456789"`. Parse tolerantly — fractional seconds can be absent.
>
> **version** `string` *required*
>
> API version of your account, e.g. `"3.0.0"`
>
> **sequence\_number** `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**: `"5f0c2b1e-9a43-4d7e-8b61-2c7d9e4f1a90"`
>
> **data** `object` *required*
>
> Event-specific data payload containing the requested changes

> [tab] Data Object Fields
>
> **data.merchant\_id** `string` *required*
>
> Unique identifier of the sub-merchant
>
> **Example**: `"1380229823"`
>
> **data.legal\_name** `string` *required*
>
> Legal business name of the sub-merchant as registered with authorities
>
> **Example**: `"TechStore Solutions Private Limited"`
>
> **data.trade\_name** `string` *required*
>
> The sub-merchant's brand name: the `brand_name` sent when it was created or last edited, or `legal_name` when none was sent.
>
> **Example**: `"TechStore Online"`
>
> **data.timestamp** `string` *required*
>
> ISO 8601 timestamp when EximPe asked for the changes
>
> **Example**: `"2026-12-15T14:32:18.456789"`
>
> **data.reason** `string` *required*
>
> EximPe's overall reason for sending the application back. Can be an empty string when no reason was recorded. The same text is returned as `changes_requested_reason` by [Get Merchant](https://docs.eximpe.com/api-reference/v3/merchant/get.md).
>
> **Example**: `"The registration number does not match the incorporation certificate."`
>
> **data.section\_reasons** `array` *required*
>
> One entry per part of the application that needs changes. Can be empty.
>
> * `section` — the part of the application, e.g. `"company_details"`. See [Sections](https://docs.eximpe.com/api-reference/v3/merchant/options.md#sections) for every value.
> * `reason` — what needs to change in that part.
>
> **Example**: `[{"section": "company_details", "reason": "Registration number does not match the certificate."}]`

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.