Skip to content

Prepaid recharge validate API - Add Error Codes and webhook callouts #373

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pankaj0308 merged 2 commits into from
Nov 28, 2025
Merged

Prepaid recharge validate API - Add Error Codes and webhook callouts #373

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
360dec9
Add validation failed cases
pragati-setu Nov 28, 2025
45e2580
Add callouts to webhooks page
pragati-setu Nov 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
157 changes: 136 additions & 21 deletions api-references/payments/billpay/mobile-prepaid-recharge.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1098,7 +1098,7 @@
"properties": {
"error": {
"type": [
"string",
"object",
"null"
],
"example": null,
Expand Down Expand Up @@ -1853,11 +1853,8 @@
"type": "object",
"properties": {
"error": {
"type": [
"string",
"null"
],
"example": null,
"$ref": "#/components/schemas/ValidationError",
"nullable": true,
"description": "Error details if any, otherwise null"
},
"details": {
Expand Down Expand Up @@ -1899,7 +1896,7 @@
"status": {
"type": "string",
"example": "Success",
"description": "Status of the recharge validation. Possible values: `Success`, `Processing`, `Failure`"
"description": "Status of the recharge validation. Possible values: `Validation Successful`, `Validation Failed`"
}
},
"description": "Details of the recharge validation"
Expand All @@ -1911,21 +1908,113 @@
}
}
},
"example": {
"data": {
"error": null,
"details": {
"mobile_number": "7249649345",
"provider": "Airtel",
"service_type": "M",
"is_special": false
},
"amount": 2200,
"ValidationRefNo": "LXMREN493393852",
"status": "Success"
"examples": {
"validation-success": {
"value": {
"data": {
"error": null,
"details": {
"mobile_number": "7249649345",
"provider": "Airtel",
"service_type": "M",
"is_special": false
},
"amount": 2200,
"ValidationRefNo": "LXMREN493393852",
"status": "Validation Successful"
},
"trace_id": "0466a81f4d4a1c336dcbc",
"success": true
}
},
"invalid-amount": {
"value": {
"data": {
"error": {
"code": "2",
"message": "Invalid Amount.",
"failureReason": "Invalid Amount"
},
"details": {
"mobile_number": "7249649345",
"provider": "Airtel",
"service_type": "M",
"is_special": false
},
"amount": 150,
"ValidationRefNo": "LVSYAHFY389555848",
"status": "Validation Failed"
},
"trace_id": "d4kll8d2vl64uj1778m0",
"success": true
}
},
"amount-zero-failure": {
"value": {
"data": {
"error": {
"code": "4",
"message": "Amount Less Or Equalto Zero",
"failureReason": "Amount Less Or Equalto Zero"
},
"details": {
"mobile_number": "7249649345",
"provider": "Airtel",
"service_type": "M",
"is_special": false
},
"amount": 0,
"ValidationRefNo": "LVSYTNLY389512894",
"status": "Validation Failed"
},
"trace_id": "d4klbe52vl649l2047sg",
"success": true
}
},
"trace_id": "0466a81f4d4a1c336dcbc",
"success": true
"operator-internal-processing-error": {
"value": {
"data": {
"error": {
"code": "2",
"message": "Operator Internal processing error",
"failureReason": "Operator Internal processing error"
},
"details": {
"mobile_number": "7249649345",
"provider": "Airtel",
"service_type": "M",
"is_special": false
},
"amount": 0,
"ValidationRefNo": "LVSYTNLY389516789",
"status": "Validation Failed"
},
"trace_id": "d4kll8d2vl64uj1778m0",
"success": true
}
},
"error-in-validation-api-call": {
"value": {
"data": {
"error": {
"code": "1",
"message": "Error in Validation API call",
"failureReason": "Error in Validation API call"
},
"details": {
"mobile_number": "7249649345",
"provider": "Airtel",
"service_type": "M",
"is_special": false
},
"amount": 0,
"ValidationRefNo": "LVSYTNLY389516789",
"status": "Validation Failed"
},
"trace_id": "d4kll8d2vl64uj1778m0",
"success": true
}
}
}
}
},
Expand Down Expand Up @@ -2409,6 +2498,32 @@
},
"components": {
"schemas": {
"ValidationError": {
"type": "object",
"required": [
"code",
"message",
"failureReason"
],
"properties": {
"code": {
"type": "string",
"example": "1",
"description": "Validation error code"
},
"message": {
"type": "string",
"example": "Error in Validation API call Please try again",
"description": "Human-readable explanation of the error"
},
"failureReason": {
"type": "string",
"example": "Error in Validation API call Please try again",
"description": "Specific failure reason returned by the provider"
}
},
"description": "Error payload returned by the validation API"
},
"fetchTokenRequest": {
"type": "object",
"properties": {
Expand Down
8 changes: 7 additions & 1 deletion content/payments/billpay/mobile-prepaid-recharge/webhooks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,10 @@ You need to do the following to configure a Setu provided webhook—

To configure webhooks, share your webhook URL with Setu via email to <a href="mailto:support@setu.co">support@setu.co</a>.

<Callout type="warning">
We expect a single base URL for all webhooks and we will append the specific endpoints to the base URL based on the event type.
</Callout>

<hr class="primary" />


Expand Down Expand Up @@ -336,6 +340,8 @@ The system implements automatic retry mechanisms for webhook delivery with diffe
- 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.
<Callout type="warning">
After all retries are exhausted, the webhook status is marked as "FAILED" in the system.
</Callout>

<WasPageHelpful />