diff --git a/api-references/payments/billpay/mobile-prepaid-recharge.json b/api-references/payments/billpay/mobile-prepaid-recharge.json index e19a0c3f..4afed665 100644 --- a/api-references/payments/billpay/mobile-prepaid-recharge.json +++ b/api-references/payments/billpay/mobile-prepaid-recharge.json @@ -1,16 +1,18 @@ + { - "openapi": "3.0.1", - "info": { - "title": "Prepaid Mobile Recharge", - "x-logo": { - "url": "https://setu-customer-success.s3.ap-south-1.amazonaws.com/icons/setu-logo-dp-on-tp.svg", - "altText": "Prepaid Mobile Recharge" - }, - "version": "1.0.0", - "description": "Process flow for prepaid recharge payments." - }, - "schemes": ["https"], - + "openapi": "3.0.1", + "info": { + "title": "Prepaid Mobile Recharge", + "x-logo": { + "url": "https://setu-customer-success.s3.ap-south-1.amazonaws.com/icons/setu-logo-dp-on-tp.svg", + "altText": "Prepaid Mobile Recharge" + }, + "version": "1.0.0", + "description": "Process flow for prepaid recharge payments." + }, + "schemes": [ + "https" + ], "servers": [ { "url": "https://prepaid.setu.co", @@ -20,35 +22,236 @@ "url": "https://prepaid-uat.setu.co", "description": "UAT" } + ], - "paths": { - "/fetch-operator-details": { - "post": { - "tags": ["Fetch"], - "summary": "API to fetch operator details for mobile number", - "consumes": ["application/json"], - "produces": ["application/json"], - "responses": { - "200": { - "content": { - "application/json": { + "paths": { + "/v1/users/login": { + "servers": [ + { + "url":"https://accountservice.setu.co" + } + ], + "post": { + "summary": "Token API", + "description": "Use this endpoint to obtain a Bearer token required for all other API calls.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ClientID", + "Secret", + "grant_type" + ], + "properties": { + "ClientID": { + "type": "string", + "description": "The client ID provided by Setu for your application." + }, + "Secret": { + "type": "string", + "description": "The client secret provided by Setu for your application. Keep this confidential." + }, + "grant_type": { + "type": "string", + "description": "The OAuth2 grant type. Must be set to 'client_credentials'.", + "enum": ["client_credentials"] + } + } + }, + "example": { + "ClientID": "XXXX-XXXX-XXXX-XXXX", + "Secret": "XXXXXXXXXXXXXXXXX", + "grant_type": "client_credentials" + } + } + } + }, + "responses": { + "200": { + "description": "Authentication successful", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "access_token", + "refresh_token" + ], + "properties": { + "access_token": { + "type": "string", + "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "description": "Bearer token to be used in Authorization header for subsequent API calls" + }, + "refresh_token": { + "type": "string", + "example": "", + "description": "Refresh token (currently not used)" + } + } + }, + "example": { + "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "refresh_token": "" + } + } + } + }, + "401": { + "description": "Authentication failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "integer", + "example": 401, + "description": "HTTP status code" + }, + "type": { + "type": "string", + "example": "", + "description": "Error type" + }, + "message": { + "type": "string", + "example": "You are not authenticated to perform the requested action.", + "description": "Error message" + }, + "traceId": { + "type": "string", + "example": "21fc3650-21c3-498a-b83e-543301045fcb", + "description": "Unique identifier for tracing the request" + } + } + }, + "example": { + "status": 401, + "type": "", + "message": "You are not authenticated to perform the requested action.", + "traceId": "21fc3650-21c3-498a-b83e-543301045fcb" + } + } + } + } + } + } + }, + "/fetch-operator-details": { + "post": { + "tags": [ + "Fetch" + ], + "summary": "API to fetch operator details for mobile number", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "customer" + ], + "properties": { + "customer": { + "type": "object", + "required": [ + "billParameters", + "mobile" + ], + "properties": { + "billParameters": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "value" + ], + "properties": { + "name": { + "type": "string", + "description": "The display name of the parameter. Must be 'Mobile Number' for this endpoint." + }, + "value": { + "type": "string", + "description": "The 10-digit mobile number whose operator details are being fetched. Must contain only numeric characters." + } + } + }, + "description": "Parameters for fetching Operator and Location details for mobile number. This array should contain exactly one object with name='Mobile Number'." + }, + "mobile": { + "type": "string", + "description": "The 10-digit mobile number of the user initiating the recharge. This may or may not be the same as the number being recharged." + } + }, + "description": "The details needed for fetching operator details." + } + } + }, + "example": { + "customer": { + "billParameters": [ + { + "name": "Mobile Number", + "value": "7066573353" + } + ], + "mobile": "7066573353" + } + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { "schema": { "type": "object", - "required": ["success", "data", "trace_id"], + "required": [ + "success", + "data", + "trace_id" + ], "properties": { - "success":{ - "type":"boolean", - "example":"true", - "description":"status of API call" + "success": { + "type": "boolean", + "example": "true", + "description": "status of API call" }, "data": { "type": "object", - "required": ["mobile_number","current_operator","current_location","previous_operator","previous_location","ported"], + "required": [ + "mobile_number", + "current_operator", + "current_location", + "previous_operator", + "previous_location", + "ported" + ], "properties": { "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", @@ -58,28 +261,24 @@ "current_location": { "type": "string", "example": "Maharashtra", - "description":"Operator Circle , valid values are : `Kolkata `,` Mumbai `,` Delhi `,` Chennai `,` Maharashtra `,` Gujarat `,` Andhra Pradesh `,` Karnataka `,` Tamil Nadu `,` Kerala `,` Punjab `,` Haryana `,` Uttar Pradesh (East) `,` Uttar Pradesh (West) `,` Madhya Pradesh `,` Rajasthan `,` West Bengal & AN Island `,` Orissa `,` Himachal Pradesh `,` Bihar & Jharkhand `,` Assam `,` NorthEast `,` J&K `,` Uttaranchal `,` All `,` IND`" - + "description": "Operator Circle , valid values are : `Kolkata `,` Mumbai `,` Delhi `,` Chennai `,` Maharashtra `,` Gujarat `,` Andhra Pradesh `,` Karnataka `,` Tamil Nadu `,` Kerala `,` Punjab `,` Haryana `,` Uttar Pradesh (East) `,` Uttar Pradesh (West) `,` Madhya Pradesh `,` Rajasthan `,` West Bengal & AN Island `,` Orissa `,` Himachal Pradesh `,` Bihar & Jharkhand `,` Assam `,` NorthEast `,` J&K `,` Uttaranchal `,` All `,` IND`" + }, + "previous_operator": { + "type": "string", + "example": "jio", + "description": "Previous Network provider `jio` `airtel` `vi` `bsnl` `mtnl`. Incase of it is never ported `None` " }, - "previous_operator": { - "type": "string", - "example": "jio", - "description": "Previous Network provider `jio` `airtel` `vi` `bsnl` `mtnl`. Incase of it is never ported `None` " - }, "previous_location": { - "type": "string", - "example": "Maharashtra", - "description":"Previous Operator Circle if any , valid values are : `Kolkata `,` Mumbai `,` Delhi `,` Chennai `,` Maharashtra `,` Gujarat `,` Andhra Pradesh `,` Karnataka `,` Tamil Nadu `,` Kerala `,` Punjab `,` Haryana `,` Uttar Pradesh (East) `,` Uttar Pradesh (West) `,` Madhya Pradesh `,` Rajasthan `,` West Bengal & AN Island `,` Orissa `,` Himachal Pradesh `,` Bihar & Jharkhand `,` Assam `,` NorthEast `,` J&K `,` Uttaranchal `,` All `,` IND`" - - }, + "type": "string", + "example": "Maharashtra", + "description": "Previous Operator Circle if any , valid values are : `Kolkata `,` Mumbai `,` Delhi `,` Chennai `,` Maharashtra `,` Gujarat `,` Andhra Pradesh `,` Karnataka `,` Tamil Nadu `,` Kerala `,` Punjab `,` Haryana `,` Uttar Pradesh (East) `,` Uttar Pradesh (West) `,` Madhya Pradesh `,` Rajasthan `,` West Bengal & AN Island `,` Orissa `,` Himachal Pradesh `,` Bihar & Jharkhand `,` Assam `,` NorthEast `,` J&K `,` Uttaranchal `,` All `,` IND`" + }, "ported": { "type": "boolean", "example": "true", "description": "Parameter indicating if mobile number was ported previously" - } - + } }, - "description": "Details for listing mobile number details required for fetching plans and recharge" }, "traceId": { @@ -88,1311 +287,1588 @@ "description": "Identifier associated with this response for debug purposes" } } - }}}, - "description": "Ok" + } + } + }, + "description": "Ok" + }, + "400": { + "description": "Invalid Product Instance ID", + "headers": { + "content-length": { + "schema": { + "type": "string", + "example": "210" + } }, - "400": { - "description": "Invalid Product Instance ID", - "headers": { - "content-length": { - "schema": { - "type": "string", - "example": "210" - } - }, - "date": { - "schema": { - "type": "string", - "example": "Sun, 13 Oct 2024 20:13:17 GMT" - } - }, - "server": { - "schema": { - "type": "string", - "example": "uvicorn" - } - }, - "x-trace-id": { - "schema": { - "type": "string", - "example": "10a5b1c5-9941-4551-b76a-35be8697c59d" - } + "date": { + "schema": { + "type": "string", + "example": "Sun, 13 Oct 2024 20:13:17 GMT" } }, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "error": { - "type": "object", - "properties": { - "code": { - "type": "string", - "example": "ERR007" - }, - "failureReason": { - "type": "string", - "example": "invalid-params" - }, - "message": { - "type": "string", - "example": "Mobile number should be 10 digit" - } - } - }, - "success": { - "type": "boolean", - "example": false - }, - "trace_id": { - "type": "string", - "example": "f44e8a89-2bfe-457b-87f6-f829c373761c" - } - } - }, - "examples": { - "400": { - "value": { - "error": { - "code": "ERR009", - "failureReason": "invalid-instance-id", - "message": "Invalid Product Instance ID: 91b09564-c250-4823-a262-7464c171974ea" - }, - "success": false, - "trace_id": "10a5b1c5-9941-4551-b76a-35be8697c59d" - } - } - } + "server": { + "schema": { + "type": "string", + "example": "uvicorn" + } + }, + "x-trace-id": { + "schema": { + "type": "string", + "example": "10a5b1c5-9941-4551-b76a-35be8697c59d" } } }, - "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" - } - } - }, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "error": { - "type": "object", - "properties": { - "code": { - "type": "string", - "example": "ERR011" - }, - "failureReason": { - "type": "string", - "example": "input-params-missing" - }, - "message": { - "type": "string", - "example": "Missing required parameters: customer.billParameters.0.name" - } - } - }, - "success": { - "type": "boolean", - "example": false - }, - "trace_id": { - "type": "string", - "example": "3b0e103e-4fa8-403f-a6c9-b9dd62b82de7" - } - } - }, - "examples": { - "422": { - "value": { - "error": { - "code": "ERR011", - "failureReason": "input-params-missing", - "message": "Missing required parameters: customer.billParameters.0.name" + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "ERR007" + }, + "failureReason": { + "type": "string", + "example": "invalid-params" }, - "success": false, - "trace_id": "3b0e103e-4fa8-403f-a6c9-b9dd62b82de7" + "message": { + "type": "string", + "example": "Mobile number should be 10 digit" + } } + }, + "success": { + "type": "boolean", + "example": false + }, + "trace_id": { + "type": "string", + "example": "f44e8a89-2bfe-457b-87f6-f829c373761c" } } - } - } - }, - "500": { - "description": "Upstream API Connectivity Error", - "headers": { - "content-length": { - "schema": { - "type": "string", - "example": "183" - } - }, - "date": { - "schema": { - "type": "string", - "example": "Sun, 13 Oct 2024 20:18:38 GMT" - } - }, - "server": { - "schema": { - "type": "string", - "example": "uvicorn" - } }, - "x-trace-id": { - "schema": { - "type": "string", - "example": "98ade67b-89d8-4b55-80c8-6e41d25d3442" - } - } - }, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { + "examples": { + "400": { + "value": { "error": { - "type": "object", - "properties": { - "code": { - "type": "string", - "example": "ERR999" - }, - "failureReason": { - "type": "string", - "example": "upstream-connectivity-error" - }, - "message": { - "type": "string", - "example": "Upstream API Connectivity Error" - } - } - }, - "success": { - "type": "boolean", - "example": false + "code": "ERR009", + "failureReason": "invalid-instance-id", + "message": "Invalid Product Instance ID: 91b09564-c250-4823-a262-7464c171974ea" }, - "trace_id": { - "type": "string", - "example": "98ade67b-89d8-4b55-80c8-6e41d25d3442" - } - } - }, - "examples": { - "500": { - "value": { - "error": { - "code": "ERR999", - "failureReason": "upstream-connectivity-error", - "message": "Upstream API Connectivity Error" - }, - "success": false, - "trace_id": "98ade67b-89d8-4b55-80c8-6e41d25d3442" - } + "success": false, + "trace_id": "10a5b1c5-9941-4551-b76a-35be8697c59d" } } } } } - } - , - "parameters": [ - { - "in": "header", - "name": "X-PRODUCT-INSTANCE-ID", - "required": true, - "type": "string", - "description": "This is provided by Setu and it represents a product instance for business in their system." + }, + "422": { + "description": "Invalid Request Parameters", + "headers": { + "content-length": { + "schema": { + "type": "string", + "example": "204" + } }, - { - "in": "header", - "name": "Authorization", - "required": true, - "type": "string", - "description": "Bearer token for authorization." + "date": { + "schema": { + "type": "string", + "example": "Sun, 13 Oct 2024 20:28:16 GMT" + } + }, + "server": { + "schema": { + "type": "string", + "example": "uvicorn" + } }, - - { - "in": "body", - "name": "body", + "x-trace-id": { + "schema": { + "type": "string", + "example": "3b0e103e-4fa8-403f-a6c9-b9dd62b82de7" + } + } + }, + "content": { + "application/json": { "schema": { "type": "object", - "required": [ - "customer" - - ], "properties": { - - "customer": { - "type": "object", - "required":["billParameters"], - "properties": { - "mobile": { - "type": "string", - "example": "9192990013", - "descriiption": "The login mobile number of the initiating recharge" - }, - "billParameters": { - "type": "array", - "items": { - "type": "object", - "required":["name","value"], - "properties": { - "name": { - "type": "string", - "example": "Mobile Number", - "description": "The display name of the parameter." - }, - "value": { - "type": "string", - "example": "7066573353", - "description": "The value of the customer mobile number whose details are being fetched." - } - } - }, - "description": "Parameters for fetching Operator and Location details for mobile number." - } + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "ERR011" + }, + "failureReason": { + "type": "string", + "example": "input-params-missing" }, - "description": "The details needed for fetching operator details." + "message": { + "type": "string", + "example": "Missing required parameters: customer.billParameters.0.name" + } } + }, + "success": { + "type": "boolean", + "example": false + }, + "trace_id": { + "type": "string", + "example": "3b0e103e-4fa8-403f-a6c9-b9dd62b82de7" + } + } + }, + "examples": { + "422": { + "value": { + "error": { + "code": "ERR011", + "failureReason": "input-params-missing", + "message": "Missing required parameters: customer.billParameters.0.name" + }, + "success": false, + "trace_id": "3b0e103e-4fa8-403f-a6c9-b9dd62b82de7" + } } } } - ] - } - }, - "/fetch-plans":{ - "post": { - "tags": ["Fetch"], - "summary": "API to fetch prepaid plans for a mobile number", - "consumes": ["application/json"], - "produces": ["application/json"], - "responses": { - "200": { "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["success", "data", "trace_id"], - "properties": { - "success": { - "type": "boolean", - "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": 199, - "description": "Price of the plan in paise" - }, - "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" - } - } - }, - "description": "List of available prepaid plans" - } + } + }, + "500": { + "description": "Upstream API Connectivity Error", + "headers": { + "content-length": { + "schema": { + "type": "string", + "example": "183" + } + }, + "date": { + "schema": { + "type": "string", + "example": "Sun, 13 Oct 2024 20:18:38 GMT" + } + }, + "server": { + "schema": { + "type": "string", + "example": "uvicorn" + } + }, + "x-trace-id": { + "schema": { + "type": "string", + "example": "98ade67b-89d8-4b55-80c8-6e41d25d3442" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "ERR999" }, - "description": "Details for listing available plans for the mobile number" - }, - "traceId": { - "type": "string", - "example": "dMXpKMx4TBKsu8ro1559WeYZS21Og5", - "description": "Identifier associated with this response for debug purposes" + "failureReason": { + "type": "string", + "example": "upstream-connectivity-error" + }, + "message": { + "type": "string", + "example": "Upstream API Connectivity Error" + } } + }, + "success": { + "type": "boolean", + "example": false + }, + "trace_id": { + "type": "string", + "example": "98ade67b-89d8-4b55-80c8-6e41d25d3442" } - }}}, - "description": "Ok" - }, - "400": { - "description": "Invalid Request", - "headers": { - "content-length": { - "schema": { - "type": "string", - "example": "211" - } - }, - "date": { - "schema": { - "type": "string", - "example": "Mon, 14 Oct 2024 03:47:13 GMT" } }, - "server": { - "schema": { - "type": "string", - "example": "uvicorn" - } - }, - "x-trace-id": { - "schema": { - "type": "string", - "example": "18cc0c0d-2fa7-4c44-92bd-d15523a7e366" + "examples": { + "500": { + "value": { + "error": { + "code": "ERR999", + "failureReason": "upstream-connectivity-error", + "message": "Upstream API Connectivity Error" + }, + "success": false, + "trace_id": "98ade67b-89d8-4b55-80c8-6e41d25d3442" + } } } - }, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "error": { + } + } + } + }, + "parameters": [ + { + "in": "header", + "name": "X-PRODUCT-INSTANCE-ID", + "required": true, + "type": "string", + "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 access token recieved from token API.", + "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." + }, + { + "in": "body", + "name": "body", + "schema": { + "type": "object", + "required": [ + "customer" + ], + "properties": { + "customer": { + "type": "object", + "required": [ + "billParameters" + ], + "properties": { + "mobile": { + "type": "string", + "example": "9192990013", + "descriiption": "The login mobile number of the initiating recharge" + }, + "billParameters": { + "type": "array", + "items": { "type": "object", + "required": [ + "name", + "value" + ], "properties": { - "code": { + "name": { "type": "string", - "example": "ERR007" + "example": "Mobile Number", + "description": "The display name of the parameter." }, - "failureReason": { - "type": "string", - "example": "invalid-params" - }, - "message": { + "value": { "type": "string", - "example": "Invalid operator name viax" + "example": "7066573353", + "description": "The value of the customer mobile number whose details are being fetched." } } }, - "success": { - "type": "boolean", - "example": false - }, - "trace_id": { - "type": "string", - "example": "cb7f237d-2b6e-49da-b471-327848df324a" - } + "description": "Parameters for fetching Operator and Location details for mobile number." } }, - "examples": { - "400": { - "value": { - "error": { - "code": "ERR007", - "failureReason": "invalid-params", - "message": "Mobile number should be numeric" + "description": "The details needed for fetching operator details." + } + } + } + } + ] + } + }, + "/fetch-plans": { + "post": { + "tags": [ + "Fetch" + ], + "summary": "API to fetch prepaid plans for a mobile number", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "customer" + ], + "properties": { + "customer": { + "type": "object", + "required": [ + "billParameters", + "mobile" + ], + "properties": { + "billParameters": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "value" + ], + "properties": { + "name": { + "type": "string", + "description": "The display name of the parameter. Must be one of: 'Mobile Number', 'Operator', or 'Location'." + }, + "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." + } + } }, - "success": false, - "trace_id": "3b4feff1-76bb-4443-a398-9000f9f424b7" + "description": "Parameters for fetching prepaid plans. This array should contain three objects with names: 'Mobile Number', 'Operator', and 'Location'." + }, + "mobile": { + "type": "string", + "description": "The 10-digit mobile number of the user initiating the recharge. This may or may not be the same as the number being recharged." } }, - "Fetch Plans": { - "value": { - "error": { - "code": "ERR009", - "failureReason": "invalid-instance-id", - "message": "Invalid Product Instance ID: 91b09564-c250-4823-a262-7464c171974eaa" - }, - "success": false, - "trace_id": "18cc0c0d-2fa7-4c44-92bd-d15523a7e366" - } - } + "description": "The details needed for fetching prepaid plans." } } } - }, - "500": { - "description": "Upstream API connectivity error", - "headers": { - "content-length": { - "schema": { - "type": "string", - "example": "183" - } - }, - "date": { - "schema": { - "type": "string", - "example": "Mon, 14 Oct 2024 03:43:02 GMT" - } - }, - "server": { - "schema": { - "type": "string", - "example": "uvicorn" - } - }, - "x-trace-id": { - "schema": { - "type": "string", - "example": "e40f8f47-7bf7-4a8b-922e-193bb3c0e32c" - } - } - }, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "error": { - "type": "object", - "properties": { - "code": { - "type": "string", - "example": "ERR999" - }, - "failureReason": { - "type": "string", - "example": "upstream-connectivity-error" + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "success", + "data", + "trace_id" + ], + "properties": { + "success": { + "type": "boolean", + "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" + } + } }, - "message": { - "type": "string", - "example": "Upstream API Connectivity Error" - } + "description": "List of available prepaid plans" } }, - "success": { - "type": "boolean", - "example": false - }, - "trace_id": { - "type": "string", - "example": "e40f8f47-7bf7-4a8b-922e-193bb3c0e32c" - } - } - }, - "examples": { - "Fetch Plans": { - "value": { - "error": { - "code": "ERR999", - "failureReason": "upstream-connectivity-error", - "message": "Upstream API Connectivity Error" - }, - "success": false, - "trace_id": "e40f8f47-7bf7-4a8b-922e-193bb3c0e32c" - } + "description": "Details for listing available plans for the mobile number" + }, + "traceId": { + "type": "string", + "example": "dMXpKMx4TBKsu8ro1559WeYZS21Og5", + "description": "Identifier associated with this response for debug purposes" } } } } - } + }, + "description": "Ok" + }, + "400": { + "description": "Invalid Request", + "headers": { + "content-length": { + "schema": { + "type": "string", + "example": "211" + } }, - "parameters": [ - { - "in": "header", - "name": "X-PRODUCT-INSTANCE-ID", - "required": true, + "date": { + "schema": { "type": "string", - "description": "This is provided by Setu and it represents a product instance for business in their system." - }, - { - "in": "header", - "name": "Authorization", - "required": true, + "example": "Mon, 14 Oct 2024 03:47:13 GMT" + } + }, + "server": { + "schema": { "type": "string", - "description": "Bearer token for authorization." - }, - { - "in": "body", - "name": "body", - "schema": { - "type": "object", - "required": ["customer"], - "properties": { - - "customer": { - "type": "object", - "required":["billParameters"], - "properties": { - "mobile": { - "type": "string", - "example": "7566628882", - "description": "The login mobile number of the initiating recharge" - }, - "billParameters": { - "type": "array", - "items": [ - { + "example": "uvicorn" + } + }, + "x-trace-id": { + "schema": { + "type": "string", + "example": "18cc0c0d-2fa7-4c44-92bd-d15523a7e366" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { "type": "object", - "required": ["name", "value"], "properties": { - "name": { + "code": { "type": "string", - "example": "Mobile Number", - "description": "The display name of the parameter." + "example": "ERR007" }, - "value": { - "type": "string", - "example": "7066573353", - "description": "The value of the customer mobile number or related info like Operator and Location." - } - } - }, - { - "type": "object", - "required": ["name", "value"], - "properties": { - "name": { + "failureReason": { "type": "string", - "example": "Operator", - "description": "The display name of the parameter." + "example": "invalid-params" }, - "value": { + "message": { "type": "string", - "example": "jio", - "description": "The operator for the customer." + "example": "Invalid operator name viax" } } }, - { - "type": "object", - "required": ["name", "value"], - "properties": { - "name": { - "type": "string", - "example": "Location", - "description": "The display name of the parameter." - }, - "value": { - "type": "string", - "example": "Maharashtra", - "description": "The location or region of the customer." - } - } + "success": { + "type": "boolean", + "example": false + }, + "trace_id": { + "type": "string", + "example": "cb7f237d-2b6e-49da-b471-327848df324a" } - ], - "description": "Parameters for fetching prepaid plans, including Mobile Number, Operator, and Location." - } - }, - "description": "The details needed for fetching prepaid plans." - } + } + }, + "examples": { + "400": { + "value": { + "error": { + "code": "ERR007", + "failureReason": "invalid-params", + "message": "Mobile number should be numeric" + }, + "success": false, + "trace_id": "3b4feff1-76bb-4443-a398-9000f9f424b7" + } + }, + "Fetch Plans": { + "value": { + "error": { + "code": "ERR009", + "failureReason": "invalid-instance-id", + "message": "Invalid Product Instance ID: 91b09564-c250-4823-a262-7464c171974eaa" + }, + "success": false, + "trace_id": "18cc0c0d-2fa7-4c44-92bd-d15523a7e366" } } } - ] + } } }, - "/recharge/request":{ - "post": { - "tags": ["Recharge"], - "summary": "API to initiate a prepaid recharge request for a mobile number", - "consumes": ["application/json"], - "produces": ["application/json"], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["success", "data", "trace_id"], - "properties": { - "success": { - "type": "boolean", - "example": true, - "description": "Status of API call" - }, - "data": { - "type": "object", - "properties": { - "error": { - "type": ["string", "null"], - "example": null, - "description": "Error details if any, otherwise null" - }, - "details": { - "type": "object", - "properties": { - "mobile_number": { - "type": "string", - "example": "vi", - "description": "Mobile number associated with the transaction" - }, - "provider": { - "type": "string", - "example": "vi", - "description": "Provider name" - }, - "service_type": { - "type": "string", - "example": "M", - "description": "Service type (e.g., Mobile)" - }, - "is_postpaid": { - "type": "boolean", - "example": false, - "description": "Indicates if the mobile number is postpaid" - }, - "is_special": { - "type": "boolean", - "example": false, - "description": "Indicates if this is a special service" - } - }, - "description": "Additional details about the recharge" - }, - "amount": { - "type": "integer", - "example": 1900, - "description": "Recharge amount" + "500": { + "description": "Upstream API connectivity error", + "headers": { + "content-length": { + "schema": { + "type": "string", + "example": "183" + } }, - "transactionRefId": { - "type": "string", - "example": "CYJSTPM37695672", - "description": "Unique reference ID for the transaction" + "date": { + "schema": { + "type": "string", + "example": "Mon, 14 Oct 2024 03:43:02 GMT" + } }, - "status": { - "type": "string", - "example": "Success", - "description": "Status of the recharge transaction" + "server": { + "schema": { + "type": "string", + "example": "uvicorn" + } }, - "operatorRefId": { - "type": "string", - "example": "F3MV358Q19", - "description": "Reference ID provided by the operator" + "x-trace-id": { + "schema": { + "type": "string", + "example": "e40f8f47-7bf7-4a8b-922e-193bb3c0e32c" + } } }, - "description": "Details of the recharge transaction" - }, - "trace_id": { - "type": "string", - "example": "cu7it2r6nmjg00e34e8g", - "description": "Identifier associated with this response for debugging purposes" - } - } - } - } - }, - "description": "Ok" -} -, - "422": { - "description": "Invalid Request Parameters", - "headers": { - "content-length": { - "schema": { - "type": "string", - "example": "269" - } - }, - "date": { - "schema": { - "type": "string", - "example": "Mon, 14 Oct 2024 04:21:24 GMT" + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "ERR999" + }, + "failureReason": { + "type": "string", + "example": "upstream-connectivity-error" + }, + "message": { + "type": "string", + "example": "Upstream API Connectivity Error" + } } }, - "server": { - "schema": { - "type": "string", - "example": "uvicorn" - } + "success": { + "type": "boolean", + "example": false }, - "x-trace-id": { - "schema": { - "type": "string", - "example": "ac14888e-d56d-46e1-83cc-a408c87d32d0" - } + "trace_id": { + "type": "string", + "example": "e40f8f47-7bf7-4a8b-922e-193bb3c0e32c" } - }, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "error": { - "type": "object", - "properties": { - "code": { - "type": "string", - "example": "ERR011" - }, - "failureReason": { - "type": "string", - "example": "input-params-invalid" - }, - "message": { - "type": "string", - "example": "Value error, allowed payment modes : ['Internet Banking', 'UPI', 'Debit Card', 'Credit Card', 'Wallet']: paymentDetails.mode" - } + } + }, + "examples": { + "Fetch Plans": { + "value": { + "error": { + "code": "ERR999", + "failureReason": "upstream-connectivity-error", + "message": "Upstream API Connectivity Error" + }, + "success": false, + "trace_id": "e40f8f47-7bf7-4a8b-922e-193bb3c0e32c" + } + } + } + } + } + } + }, + "parameters": [ + { + "in": "header", + "name": "X-PRODUCT-INSTANCE-ID", + "required": true, + "type": "string", + "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 access token recieved from token API.", + "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." + }, + { + "in": "body", + "name": "body", + "schema": { + "type": "object", + "required": [ + "customer" + ], + "properties": { + "customer": { + "type": "object", + "required": [ + "billParameters" + ], + "properties": { + "mobile": { + "type": "string", + "example": "7566628882", + "description": "The login mobile number of the initiating recharge" + }, + "billParameters": { + "type": "array", + "items": [ + { + "type": "object", + "required": [ + "name", + "value" + ], + "properties": { + "name": { + "type": "string", + "example": "Mobile Number", + "description": "The display name of the parameter." + }, + "value": { + "type": "string", + "example": "7066573353", + "description": "The value of the customer mobile number or related info like Operator and Location." } - }, - "success": { - "type": "boolean", - "example": false - }, - "trace_id": { - "type": "string", - "example": "ac14888e-d56d-46e1-83cc-a408c87d32d0" } - } - }, - "examples": { - "422": { - "value": { - "error": { - "code": "ERR011", - "failureReason": "input-params-invalid", - "message": "Value error, allowed payment modes : ['Internet Banking', 'UPI', 'Debit Card', 'Credit Card', 'Wallet']: paymentDetails.mode" + }, + { + "type": "object", + "required": [ + "name", + "value" + ], + "properties": { + "name": { + "type": "string", + "example": "Operator", + "description": "The display name of the parameter." }, - "success": false, - "trace_id": "ac14888e-d56d-46e1-83cc-a408c87d32d0" + "value": { + "type": "string", + "example": "jio", + "description": "The operator for the customer." + } + } + }, + { + "type": "object", + "required": [ + "name", + "value" + ], + "properties": { + "name": { + "type": "string", + "example": "Location", + "description": "The display name of the parameter." + }, + "value": { + "type": "string", + "example": "Maharashtra", + "description": "The location or region of the customer." + } } } - } + ], + "description": "Parameters for fetching prepaid plans, including Mobile Number, Operator, and Location." } - } - }, - "500": { - "description": "Upstream API Connectivity Error", - "headers": { - "content-length": { - "schema": { + }, + "description": "The details needed for fetching prepaid plans." + } + } + } + } + ] + } + }, + "/recharge/request": { + "post": { + "tags": [ + "Recharge" + ], + "summary": "API to initiate a prepaid recharge request for a mobile number", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "customer", + "paymentDetails" + ], + "properties": { + "customer": { + "type": "object", + "required": [ + "billParameters", + "mobile" + ], + "properties": { + "billParameters": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "value" + ], + "properties": { + "name": { + "type": "string", + "description": "The display name of the parameter. Must be one of: 'Mobile Number', 'Operator', or 'Location'.", + "example": "Mobile Number" + }, + "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": "Parameters for the recharge request. This array should contain three objects with names: 'Mobile Number', 'Operator', and 'Location'." + }, + "mobile": { "type": "string", - "example": "183" + "description": "The 10-digit mobile number of the user initiating the recharge. This may or may not be the same as the number being recharged." } }, - "date": { - "schema": { + "description": "Details needed for identifying the customer and the recharge request" + }, + "paymentDetails": { + "type": "object", + "required": [ + "amount", + "mode", + "paymentParams", + "paymentRefId", + "timestamp" + ], + "properties": { + "amount": { + "type": "number", + "description": "Recharge amount in paise (1/100 of a rupee). For example, 1900 paise = 19 INR.", + "example": 1900 + }, + "mode": { "type": "string", - "example": "Mon, 14 Oct 2024 04:22:39 GMT" - } - }, - "server": { - "schema": { + "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": { + "type": "array", + "items": { + "type": "object" + }, + "description": "Additional payment parameters if required by specific payment modes. Currently, an empty array is sufficient.", + "example": [] + }, + "paymentRefId": { "type": "string", - "example": "uvicorn" - } - }, - "x-trace-id": { - "schema": { + "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." + }, + "timestamp": { "type": "string", - "example": "45c7e24c-68c2-46ab-84fc-fb2b7fe5b02b" + "description": "Timestamp of when the payment was initiated, in ISO 8601 format with timezone (e.g., '2024-02-07T13:54:00+05:30')." } - } + }, + "description": "Details of the payment for the recharge" }, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "error": { - "type": "object", - "properties": { - "code": { - "type": "string", - "example": "ERR009" - }, - "failureReason": { - "type": "string", - "example": "invalid-instance-id" - }, - "message": { - "type": "string", - "example": "Invalid Product Instance ID: 91b09564-c250-4823-a262-7464c171974eaa" - } + "refId": { + "type": "string", + "description": "Optional unique reference ID for the recharge request. If not provided, the system will use paymentRefId as the reference." + } + } + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "success", + "data", + "trace_id" + ], + "properties": { + "success": { + "type": "boolean", + "example": true, + "description": "Status of API call" + }, + "data": { + "type": "object", + "properties": { + "error": { + "type": [ + "string", + "null" + ], + "example": null, + "description": "Error details if any, otherwise null" + }, + "details": { + "type": "object", + "properties": { + "mobile_number": { + "type": "string", + "example": "7066573353", + "description": "Mobile number associated with the transaction" + }, + "provider": { + "type": "string", + "example": "vi", + "description": "Provider name" + }, + "service_type": { + "type": "string", + "example": "M", + "description": "Represents the service type. Always set to 'M' for Mobile." + }, + "is_postpaid": { + "type": "boolean", + "example": false, + "description": "Indicates if the mobile number is postpaid" + }, + "is_special": { + "type": "boolean", + "example": false, + "description": "Indicates if this is a special service" } }, - "success": { - "type": "boolean", - "example": false - }, - "trace_id": { - "type": "string", - "example": "8ed9fff1-19fb-4ce5-8072-22b02a314d1f" - } + "description": "Additional details about the recharge" + }, + "amount": { + "type": "integer", + "example": 1900, + "description": "Recharge amount in paise" + }, + "transactionRefId": { + "type": "string", + "example": "CYJSTPM37695672", + "description": "Unique reference ID for the transaction" + }, + "status": { + "type": "string", + "example": "Success", + "description": "Status of the recharge transaction.\n\nPossible values:\n- `Success`\n- `Processing`\n- `Failure`" + }, + "operatorRefId": { + "type": "string", + "example": "F3MV358Q19", + "description": "Reference ID provided by the operator" } }, - "examples": { - "400": { - "value": { - "error": { - "code": "ERR999", - "failureReason": "upstream-connectivity-error", - "message": "Upstream API Connectivity Error" - }, - "success": false, - "trace_id": "45c7e24c-68c2-46ab-84fc-fb2b7fe5b02b" - } + "description": "Details of the recharge transaction" + }, + "trace_id": { + "type": "string", + "example": "cu7it2r6nmjg00e34e8g", + "description": "Identifier associated with this response for debugging purposes" + } + } + } + } + }, + "description": "Ok" + }, + "422": { + "description": "Invalid Request Parameters", + "headers": { + "content-length": { + "schema": { + "type": "string", + "example": "269" + } + }, + "date": { + "schema": { + "type": "string", + "example": "Mon, 14 Oct 2024 04:21:24 GMT" + } + }, + "server": { + "schema": { + "type": "string", + "example": "uvicorn" + } + }, + "x-trace-id": { + "schema": { + "type": "string", + "example": "ac14888e-d56d-46e1-83cc-a408c87d32d0" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "ERR011" }, - "500": { - "value": { - "error": { - "code": "ERR005", - "failureReason": "duplicate-payment-ref-id", - "message": "Duplicate Payment Reference ID : TEST6291DD4004750702202402" - }, - "success": false, - "trace_id": "3d7bfc34-0f80-43c2-b103-38633bb74f8b" - } + "failureReason": { + "type": "string", + "example": "input-params-invalid" + }, + "message": { + "type": "string", + "example": "Value error, allowed payment modes : ['Internet Banking', 'UPI', 'Debit Card', 'Credit Card', 'Wallet']: paymentDetails.mode" } } + }, + "success": { + "type": "boolean", + "example": false + }, + "trace_id": { + "type": "string", + "example": "ac14888e-d56d-46e1-83cc-a408c87d32d0" + } + } + }, + "examples": { + "422": { + "value": { + "error": { + "code": "ERR011", + "failureReason": "input-params-invalid", + "message": "Value error, allowed payment modes : ['Internet Banking', 'UPI', 'Debit Card', 'Credit Card', 'Wallet']: paymentDetails.mode" + }, + "success": false, + "trace_id": "ac14888e-d56d-46e1-83cc-a408c87d32d0" } } } + } + } + }, + "500": { + "description": "Upstream API Connectivity Error", + "headers": { + "content-length": { + "schema": { + "type": "string", + "example": "183" + } }, - "parameters": [ - { - "in": "header", - "name": "X-PRODUCT-INSTANCE-ID", - "required": true, + "date": { + "schema": { "type": "string", - "description": "This is provided by Setu and it represents a product instance for business in their system." - }, - { - "in": "header", - "name": "Authorization", - "required": true, + "example": "Mon, 14 Oct 2024 04:22:39 GMT" + } + }, + "server": { + "schema": { "type": "string", - "description": "Bearer token for authorization." - }, - { - "in": "body", - "name": "body", - "schema": { - "type": "object", - "required": ["customer", "paymentDetails"], - "properties": { - "customer": { - "type": "object", - "required":["billParameters","mobile"], - "properties": { - "billParameters": { - "type": "array", - "items": { - "type": "object", - "required":["name","value"], - "properties": { - "name": { - "type": "string", - "example": "Mobile Number", - "description": "The display name of the parameter." - }, - "value": { - "type": "string", - "example": "7066573353", - "description": "The value of the customer mobile number or related info like Operator and Location." - } - } - }, - "description": "Parameters for the recharge request, including Mobile Number, Operator, and Location." - }, - "mobile": { - "type": "string", - "example": "6291400475", - "description": "The mobile number initiating the recharge" - } + "example": "uvicorn" + } + }, + "x-trace-id": { + "schema": { + "type": "string", + "example": "45c7e24c-68c2-46ab-84fc-fb2b7fe5b02b" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "ERR009" }, - "description": "Details needed for identifying the customer and the recharge request" + "failureReason": { + "type": "string", + "example": "invalid-instance-id" + }, + "message": { + "type": "string", + "example": "Invalid Product Instance ID: 91b09564-c250-4823-a262-7464c171974eaa" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "trace_id": { + "type": "string", + "example": "8ed9fff1-19fb-4ce5-8072-22b02a314d1f" + } + } + }, + "examples": { + "400": { + "value": { + "error": { + "code": "ERR999", + "failureReason": "upstream-connectivity-error", + "message": "Upstream API Connectivity Error" + }, + "success": false, + "trace_id": "45c7e24c-68c2-46ab-84fc-fb2b7fe5b02b" + } + }, + "500": { + "value": { + "error": { + "code": "ERR005", + "failureReason": "duplicate-payment-ref-id", + "message": "Duplicate Payment Reference ID : TEST6291DD4004750702202402" }, - "paymentDetails": { + "success": false, + "trace_id": "3d7bfc34-0f80-43c2-b103-38633bb74f8b" + } + } + } + } + } + } + }, + "parameters": [ + { + "in": "header", + "name": "X-PRODUCT-INSTANCE-ID", + "required": true, + "type": "string", + "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 access token recieved from token API.", + "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." + }, + { + "in": "body", + "name": "body", + "schema": { + "type": "object", + "required": [ + "customer", + "paymentDetails" + ], + "properties": { + "customer": { + "type": "object", + "required": [ + "billParameters", + "mobile" + ], + "properties": { + "billParameters": { + "type": "array", + "items": { "type": "object", - "required":["amount","mode","paymentRefId","paymentParams","timestamp"], + "required": [ + "name", + "value" + ], "properties": { - "amount": { - "type": "number", - "example": 2900, - "description": "Recharge amount in paise (e.g., 2900 paise = 29 INR)" - }, - "mode": { - "type": "string", - "example": "Internet Banking", - "description": "The payment mode used for the recharge" - }, - "paymentParams": { - "type": "array", - "items": { - "type": "object" - }, - "description": "Additional payment parameters in case any" - }, - "paymentRefId": { + "name": { "type": "string", - "example": "TEST6291DD4004750702202402", - "description": "Reference ID for the payment transaction" + "example": "Mobile Number", + "description": "The display name of the parameter." }, - "timestamp": { + "value": { "type": "string", - "example": "2024-02-07T13:54:00+05:30", - "description": "Timestamp of when the payment was initiated" + "example": "7066573353", + "description": "The value of the customer mobile number or related info like 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" }, - "description": "Details of the payment for the recharge" + { + "name": "Location", + "value": "Maharashtra" + } + ] + }, + "mobile": { + "type": "string", + "example": "6291400475", + "description": "The mobile number initiating the recharge" + } + }, + "description": "Details needed for identifying the customer and the recharge request" + }, + "paymentDetails": { + "type": "object", + "required": [ + "amount", + "mode", + "paymentRefId", + "paymentParams", + "timestamp" + ], + "properties": { + "amount": { + "type": "number", + "example": 1900, + "description": "Recharge amount in paise (1/100 of a rupee). Must be a positive integer value representing the amount in paise." + }, + "mode": { + "type": "string", + "example": "Internet Banking", + "description": "The payment mode used for the recharge. Must be one of: 'Internet Banking', 'UPI', 'Debit Card', 'Credit Card', or 'Wallet'." + }, + "paymentParams": { + "type": "array", + "items": { + "type": "object" }, - "refId": { - "type": "string", - "example": "REFIDTEST6291DD4004750702202402", - "description": "Unique reference ID for the recharge request" - } + "description": "Additional payment parameters in case any" + }, + "paymentRefId": { + "type": "string", + "example": "TEST6291DD4004750702202402", + "description": "Reference ID for the payment transaction" + }, + "timestamp": { + "type": "string", + "example": "2024-02-07T13:54:00+05:30", + "description": "Timestamp of when the payment was initiated, in ISO 8601 format with timezone. Format: YYYY-MM-DDThh:mm:ss+TZ (e.g., '2024-02-07T13:54:00+05:30')." } - } - } - ] - } - }, - "/recharge/status": { - "post": { - "tags": ["Recharge"], - "summary": "API to check the status of a prepaid recharge transaction", - "consumes": ["application/json"], - "produces": ["application/json"], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["success", "data", "trace_id"], - "properties": { - "success": { - "type": "boolean", - "example": true, - "description": "Status of API call" - }, - "data": { - "type": "object", - "properties": { - "error": { - "type": ["string", "null"], - "example": null, - "description": "Error details if any, otherwise null" - }, - "details": { - "type": "object", - "properties": { - "mobile_number": { - "type": "string", - "example": "vi", - "description": "Mobile number associated with the transaction" - }, - "provider": { - "type": "string", - "example": "vi", - "description": "Provider name" - }, - "service_type": { - "type": "string", - "example": "M", - "description": "Service type (e.g., Mobile)" - }, - "is_postpaid": { - "type": "boolean", - "example": false, - "description": "Indicates if the mobile number is postpaid" }, - "is_special": { - "type": "boolean", - "example": false, - "description": "Indicates if this is a special service" - } + "description": "Details of the payment for the recharge" }, - "description": "Additional details about the recharge" - }, - "amount": { - "type": "integer", - "example": 1900, - "description": "Recharge amount" - }, - "transactionRefId": { - "type": "string", - "example": "CYJSTPM37695672", - "description": "Unique reference ID for the transaction" - }, - "status": { - "type": "string", - "example": "Success", - "description": "Status of the recharge transaction" - }, - "operatorRefId": { - "type": "string", - "example": "F3MV358Q19", - "description": "Reference ID provided by the operator" + "refId": { + "type": "string", + "example": "REFIDTEST6291DD4004750702202402", + "description": "Optional unique reference ID for the recharge request. If provided, must be an alphanumeric string with length between 5 and 40 characters." + } } - }, - "description": "Details of the recharge transaction" - }, - "trace_id": { - "type": "string", - "example": "cu7it2r6nmjg00e34e8g", - "description": "Identifier associated with this response for debugging purposes" + } } - } + ] } - } - }, - "description": "Ok" -} - - - }, - "parameters": [ - - { - "in": "header", - "name": "X-PRODUCT-INSTANCE-ID", - "required": true, - "type": "string", - "description": "This is provided by Setu and it represents a product instance for business in their system." - }, - { - "in": "header", - "name": "Authorization", + }, + "/recharge/status": { + "post": { + "tags": [ + "Recharge" + ], + "summary": "API to check the status of a prepaid recharge transaction", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "requestBody": { "required": true, - "type": "string", - "description": "Bearer token for authorization." - }, - { - "in": "body", - "name": "body", - "schema": { - "type": "object", - "required": ["paymentRefId"], - "properties": { - "paymentRefId": { - "type": "string", - "example": "TEST62XD4XX04750702202402", - "description": "Reference ID for the payment transaction whose status is being queried" - } - } - } - } - ] - } - }, - "/wallet/balance": { - "get": { - "tags": ["Wallet"], - "summary": "API to fetch the balance of the wallet", - "produces": ["application/json"], - "responses": { - "200": { "content": { "application/json": { - "schema": { - "type": "object", - "required": ["success", "data", "trace_id"], - "properties": { - "success": { - "type": "boolean", - "example": true, - "description": "Status of the API call" - }, - "data": { + "schema": { "type": "object", + "required": [ + "paymentRefId" + ], "properties": { - "balance": { - "type": "number", - "example": 1500.75, - "description": "Current wallet balance available" - }, - "currency": { + "paymentRefId": { "type": "string", - "example": "INR", - "description": "Currency of the wallet balance" + "description": "Reference ID for the payment transaction whose status is being queried. This is the same paymentRefId used in the original recharge request." } - }, - "description": "Details of the wallet balance" - }, - "traceId": { - "type": "string", - "example": "dMXpKMx4TBKsu8ro1559WeYZS21Og5", - "description": "Identifier associated with this response for debug purposes" + } } } - }}}, - "description": "Response containing the wallet balance details" - } - }, - "parameters": [ - { - "in": "header", - "name": "X-PRODUCT-INSTANCE-ID", - "required": true, - "type": "string", - "description": "This is provided by Setu and it represents a product instance for business in their system." - }, - { - "in": "header", - "name": "Authorization", - "required": true, - "type": "string", - "description": "Bearer token for authorization." - } - ] - } - }, - "/transaction": { - "get": { - "tags": ["Transaction"], - "summary": "API to fetch transaction details", - "produces": ["application/json"], - "parameters": [ - { - "in": "query", - "name": "limit", - "required": false, - "type": "integer", - "example": 1, - "description": "Maximum number of transactions to return" - }, - { - "in": "query", - "name": "page_number", - "required": false, - "type": "integer", - "example": 18, - "description": "Page number of the result" - }, - { - "in": "query", - "name": "operator", - "required": false, - "type": "string", - "example": "Jio", - "description": "Operator name to filter transactions" - }, - { - "in": "query", - "name": "start_date", - "required": false, - "type": "string", - "format": "date", - "example": "2024-10-07", - "description": "Start date for transaction history in YYYY-MM-DD format" - }, - { - "in": "query", - "name": "end_date", - "required": false, - "type": "string", - "format": "date", - "example": "2024-10-09", - "description": "End date for transaction history in YYYY-MM-DD format" - }, - { - "in": "header", - "name": "X-PRODUCT-INSTANCE-ID", - "required": true, - "type": "string", - "description": "This is provided by Setu and it represents a product instance for business in their system." + } }, - { - "in": "header", - "name": "Authorization", - "required": true, - "type": "string", - "description": "Bearer token for authorization." - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["success", "data", "trace_id"], - "properties": { - "success": { - "type": "boolean", - "example": true, - "description": "Status of the API call" - }, - "data": { - "type": "array", - "items": { + "responses": { + "200": { + "content": { + "application/json": { + "schema": { "type": "object", + "required": [ + "success", + "data", + "trace_id" + ], "properties": { - "transaction_id": { - "type": "string", - "example": "TXN123456789", - "description": "Unique identifier for the transaction" + "success": { + "type": "boolean", + "example": true, + "description": "Status of API call" }, - "mobile_number": { - "type": "string", - "example": "7066573353", - "description": "Mobile number involved in the transaction" + "data": { + "type": "object", + "properties": { + "error": { + "type": [ + "string", + "null" + ], + "example": null, + "description": "Error details if any, otherwise null" + }, + "details": { + "type": "object", + "properties": { + "mobile_number": { + "type": "string", + "example": "7066573353", + "description": "Mobile number associated with the transaction" + }, + "provider": { + "type": "string", + "example": "vi", + "description": "Provider name" + }, + "service_type": { + "type": "string", + "example": "M", + "description": "Represents the service type. Always set to 'M' for Mobile." + }, + "is_postpaid": { + "type": "boolean", + "example": false, + "description": "Indicates if the mobile number is postpaid" + }, + "is_special": { + "type": "boolean", + "example": false, + "description": "Indicates if this is a special service" + } + }, + "description": "Additional details about the recharge" + }, + "amount": { + "type": "integer", + "example": 1900, + "description": "Recharge amount in paise" + }, + "transactionRefId": { + "type": "string", + "example": "CYJSTPM37695672", + "description": "Unique reference ID for the transaction" + }, + "status": { + "type": "string", + "example": "Success", + "description": "Status of the recharge transaction.\n\nPossible values:\n- `Success`\n- `Processing`\n- `Failure`" + }, + "operatorRefId": { + "type": "string", + "example": "F3MV358Q19", + "description": "Reference ID provided by the operator" + } + }, + "description": "Details of the recharge transaction" }, - "operator": { + "trace_id": { "type": "string", - "example": "Jio", - "description": "Operator name" + "example": "cu7it2r6nmjg00e34e8g", + "description": "Identifier associated with this response for debugging purposes" + } + } + } + } + }, + "description": "Ok" + } + }, + "parameters": [ + { + "in": "header", + "name": "X-PRODUCT-INSTANCE-ID", + "required": true, + "type": "string", + "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 access token recieved from token API.", + "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." + }, + { + "in": "body", + "name": "body", + "schema": { + "type": "object", + "required": [ + "paymentRefId" + ], + "properties": { + "paymentRefId": { + "type": "string", + "example": "TEST62XD4XX04750702202402", + "description": "Reference ID for the payment transaction whose status is being queried" + } + } + } + } + ] + } + }, + "/wallet/balance": { + "get": { + "tags": [ + "Wallet" + ], + "summary": "API to fetch the balance of the wallet", + "produces": [ + "application/json" + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "success", + "data", + "trace_id" + ], + "properties": { + "success": { + "type": "boolean", + "example": true, + "description": "Status of the API call" }, - "amount": { - "type": "number", - "example": 2900, - "description": "Transaction amount" + "data": { + "type": "object", + "properties": { + "balance": { + "type": "number", + "example": 1500.75, + "description": "Current wallet balance available" + }, + "currency": { + "type": "string", + "example": "INR", + "description": "Currency of the wallet balance" + } + }, + "description": "Details of the wallet balance" }, - "status": { + "traceId": { "type": "string", - "example": "SUCCESS", - "description": "Status of the transaction" + "example": "dMXpKMx4TBKsu8ro1559WeYZS21Og5", + "description": "Identifier associated with this response for debug purposes" + } + } + } + } + }, + "description": "Response containing the wallet balance details" + } + }, + "parameters": [ + { + "in": "header", + "name": "X-PRODUCT-INSTANCE-ID", + "required": true, + "type": "string", + "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 access token recieved from token API.", + "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." + } + ] + } + }, + "/transaction": { + "get": { + "tags": [ + "Transaction" + ], + "summary": "API to fetch transaction details", + "produces": [ + "application/json" + ], + "parameters": [ + { + "in": "query", + "name": "limit", + "required": false, + "type": "integer", + "example": 1, + "description": "Maximum number of transactions to return per page. Default is 100." + }, + { + "in": "query", + "name": "page_number", + "required": false, + "type": "integer", + "example": 18, + "description": "Page number for pagination. Starts from 1. Default is 1 if not specified." + }, + { + "in": "query", + "name": "operator", + "required": false, + "type": "string", + "example": "Jio", + "description": "Filter transactions by operator name. Must be one of: 'Jio', 'Airtel', 'Vi', 'BSNL', or 'MTNL'." + }, + { + "in": "query", + "name": "start_date", + "required": false, + "type": "string", + "format": "date", + "example": "2024-10-07", + "description": "Start date for transaction history in YYYY-MM-DD format. Cannot be more than 90 days in the past." + }, + { + "in": "query", + "name": "end_date", + "required": false, + "type": "string", + "format": "date", + "example": "2024-10-09", + "description": "End date for transaction history in YYYY-MM-DD format. Cannot be in the future or before start_date." + }, + { + "in": "header", + "name": "X-PRODUCT-INSTANCE-ID", + "required": true, + "type": "string", + "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 access token recieved from token API.", + "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "success", + "data", + "trace_id" + ], + "properties": { + "success": { + "type": "boolean", + "example": true, + "description": "Status of the API call" }, - "timestamp": { + "data": { + "type": "array", + "items": { + "type": "object", + "properties": { + "transaction_id": { + "type": "string", + "example": "TXN123456789", + "description": "Unique identifier for the transaction" + }, + "mobile_number": { + "type": "string", + "example": "7066573353", + "description": "Mobile number involved in the transaction" + }, + "operator": { + "type": "string", + "example": "Jio", + "description": "Operator name" + }, + "amount": { + "type": "number", + "example": 2900, + "description": "Transaction amount in paise" + }, + "status": { + "type": "string", + "example": "SUCCESS", + "description": "Status of the transaction" + }, + "timestamp": { + "type": "string", + "format": "date-time", + "example": "2024-10-07T13:54:00+05:30", + "description": "Timestamp of when the transaction occurred" + } + } + }, + "description": "List of transaction details" + }, + "traceId": { "type": "string", - "format": "date-time", - "example": "2024-10-07T13:54:00+05:30", - "description": "Timestamp of when the transaction occurred" + "example": "dMXpKMx4TBKsu8ro1559WeYZS21Og5", + "description": "Identifier associated with this response for debug purposes" } } - }, - "description": "List of transaction details" - }, - "traceId": { - "type": "string", - "example": "dMXpKMx4TBKsu8ro1559WeYZS21Og5", - "description": "Identifier associated with this response for debug purposes" + } } - } - }}}, - "description": "Response containing the list of transactions" + }, + "description": "Response containing the list of transactions" + } } } } - } - }, + }, "components": { "schemas": { "fetchTokenRequest": { @@ -1412,7 +1888,10 @@ "fetchTokenResponse": { "allOf": [ { - "required": ["expiresIn", "token"], + "required": [ + "expiresIn", + "token" + ], "type": "object", "properties": { "expiresIn": { @@ -1426,7 +1905,10 @@ } }, { - "required": ["success", "traceId"], + "required": [ + "success", + "traceId" + ], "type": "object", "properties": { "success": { @@ -1442,7 +1924,10 @@ ] }, "successAndTracerDetails": { - "required": ["success", "traceId"], + "required": [ + "success", + "traceId" + ], "type": "object", "properties": { "success": { @@ -1478,8 +1963,8 @@ } } } - } + } } - }, - "x-original-swagger-version": "2.0" + }, + "x-original-swagger-version": "2.0" }