> ## 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.

# PAYMENT SUCCESSFUL

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

***

## Event Overview

**Event Type**: `PAYMENT_SUCCESSFUL`\
**Category**: Payment\
**Description**: Payment transaction was successful

This webhook is triggered when a payment is marked CAPTURED (after a payment success callback or VBA transfer processor).

### When the webhook is sent

* **Regular payment flow:** After a payment success callback is received, the payment is updated to CAPTURED and the webhook is created.
* **VBA transfer flow:** After a VBA transfer payment is successfully recorded, the webhook is created.
* 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

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

### Headers

| Header                | Description                                                                                                                                   |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `Content-Type`        | `application/json`                                                                                                                            |
| `User-Agent`          | `Eximpe-Webhook/1.0`                                                                                                                          |
| `X-Webhook-Event`     | `PAYMENT_SUCCESSFUL`                                                                                                                          |
| `X-Webhook-Timestamp` | Unix timestamp (string) at the time of the request                                                                                            |
| `X-Webhook-Signature` | HMAC-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(encryption_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

<CodeGroup>
  ```json Example Payload theme={null}
  {
    "event_type": "PAYMENT_SUCCESSFUL",
    "event_time": "2025-02-12T10:30:00.123456Z",
    "version": "2.0.0",
    "sequence_number": "550e8400-e29b-41d4-a716-446655440000",
    "data": {
      "payment_id": "770e8400-e29b-41d4-a716-446655440002",
      "order_id": "660e8400-e29b-41d4-a716-446655440001",
      "status": "CAPTURED",
      "message": "Payment successful",
      "mop_type": "VBA_TRANSFER",
      "bank_ref_num": "BANKREF123",
      "payment_completed_at": "2025-02-12T10:29:55.000000Z",
      "utr": "UTR123456",
      "virtual_account_id": "USER09",
      "subscription_id": null
    }
  }
  ```
</CodeGroup>

***

## Field Specifications

<Tabs>
  <Tab title="Root Level Fields">
    <ParamField path="event_type" type="string" required>
      Always `"PAYMENT_SUCCESSFUL"` for this webhook event
    </ParamField>

    <ParamField path="event_time" type="string" required>
      ISO 8601 datetime when the webhook event was created

      **Example**: `"2025-02-12T10:30:00.123456Z"`
    </ParamField>

    <ParamField path="version" type="string" required>
      Envelope version (e.g. "2.0.0")
    </ParamField>

    <ParamField path="sequence_number" type="string" required>
      Unique identifier for this webhook event (UUID), useful for idempotency

      **Example**: `"550e8400-e29b-41d4-a716-446655440000"`
    </ParamField>

    <ParamField path="data" type="object" required>
      Payment request details (payment\_id, order\_id, status, message, mop\_type, bank\_ref\_num, payment\_completed\_at, utr, virtual\_account\_id, subscription\_id)
    </ParamField>
  </Tab>

  <Tab title="Data Object Fields">
    <ParamField path="data.payment_id" type="string" required>
      UID of the payment

      **Example**: `"770e8400-e29b-41d4-a716-446655440002"`
    </ParamField>

    <ParamField path="data.order_id" type="string" required>
      UID of the order for this payment

      **Example**: `"660e8400-e29b-41d4-a716-446655440001"`
    </ParamField>

    <ParamField path="data.status" type="string" required>
      Payment status (CAPTURED for successful payments)

      **Example**: `"CAPTURED"`
    </ParamField>

    <ParamField path="data.message" type="string" required>
      Status message from the payment

      **Example**: `"Payment successful"`
    </ParamField>

    <ParamField path="data.mop_type" type="string" required>
      Method of payment type

      **Example**: `"VBA_TRANSFER"`
    </ParamField>

    <ParamField path="data.bank_ref_num" type="string" required>
      Bank reference number (if any)

      **Example**: `"BANKREF123"`
    </ParamField>

    <ParamField path="data.payment_completed_at" type="string" required>
      ISO 8601 datetime when payment completed (typically set for success)

      **Example**: `"2025-02-12T10:29:55.000000Z"`
    </ParamField>

    <ParamField path="data.utr" type="string" required>
      UTR of the payment (if any); may be empty or null

      **Example**: `"UTR123456"`
    </ParamField>

    <ParamField path="data.virtual_account_id" type="string" required>
      Virtual account ID of the MerchantVBA (if this payment is linked to a VBA); otherwise null

      **Example**: `"USER09"`
    </ParamField>
  </Tab>
</Tabs>

***

## 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. **Note:** You may subsequently receive a **PAYMENT\_DETAILS\_MISSING** webhook if verification details are missing on the order (see [Payment Details Missing](/api-reference/v2/webhooks/payment-details-missing)).