#Webhooks/Notifications

This document describes the webhooks that are sent to your configured webhook URL when various events occur in the recharge system.

#Pre-requisites

You need to do the following to configure a Setu provided webhook—

• Share the webhook URL. A URL that can accept JSON data over POST.
• Take steps to handle the notification

#Configuration

To configure webhooks, share your webhook URL with Setu via email to support@setu.co.

#Webhook Endpoints

The system appends specific routes to your base webhook_url based on the event type:

#1. Payment Status Webhook

Endpoint: {webhook_url}/payment/status

Description: Sent when a recharge transaction status is updated (successful, failed, or processing).

Request Body:

{
  "transactionRefId": "string",
  "trace_id": "string",
  "operatorRefId": "string",
  "status": "Successful | Processing | Failure",
  "amount": "string",
  "mobile_number": "string",
  "provider": "string",
  "failureReason": "string (optional, only present for failures)",
  "timestamp": "ISO 8601 datetime string"
}

Field Descriptions:

{
  "transactionRefId": "TXN123456789",
  "trace_id": "SYS-ABC-123",
  "operatorRefId": "OP-987654321",
  "status": "Successful",
  "amount": "99.00",
  "mobile_number": "9876543210",
  "provider": "Airtel",
  "timestamp": "2025-11-13T10:30:00Z"
}

{
  "transactionRefId": "TXN123456790",
  "trace_id": "SYS-ABC-124",
  "status": "Failure",
  "amount": "99.00",
  "mobile_number": "9876543210",
  "provider": "Airtel",
  "failureReason": "Insufficient balance",
  "timestamp": "2025-11-13T10:31:00Z"
}

#2. Payment Reversal Webhook

Endpoint: {webhook_url}/payment/reversal

Description: Sent when a recharge transaction is reversed by the operator.

Request Body:

{
  "transactionRefId": "string",
  "trace_id": "string",
  "operatorRefId": "string (optional)",
  "status": "REVERSED",
  "amount": "string",
  "mobile_number": "string",
  "provider": "string",
  "failureReason": "string (optional)",
  "timestamp": "ISO 8601 datetime string"
}

Field Descriptions:

• Same fields as Payment Status Webhook, but status will always be "REVERSED"
• failureReason: May contain reason for reversal if provided by operator

{
  "transactionRefId": "TXN123456789",
  "trace_id": "SYS-ABC-123",
  "operatorRefId": "OP-987654321",
  "status": "REVERSED",
  "amount": "99.00",
  "mobile_number": "9876543210",
  "provider": "Airtel",
  "failureReason": "Transaction reversed by operator",
  "timestamp": "2025-11-13T10:35:00Z"
}

#3. Wallet Low Balance Webhook

Endpoint: {webhook_url}/wallet/low_balance

Description: Sent when the wallet balance falls below the configured threshold or when a low balance alert is received from the vendor.

Request Body:

{
  "event": "wallet.low_balance",
  "balance": "string",
  "message": "string",
  "timestamp": "ISO 8601 datetime string",
  "traceId": "string"
}

Field Descriptions:

{
  "event": "wallet.low_balance",
  "balance": "2450.00",
  "message": "Low balance Alert",
  "timestamp": "2025-11-13T09:15:00Z",
  "traceId": "low-balance-webhook-demo-instance-a1b2c3d4"
}

#4. Wallet Topup Webhook

Endpoint: {webhook_url}/wallet/top_up

Description: Sent when a wallet top-up is detected or when a top-up notification is received from the vendor.

Request Body:

{
  "event": "wallet.credit",
  "amount": "string",
  "referenceNumber": "string",
  "creditedFrom": "string",
  "transactionDate": "ISO 8601 datetime string",
  "message": "string",
  "traceId": "string",
  "currentBalance": "string"
}

Field Descriptions:

{
  "event": "wallet.credit",
  "amount": "5000.00",
  "referenceNumber": "TXN-9090",
  "creditedFrom": "Bank Transfer",
  "transactionDate": "2025-11-13T09:45:00Z",
  "message": "Wallet topped up successfully",
  "traceId": "topup-webhook-demo-instance-e5f6g7h8",
  "currentBalance": "12450.00"
}

#Webhook Response

Your webhook endpoint should respond with:

• HTTP Status Code: 200-299 for successful receipt
• Response Body: Any valid JSON (will be logged but not processed)

Example Response:

{
  "received": true,
  "message": "Webhook processed successfully"
}

If your endpoint returns a non-2xx status code or times out, the system will automatically retry according to the retry policy for that webhook type (see Retry Mechanism section).

#Retry Mechanism

The system implements automatic retry mechanisms for webhook delivery with different policies based on webhook type:

#Payment Webhooks (Transaction Status & Reversal)

• Maximum Retries: 5 attempts
• Initial Retry Interval: 2 seconds
• Maximum Retry Interval: 2 minutes
• Backoff Strategy: Exponential backoff with coefficient of 2.0
• Retry Triggers:
  • Non-2xx HTTP status codes
  • Network timeouts
  • Connection errors

#Wallet Webhooks (Low Balance & Topup)

• Maximum Retries: 3 attempts
• Initial Retry Interval: 5 seconds
• Maximum Retry Interval: 1 minute
• Backoff Strategy: Exponential backoff with coefficient of 2.0
• Retry Triggers:
  • Non-2xx HTTP status codes
  • Network timeouts
  • Connection errors

Retry Timeline Example (Payment Webhooks):

• Attempt 1: Immediate
• Attempt 2: After 2 seconds
• Attempt 3: After 4 seconds (2 × 2)
• Attempt 4: After 8 seconds (4 × 2)
• Attempt 5: After 16 seconds (8 × 2)
• Attempt 6: After 32 seconds (16 × 2, capped at 2 minutes max)

After all retries are exhausted, the webhook status is marked as "FAILED" in the system.