diff --git a/api-references/payments/billpay/mobile-prepaid-recharge.json b/api-references/payments/billpay/mobile-prepaid-recharge.json index c2e30949..e3ef2c90 100644 --- a/api-references/payments/billpay/mobile-prepaid-recharge.json +++ b/api-references/payments/billpay/mobile-prepaid-recharge.json @@ -21,14 +21,17 @@ "url": "https://prepaid-uat.setu.co", "description": "UAT" } + ], "paths": { "/v1/users/login": { + "servers": [ + { + "url":"https://accountservice.setu.co" + } + ], "post": { - "tags": [ - "Authentication" - ], - "summary": "API to authenticate and get access token", + "summary": "Token API", "description": "Use this endpoint to obtain a Bearer token required for all other API calls.", "consumes": [ "application/json" @@ -247,7 +250,7 @@ "mobile_number": { "type": "string", "example": "7066573354", - "description": "Input mobile number" + "description": "The 10-digit mobile number for which the operator details are retrieved." }, "current_operator": { "type": "string", @@ -365,75 +368,47 @@ } }, "422": { - "description": "Invalid Request Parameters", - "headers": { - "content-length": { - "schema": { - "type": "string", - "example": "204" - } - }, - "date": { - "schema": { - "type": "string", - "example": "Sun, 13 Oct 2024 20:28:16 GMT" - } - }, - "server": { - "schema": { - "type": "string", - "example": "uvicorn" - } - }, - "x-trace-id": { - "schema": { - "type": "string", - "example": "3b0e103e-4fa8-403f-a6c9-b9dd62b82de7" - } - } - }, + "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "type": "object", + "required": ["success", "error", "trace_id"], "properties": { + "success": { "type": "boolean", "example": false }, "error": { "type": "object", + "required": ["code", "message", "failureReason"], "properties": { - "code": { - "type": "string", - "example": "ERR011" - }, - "failureReason": { - "type": "string", - "example": "input-params-missing" - }, - "message": { - "type": "string", - "example": "Missing required parameters: customer.billParameters.0.name" - } + "code": { "type": "string", "example": "ERR009" }, + "message": { "type": "string", "example": "Invalid Product Instance ID: " }, + "failureReason": { "type": "string", "example": "invalid-instance-id" } } }, - "success": { - "type": "boolean", - "example": false - }, - "trace_id": { - "type": "string", - "example": "3b0e103e-4fa8-403f-a6c9-b9dd62b82de7" - } + "trace_id": { "type": "string", "example": "d1m1kslcjsji7vn3b5vg" } } }, "examples": { - "422": { + "invalid-instance-id": { "value": { + "success": false, "error": { - "code": "ERR011", - "failureReason": "input-params-missing", - "message": "Missing required parameters: customer.billParameters.0.name" + "code": "ERR009", + "message": "Invalid Product Instance ID: b7e2c9a1-5d4f-4c8e-9f3a-2a1b6c7d8e9f", + "failureReason": "invalid-instance-id" }, + "trace_id": "d1m1kslcjsji7vn3b5vg" + } + }, + "balance-api-unavailable-in-uat": { + "value": { "success": false, - "trace_id": "3b0e103e-4fa8-403f-a6c9-b9dd62b82de7" + "error": { + "code": "ERR012", + "message": "Balance API is not available in UAT environment", + "failureReason": "balance-api-unavailable-in-uat" + }, + "trace_id": "d1m1j6kd7qs2b5gbln8g" } } } @@ -523,14 +498,16 @@ "name": "X-PRODUCT-INSTANCE-ID", "required": true, "type": "string", - "description": "Unique identifier provided by Setu that represents your product instance." + "description": "Unique identifier provided by Setu that represents your product instance.", + "example": "b7e2c9a1-5d4f-4c8e-9f3a-2a1b6c7d8e9f" }, { "in": "header", "name": "Authorization", "required": true, "type": "string", - "description": "Bearer token for authorization. Format: 'Bearer {token}' where {token} is obtained from the login API." + "description": "Bearer token for authorization. Format: 'Bearer {token}' where {token} is access token recieved from token API.", + "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, { "in": "body", @@ -628,7 +605,7 @@ }, "value": { "type": "string", - "description": "The value for the parameter. For 'Mobile Number': 10-digit number. For 'Operator': lowercase operator name (e.g., 'jio', 'airtel', 'vi', 'bsnl', 'mtnl'). For 'Location': exact circle name." + "description": "The value for the parameter. For 'Mobile Number': 10-digit number. For 'Operator': lowercase operator name (e.g., `jio`, `airtel`, `vi`, `bsnl`, `mtnl`). For 'Location': exact circle name." } } }, @@ -683,8 +660,8 @@ }, "amount": { "type": "number", - "example": 199, - "description": "Price of the plan in paise" + "example": 19900, + "description": "Price of the plan in paise (1/100 of a rupee). For example, 19900 paise = 199 INR." }, "validity": { "type": "string", @@ -889,14 +866,16 @@ "name": "X-PRODUCT-INSTANCE-ID", "required": true, "type": "string", - "description": "Unique identifier provided by Setu that represents your product instance." + "description": "Unique identifier provided by Setu that represents your product instance.", + "example": "b7e2c9a1-5d4f-4c8e-9f3a-2a1b6c7d8e9f" }, { "in": "header", "name": "Authorization", "required": true, "type": "string", - "description": "Bearer token for authorization. Format: 'Bearer {token}' where {token} is obtained from the login API." + "description": "Bearer token for authorization. Format: 'Bearer {token}' where {token} is access token recieved from token API.", + "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, { "in": "body", @@ -936,7 +915,7 @@ "value": { "type": "string", "example": "7066573353", - "description": "The value of the customer mobile number or related info like Operator and Location." + "description": "The value of the customer mobile number whose details are being fetched." } } }, @@ -1066,7 +1045,7 @@ }, "mode": { "type": "string", - "description": "The payment mode used for the recharge. Must be one of: 'Internet Banking', 'UPI', 'Debit Card', 'Credit Card', or 'Wallet'.", + "description": "The payment mode used for the recharge. **Accepted values:**\n- `Internet Banking`\n- `UPI`\n- `Debit Card`\n- `Credit Card`\n- `Wallet`\n\nThe value must match exactly as shown above (case-sensitive).", "example": "Internet Banking" }, "paymentParams": { @@ -1141,7 +1120,7 @@ "service_type": { "type": "string", "example": "M", - "description": "Service type (e.g., Mobile)" + "description": "Represents the service type. Always set to 'M' for Mobile." }, "is_postpaid": { "type": "boolean", @@ -1360,14 +1339,16 @@ "name": "X-PRODUCT-INSTANCE-ID", "required": true, "type": "string", - "description": "Unique identifier provided by Setu that represents your product instance." + "description": "Unique identifier provided by Setu that represents your product instance.", + "example": "b7e2c9a1-5d4f-4c8e-9f3a-2a1b6c7d8e9f" }, { "in": "header", "name": "Authorization", "required": true, "type": "string", - "description": "Bearer token for authorization. Format: 'Bearer {token}' where {token} is obtained from the login API." + "description": "Bearer token for authorization. Format: 'Bearer {token}' where {token} is access token recieved from token API.", + "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, { "in": "body", @@ -1407,7 +1388,21 @@ } } }, - "description": "Parameters for the recharge request, including Mobile Number, Operator, and Location." + "description": "Parameters for the recharge request, including Mobile Number, Operator, and Location.", + "example": [ + { + "name": "Mobile Number", + "value": "7066573353" + }, + { + "name": "Operator", + "value": "jio" + }, + { + "name": "Location", + "value": "Maharashtra" + } + ] }, "mobile": { "type": "string", @@ -1429,7 +1424,7 @@ "properties": { "amount": { "type": "number", - "example": 2900, + "example": 1900, "description": "Recharge amount in paise (1/100 of a rupee). Must be a positive integer value representing the amount in paise." }, "mode": { @@ -1492,7 +1487,7 @@ "properties": { "paymentRefId": { "type": "string", - "description": "Reference ID for the payment transaction whose status is being queried. This must match the paymentRefId used in the original recharge request." + "description": "Reference ID for the payment transaction whose status is being queried. This is the same paymentRefId used in the original recharge request." } } } @@ -1543,7 +1538,7 @@ "service_type": { "type": "string", "example": "M", - "description": "Service type (e.g., Mobile)" + "description": "Represents the service type. Always set to 'M' for Mobile." }, "is_postpaid": { "type": "boolean", @@ -1591,6 +1586,113 @@ } }, "description": "Ok" + }, + "422": { + "description": "Unprocessable Entity", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["success", "error", "trace_id"], + "properties": { + "success": { "type": "boolean", "example": false }, + "error": { + "type": "object", + "required": ["code", "message", "failureReason"], + "properties": { + "code": { "type": "string", "example": "ERR009" }, + "message": { "type": "string", "example": "Invalid Product Instance ID: " }, + "failureReason": { "type": "string", "example": "invalid-instance-id" } + } + }, + "trace_id": { "type": "string", "example": "d1m1kslcjsji7vn3b5vg" } + } + }, + "examples": { + "invalid-instance-id": { + "value": { + "success": false, + "error": { + "code": "ERR009", + "message": "Invalid Product Instance ID: b7e2c9a1-5d4f-4c8e-9f3a-2a1b6c7d8e9f", + "failureReason": "invalid-instance-id" + }, + "trace_id": "d1m1kslcjsji7vn3b5vg" + } + }, + "invalid-txn-ref-id": { + "value": { + "success": false, + "error": { + "code": "ERR003", + "message": "Invalid Transaction Reference ID : TEST6291DD4X0475X70C2S2402", + "failureReason": "invalid-txn-ref-id" + }, + "trace_id": "d1m1shsd7qs2b5gblnag" + } + }, + "input-params-invalid": { + "value": { + "success": false, + "error": { + "code": "ERR011", + "message": "Value error, Invalid input: 'paymentRefId' should be alphanumeric: paymentRefId", + "failureReason": "input-params-invalid" + }, + "trace_id": "d1m1uisd7qs2b5gblndg" + } + } + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["success", "error", "trace_id"], + "properties": { + "success": { "type": "boolean", "example": false }, + "error": { + "type": "object", + "required": ["code", "message", "failureReason"], + "properties": { + "code": { "type": "string", "example": "ERR100" }, + "message": { "type": "string", "example": "Internal Server Error" }, + "failureReason": { "type": "string", "example": "internal-server-error" } + } + }, + "trace_id": { "type": "string", "example": "d1m1us4d7qs2b5gblne0" } + } + }, + "examples": { + "internal-server-error": { + "value": { + "success": false, + "error": { + "code": "ERR100", + "message": "Internal Server Error", + "failureReason": "internal-server-error" + }, + "trace_id": "d1m1us4d7qs2b5gblne0" + } + }, + "upstream-connectivity-error": { + "value": { + "success": false, + "error": { + "code": "ERR999", + "message": "Upstream API Connectivity Error", + "failureReason": "upstream-connectivity-error" + }, + "trace_id": "d1m1us4d7qs2b5gblne0" + } + } + } + } + } } }, "parameters": [ @@ -1599,14 +1701,16 @@ "name": "X-PRODUCT-INSTANCE-ID", "required": true, "type": "string", - "description": "Unique identifier provided by Setu that represents your product instance." + "description": "Unique identifier provided by Setu that represents your product instance.", + "example": "b7e2c9a1-5d4f-4c8e-9f3a-2a1b6c7d8e9f" }, { "in": "header", "name": "Authorization", "required": true, "type": "string", - "description": "Bearer token for authorization. Format: 'Bearer {token}' where {token} is obtained from the login API." + "description": "Bearer token for authorization. Format: 'Bearer {token}' where {token} is access token recieved from token API.", + "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, { "in": "body", @@ -1680,6 +1784,87 @@ } }, "description": "Response containing the wallet balance details" + }, + "422": { + "description": "Unprocessable Entity", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["success", "error", "trace_id"], + "properties": { + "success": { "type": "boolean", "example": false }, + "error": { + "type": "object", + "required": ["code", "message", "failureReason"], + "properties": { + "code": { "type": "string", "example": "ERR009" }, + "message": { "type": "string", "example": "Invalid Product Instance ID: " }, + "failureReason": { "type": "string", "example": "invalid-instance-id" } + } + }, + "trace_id": { "type": "string", "example": "d1m1kslcjsji7vn3b5vg" } + } + }, + "examples": { + "invalid-instance-id": { + "value": { + "success": false, + "error": { + "code": "ERR009", + "message": "Invalid Product Instance ID: b7e2c9a1-5d4f-4c8e-9f3a-2a1b6c7d8e9f", + "failureReason": "invalid-instance-id" + }, + "trace_id": "d1m1kslcjsji7vn3b5vg" + } + }, + "balance-api-unavailable-in-uat": { + "value": { + "success": false, + "error": { + "code": "ERR012", + "message": "Balance API is not available in UAT environment", + "failureReason": "balance-api-unavailable-in-uat" + }, + "trace_id": "d1m1j6kd7qs2b5gbln8g" + } + } + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["success", "error", "trace_id"], + "properties": { + "success": { "type": "boolean", "example": false }, + "error": { + "type": "object", + "required": ["code", "message", "failureReason"], + "properties": { + "code": { "type": "string", "example": "ERR100" }, + "message": { "type": "string", "example": "Internal Server Error" }, + "failureReason": { "type": "string", "example": "internal-server-error" } + } + }, + "trace_id": { "type": "string", "example": "d1m1us4d7qs2b5gblne0" } + } + }, + "example": { + "success": false, + "error": { + "code": "ERR100", + "message": "Internal Server Error", + "failureReason": "internal-server-error" + }, + "trace_id": "d1m1us4d7qs2b5gblne0" + } + } + } } }, "parameters": [ @@ -1688,14 +1873,16 @@ "name": "X-PRODUCT-INSTANCE-ID", "required": true, "type": "string", - "description": "Unique identifier provided by Setu that represents your product instance." + "description": "Unique identifier provided by Setu that represents your product instance.", + "example": "b7e2c9a1-5d4f-4c8e-9f3a-2a1b6c7d8e9f" }, { "in": "header", "name": "Authorization", "required": true, "type": "string", - "description": "Bearer token for authorization. Format: 'Bearer {token}' where {token} is obtained from the login API." + "description": "Bearer token for authorization. Format: 'Bearer {token}' where {token} is access token recieved from token API.", + "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } ] } @@ -1757,14 +1944,16 @@ "name": "X-PRODUCT-INSTANCE-ID", "required": true, "type": "string", - "description": "Unique identifier provided by Setu that represents your product instance." + "description": "Unique identifier provided by Setu that represents your product instance.", + "example": "b7e2c9a1-5d4f-4c8e-9f3a-2a1b6c7d8e9f" }, { "in": "header", "name": "Authorization", "required": true, "type": "string", - "description": "Bearer token for authorization. Format: 'Bearer {token}' where {token} is obtained from the login API." + "description": "Bearer token for authorization. Format: 'Bearer {token}' where {token} is access token recieved from token API.", + "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } ], "responses": { @@ -1811,8 +2000,8 @@ }, "status": { "type": "string", - "example": "SUCCESS", - "description": "Status of the transaction" + "example": "Successful", + "description": "Status of the transaction. Possible values: `Successful`, `Processing`, `Failure`, `Reversed`." }, "timestamp": { "type": "string", @@ -1834,6 +2023,69 @@ } }, "description": "Response containing the list of transactions" + }, + "422": { + "description": "Invalid Request Parameters", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean", "example": false }, + "error": { + "type": "object", + "properties": { + "code": { "type": "string", "example": "ERR009" }, + "message": { "type": "string", "example": "Invalid Product Instance ID: 71f05a38-7cb6-4907-b7cb-7521c28824d9" }, + "failureReason": { "type": "string", "example": "invalid-instance-id" } + } + }, + "trace_id": { "type": "string", "example": "d1m02ecd7qsdk10rlkn0" } + } + }, + "example": { + "success": false, + "error": { + "code": "ERR009", + "message": "Invalid Product Instance ID: 71f05a38-7cb6-4907-b7cb-7521c28824d9", + "failureReason": "invalid-instance-id" + }, + "trace_id": "d1m02ecd7qsdk10rlkn0" + } + } + }, + "description": "Invalid Request Parameters" + }, + "500": { + "description": "Internal Server Error", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean", "example": false }, + "error": { + "type": "object", + "properties": { + "code": { "type": "string", "example": "ERR100" }, + "message": { "type": "string", "example": "Internal Server Error" }, + "failureReason": { "type": "string", "example": "internal-server-error" } + } + }, + "trace_id": { "type": "string", "example": "d1m02ecd7qsdk10rlkn0" } + } + }, + "example": { + "success": false, + "error": { + "code": "ERR100", + "message": "Internal Server Error", + "failureReason": "internal-server-error" + }, + "trace_id": "d1m02ecd7qsdk10rlkn0" + } + } + } } } }