From 368fcf8fb8c19a1657bf6da2a231c336bff0ea31 Mon Sep 17 00:00:00 2001 From: Pragati Verma Date: Fri, 24 Apr 2026 15:43:06 +0530 Subject: [PATCH 1/3] Mobile Prepaid Recharge Doc Updates --- .../billpay/mobile-prepaid-recharge.json | 109 +++++++++++------- .../mobile-prepaid-recharge/webhooks.mdx | 53 ++++++--- 2 files changed, 101 insertions(+), 61 deletions(-) diff --git a/api-references/payments/billpay/mobile-prepaid-recharge.json b/api-references/payments/billpay/mobile-prepaid-recharge.json index 4b59ecbc..69e6331a 100644 --- a/api-references/payments/billpay/mobile-prepaid-recharge.json +++ b/api-references/payments/billpay/mobile-prepaid-recharge.json @@ -637,61 +637,82 @@ "properties": { "success": { "type": "boolean", - "example": "true", + "example": true, "description": "Status of API call" }, "data": { - "type": "object", - "properties": { - "plans": { - "type": "array", - "items": { - "type": "object", - "properties": { - "talktime": { - "type": "string", - "example": "0.0", - "description": "Talktime available with plan" - }, - "plan_name": { - "type": "string", - "example": "Unlimited Talktime", - "description": "Name of the prepaid plan" - }, - "amount": { - "type": "number", - "example": 19900, - "description": "Price of the plan in paise (1/100 of a rupee). For example, 19900 paise = 199 INR." - }, - "validity": { - "type": "string", - "example": "28 days", - "description": "Validity period of the plan" - }, - "plan_description": { - "type": "string", - "example": "Unlimited calls with 1.5GB/day", - "description": "Details of the plan benefits" - }, - "service_provider": { - "type": "string", - "example": "Jio", - "description": "Service Provider" - } - } + "type": "array", + "description": "List of available prepaid plans", + "items": { + "type": "object", + "required": [ + "amount", + "plan_name", + "plan_description", + "talktime", + "validity", + "service_provider" + ], + "properties": { + "amount": { + "type": "number", + "example": 1000, + "description": "Plan amount" + }, + "plan_name": { + "type": "string", + "example": "Talktime (top up voucher)", + "description": "Name of the prepaid plan" + }, + "plan_description": { + "type": "string", + "example": "Talktime : Rs 7.47", + "description": "Details of the plan benefits" + }, + "talktime": { + "type": "string", + "example": "7.47", + "description": "Talktime available with plan" }, - "description": "List of available prepaid plans" + "validity": { + "type": "string", + "example": "NA", + "description": "Validity period of the plan" + }, + "service_provider": { + "type": "string", + "example": "Airtel Prepaid", + "description": "Service provider name" + } } - }, - "description": "Details for listing available plans for the mobile number" + } }, - "traceId": { + "trace_id": { "type": "string", "example": "dMXpKMx4TBKsu8ro1559WeYZS21Og5", "description": "Identifier associated with this response for debug purposes" } } } + , + "examples": { + "Fetch Plans": { + "value": { + "success": true, + "data": [ + { + "amount": 1000, + "plan_name": "Talktime (top up voucher)", + "plan_description": "Talktime : Rs 7.47", + "talktime": "7.47", + "validity": "NA", + "service_provider": "Airtel Prepaid" + } + ], + "trace_id": "dMXpKMx4TBKsu8ro1559WeYZS21Og5" + } + } + } } }, "description": "Ok" @@ -1058,7 +1079,7 @@ }, "paymentRefId": { "type": "string", - "description": "Unique reference ID for the payment transaction. This must be unique for each transaction and is used for status checks.Must be a alphanumeric string with length between 5 and 30 characters." + "description": "Unique reference ID for the payment transaction. This must be unique for each transaction and is used for status checks.Must be a alphanumeric string with length between 6 and 30 characters." }, "timestamp": { "type": "string", diff --git a/content/payments/billpay/mobile-prepaid-recharge/webhooks.mdx b/content/payments/billpay/mobile-prepaid-recharge/webhooks.mdx index ecea2dc4..2fa40601 100644 --- a/content/payments/billpay/mobile-prepaid-recharge/webhooks.mdx +++ b/content/payments/billpay/mobile-prepaid-recharge/webhooks.mdx @@ -46,12 +46,12 @@ The system appends specific routes to your base `webhook_url` based on the event "transactionRefId": "string", "trace_id": "string", "operatorRefId": "string", - "status": "Successful | Processing | Failure", + "status": "Successful | Failure", "amount": "string", "mobile_number": "string", "provider": "string", "failureReason": "string (optional, only present for failures)", - "timestamp": "ISO 8601 datetime string" + "timestamp": "ISO 8601 datetime string (IST, +05:30)" }`} **Field Descriptions**: @@ -61,12 +61,12 @@ The system appends specific routes to your base `webhook_url` based on the event | `transactionRefId` | string | Transaction reference ID from the original recharge request | Yes | | `trace_id` | string | System reference number (internal trace ID) | Yes | | `operatorRefId` | string | Operator transaction ID (if available) | No | -| `status` | string | Transaction status - one of: `"Successful"`, `"Processing"`, `"Failure"` | Yes | +| `status` | string | Transaction status - one of: `"Successful"`, `"Failure"` | Yes | | `amount` | string | Recharge amount (in rupees) | Yes | | `mobile_number` | string | Mobile number that was recharged | Yes | | `provider` | string | Service provider name | Yes | | `failureReason` | string | Reason for failure (only present when status is "Failure") | No | -| `timestamp` | string | ISO 8601 formatted timestamp of the event | Yes | +| `timestamp` | string | ISO 8601 formatted timestamp of the event (IST, `+05:30`) | Yes |
@@ -84,7 +84,7 @@ The system appends specific routes to your base `webhook_url` based on the event "amount": "99.00", "mobile_number": "9876543210", "provider": "Airtel", - "timestamp": "2025-11-13T10:30:00Z" + "timestamp": "2026-01-09T11:56:26+05:30" }`}
@@ -106,7 +106,7 @@ The system appends specific routes to your base `webhook_url` based on the event "mobile_number": "9876543210", "provider": "Airtel", "failureReason": "Insufficient balance", - "timestamp": "2025-11-13T10:31:00Z" + "timestamp": "2026-01-09T11:56:26+05:30" }`} @@ -131,7 +131,7 @@ The system appends specific routes to your base `webhook_url` based on the event "mobile_number": "string", "provider": "string", "failureReason": "string (optional)", - "timestamp": "ISO 8601 datetime string" + "timestamp": "ISO 8601 datetime string (IST, +05:30)" }`} **Field Descriptions**: @@ -149,7 +149,7 @@ The system appends specific routes to your base `webhook_url` based on the event | `mobile_number` | string | Mobile number that was recharged | Yes | | `provider` | string | Service provider name | Yes | | `failureReason` | string | Reason for reversal (if provided by operator) | No | -| `timestamp` | string | ISO 8601 formatted timestamp of the event | Yes | +| `timestamp` | string | ISO 8601 formatted timestamp of the event (IST, `+05:30`) | Yes |
@@ -168,7 +168,7 @@ The system appends specific routes to your base `webhook_url` based on the event "mobile_number": "9876543210", "provider": "Airtel", "failureReason": "Transaction reversed by operator", - "timestamp": "2025-11-13T10:35:00Z" + "timestamp": "2026-01-09T11:56:26+05:30" }`}
@@ -178,7 +178,7 @@ The system appends specific routes to your base `webhook_url` based on the event ### 3. Wallet Low Balance Webhook -**Endpoint**: `{webhook_url}/wallet/low_balance` +**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. @@ -188,7 +188,7 @@ The system appends specific routes to your base `webhook_url` based on the event "event": "wallet.low_balance", "balance": "string", "message": "string", - "timestamp": "ISO 8601 datetime string", + "timestamp": "ISO 8601 datetime string (IST, +05:30)", "traceId": "string" }`} @@ -199,7 +199,7 @@ The system appends specific routes to your base `webhook_url` based on the event | `event` | string | Always `"wallet.low_balance"` for this webhook type | Yes | | `balance` | string | Current wallet balance amount (in rupees) | Yes | | `message` | string | Alert message (typically "Low balance Alert") | Yes | -| `timestamp` | string | ISO 8601 formatted timestamp (UTC) | Yes | +| `timestamp` | string | ISO 8601 formatted timestamp (IST, `+05:30`) | Yes | | `traceId` | string | Unique trace ID for this notification | Yes | @@ -214,7 +214,7 @@ The system appends specific routes to your base `webhook_url` based on the event "event": "wallet.low_balance", "balance": "2450.00", "message": "Low balance Alert", - "timestamp": "2025-11-13T09:15:00Z", + "timestamp": "2026-01-09T11:56:26+05:30", "traceId": "low-balance-webhook-demo-instance-a1b2c3d4" }`} @@ -225,7 +225,7 @@ The system appends specific routes to your base `webhook_url` based on the event ### 4. Wallet Topup Webhook -**Endpoint**: `{webhook_url}/wallet/top_up` +**Endpoint**: `{webhook_url}/wallet/topup` **Description**: Sent when a wallet top-up is detected or when a top-up notification is received from the vendor. @@ -236,7 +236,7 @@ The system appends specific routes to your base `webhook_url` based on the event "amount": "string", "referenceNumber": "string", "creditedFrom": "string", - "transactionDate": "ISO 8601 datetime string", + "transactionDate": "ISO 8601 datetime string (IST, +05:30)", "message": "string", "traceId": "string", "currentBalance": "string" @@ -250,7 +250,7 @@ The system appends specific routes to your base `webhook_url` based on the event | `amount` | string | Top-up amount credited to wallet (in rupees) | Yes | | `referenceNumber` | string | User reference number for the top-up transaction (may be empty string) | No | | `creditedFrom` | string | Source of the credit (e.g., "Bank Transfer", may be empty string) | No | -| `transactionDate` | string | ISO 8601 formatted timestamp of the transaction | Yes | +| `transactionDate` | string | ISO 8601 formatted timestamp of the transaction (IST, `+05:30`) | Yes | | `message` | string | Transaction message (defaults to "Credit Successful" if not provided) | No | | `traceId` | string | Unique trace ID for this notification | Yes | | `currentBalance` | string | Current wallet balance after the top-up (in rupees) | Yes | @@ -268,7 +268,7 @@ The system appends specific routes to your base `webhook_url` based on the event "amount": "5000.00", "referenceNumber": "TXN-9090", "creditedFrom": "Bank Transfer", - "transactionDate": "2025-11-13T09:45:00Z", + "transactionDate": "2026-01-09T11:56:26+05:30", "message": "Wallet topped up successfully", "traceId": "topup-webhook-demo-instance-e5f6g7h8", "currentBalance": "12450.00" @@ -308,32 +308,51 @@ The system implements automatic retry mechanisms for webhook delivery with diffe #### 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. From d2feb3e1a1ae03f884c1f253ea28a975ce733408 Mon Sep 17 00:00:00 2001 From: Pragati Verma Date: Fri, 24 Apr 2026 16:35:13 +0530 Subject: [PATCH 2/3] Fix trace_id formatting --- .../billpay/mobile-prepaid-recharge.json | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/api-references/payments/billpay/mobile-prepaid-recharge.json b/api-references/payments/billpay/mobile-prepaid-recharge.json index 69e6331a..47a9f8c3 100644 --- a/api-references/payments/billpay/mobile-prepaid-recharge.json +++ b/api-references/payments/billpay/mobile-prepaid-recharge.json @@ -127,7 +127,7 @@ "example": "You are not authenticated to perform the requested action.", "description": "Error message" }, - "traceId": { + "trace_id": { "type": "string", "example": "21fc3650-21c3-498a-b83e-543301045fcb", "description": "Unique identifier for tracing the request" @@ -138,7 +138,7 @@ "status": 401, "type": "", "message": "You are not authenticated to perform the requested action.", - "traceId": "21fc3650-21c3-498a-b83e-543301045fcb" + "trace_id": "21fc3650-21c3-498a-b83e-543301045fcb" } } } @@ -280,7 +280,7 @@ }, "description": "Details for listing mobile number details required for fetching plans and recharge" }, - "traceId": { + "trace_id": { "type": "string", "example": "dMXpKMx4TBKsu8ro1559WeYZS21Og5", "description": "Identifier associated with this response for debug purposes" @@ -2403,7 +2403,7 @@ }, "description": "Details of the wallet balance" }, - "traceId": { + "trace_id": { "type": "string", "example": "dMXpKMx4TBKsu8ro1559WeYZS21Og5", "description": "Identifier associated with this response for debug purposes" @@ -2581,7 +2581,7 @@ { "required": [ "success", - "traceId" + "trace_id" ], "type": "object", "properties": { @@ -2589,7 +2589,7 @@ "type": "boolean", "example": true }, - "traceId": { + "trace_id": { "type": "string", "example": "C3SFG0O6N88R6UI7EQ" } @@ -2600,7 +2600,7 @@ "successAndTracerDetails": { "required": [ "success", - "traceId" + "trace_id" ], "type": "object", "properties": { @@ -2608,7 +2608,7 @@ "type": "boolean", "example": true }, - "traceId": { + "trace_id": { "type": "string", "example": "C3SFG0O6N88R6UI7EQ" } From c160847f3682c5206fdda018e454c6675681adbb Mon Sep 17 00:00:00 2001 From: Pragati Verma Date: Mon, 27 Apr 2026 13:06:03 +0530 Subject: [PATCH 3/3] Update webhook description --- content/payments/billpay/mobile-prepaid-recharge/webhooks.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/payments/billpay/mobile-prepaid-recharge/webhooks.mdx b/content/payments/billpay/mobile-prepaid-recharge/webhooks.mdx index 2fa40601..3a024519 100644 --- a/content/payments/billpay/mobile-prepaid-recharge/webhooks.mdx +++ b/content/payments/billpay/mobile-prepaid-recharge/webhooks.mdx @@ -38,7 +38,7 @@ The system appends specific routes to your base `webhook_url` based on the event **Endpoint**: `{webhook_url}/payment/status` -**Description**: Sent when a recharge transaction status is updated (successful, failed, or processing). +**Description**: Sent when a recharge transaction status is updated (successful or failure). **Request Body**: