Overview

Welcome to Tymk Software Recharge Services Developer Documentation. You'll find comprehensive guides and documentation to help you start working with Recharge Services as quickly as possible, as well as support if you get stuck. Let's jump right in!

Index

  • Get Service Provider Operator.
  • Get Operator & Circle from Mobile Prepaid & Postpaid
  • Do Recharge
  • Get Balance

Base Urls

Type Request Url
Test http://testapi.tymksoftwares.in/api/recharge/v1/
Live http://tymksoftwares.in/api/recharge/v1/

Services

Service Id Name
2 Prepaid Recharge
3 Postpaid Bill Payment
4 DTH Recharge
5 Data Card Recharge
6 Electricity Bill
7 Gas Bill
8 Insurance
13 Recharge Plans

Service Provider Operators

  • Call for fetching the list of active service providers along with the respective properties.
  • Send GET request to /operators

Request Parameters

Keyword Type Requirement Description
key string mandatory API Key received from Developer Panel
service_id integer mandatory Recharge Service Id

Response

{
    "operators":[
        {
            "id": "1",
            "name": "Airtel",
        }, {
            "id": "2",
            "name": "BSNL",
        }
    ]
}

Telecom Circles

  • Call for fetching the list of active telecom circles along with the respective properties.
  • Only for Prepaid Recharge Service.
  • Send GET request to /circles

Request Parameters

Keyword Type Requirement Description
key string mandatory API Key received from Developer Panel
service_id integer mandatory Recharge Service Id

Response

{
    "circles":[
        {
            "id": "1",
            "name": "Maharashtra"
        },
        {
            "id": "2",
            "name": "Rajasthan"
        },
        {
            "id": "3",
            "name": "Gujarat"
        }
    ]
}

Operators & Circles

  • Call for fetching the data of Operator & Circle from Customer Mobile number.
  • Send GET request to /operator-circle

Request Parameters

Keyword Type Requirement Description
key string mandatory API Key received from Developer Panel
mobile integer mandatory Customer's 10 Digit Mobile Number
service_id integer mandatory Recharge Service Id

Response Success

{
    "status": true,
    "operator":{
        "id": 1,
        "name": "Airtel"
    },
    "circle": {
        "id": 4,
        "name": "Rajasthan"
    }
}

Response Fail

{
    "status": false,
    "errors": [
        {
            "code": 303,
            "message" : "No Circle & Operator found for this Mobile Number"
        }
    ]
}

Attempt Recharge

  • Send the data for recharge transactions.
  • Here recharge_status only for Testing Api.
  • Send POST request to /attempt
  • Check Error Codes for recharge attempt response (Here)

Request Parameters

Keyword Type Requirement Description
key string mandatory Api Key received from Developer Panel
recharge_status integer optional Request for appropriate Response
1: Success, 2: Pending, 3: Failed
service_id integer mandatory Recharge Service Id
order_id string mandatory Unique Order ID from Your App / Website
account string mandatory Mobile No / Customer Id / Insurance Policy Number
operator_id integer mandatory Operator Code given by us (See How)
unit string optional Electricity Unit / Area Code is Mandatory for MSEB
(Maharashtra State Electricity Board)
dob date optional Date of birth is Mandatory for Insurance Billing.
amount integer mandatory Recharge / Bill Amount in Paisa

Responses

  • Insufficient Balance
  • Recharge Response
1. Insufficient Balance
If Company / Agency has no enough balance for current transaction, we will response.
(see below example)
{
    "status": false,
    "errors": [
        {
            "code": 103,
            "message" : "Company / Agency does not have enough balance for this transaction"
        }
    ]
}

2. Recharge Response

Response Parameters Success

Keyword Type Description
status boolean true
response string Success or Pending
service_id integer Recharge Service Id
order_id string Unique Order ID from Your App / Website
op_txn_id string Operator Transaction Id
reference_id string Unique Reference Id (Further Communication or Support)
amount integer Recharge / Bill Amount in Paisa
commission integer Commission received in Paisa
message string Recharge Message
opening_balance integer Company Wallet balance before transaction in Paisa
closing_balance integer Company Wallet balance after transaction in Paisa

Response Code Success

{
    "status": true,
    "response": "Success",
    "service_id": 2,
    "order_id": 741852,
    "op_txn_id": "wsuid904",
    "reference_id": "1151105204517NQPZD",
    "amount": 10000,
    "commission": 100,
    "account": "9876543210",
    "message": "Transaction Successful",
    "opening_balance": 98005,
    "closing_balance": 88005
}

Response Parameters fail

Keyword Type Description
status boolean false
service_id integer Recharge Service Id
order_id string Unique Order ID from Your App / Website
reference_id string Unique Reference Id (Further Communication or Support)
amount integer Recharge / Bill Amount in Paisa
message string Recharge Message

Response Code fail

{
    "status": false,
    "response": "Failed",
    "service_id": 2,
    "order_id": 741852,
    "reference_id": "1151105204517NQPZD",
    "amount": 10000,
    "message": "Transaction Failed",
    "errors": [
        {
            "code": 305,
            "message" : "Invalid account number"
        }
    ]
}

Get Recharge Status

  • Get Recharge status by reference_id
  • Send GET request to /status
Keyword Type Requirement Description
key string mandatory API Key received from Developer Panel
reference_id string mandatory Reference ID received from attempt recharge response

Response Code would be same as attempt recharge response code (See How)


Recharge Plans

  • Currently, We are providing only Prepaid Recharge Operator Plans
  • Send POST request to plans/prepaid
  • Here, Plan Identifier is optional. Without Plan Identifier you will get All Plans in response
Keyword Type Requirement Description
key string mandatory API Key received from Developer Panel
service_id integer mandatory Recharge Plan Service Id (Details)
operator_id integer mandatory Operator Id for Respective Operator (See How)
circle_id integer mandatory Circle Id for Respective Circle (See How)
plan_id integer optional Plan Identifier for Required Plan (Details)

Response Parameters Success

Keyword Type Description
status boolean true
operator array Operator Details
circle array Circle Details
plans array
plans.name string Plan Name
plans.details array Plan Details
plans.details.amount integer Amount
plans.details.talk_time string Talktime
plans.details.validity string Plan Validity
plans.details.description.short string Short Description
plans.details.description.long string Long Description

Response Code Success

{
    "status": true,
    "operator": {
        "id": 12,
        "name": "BSNL"
    },
    "circle": {
        "id": 6,
        "name": "Gujarat"
    },
    "plans": [
        {
            "name": "Top up",
            "details": [
                {
                    "amount": "10",
                    "talk_time": "7.7",
                    "validity": "N.A",
                    "description": {
                        "short": "Recharge of Rs. 10 by BSNL",
                        "long": "Talktime of Rs. 7.7 for Rs. 10 recharge by BSNL"
                    }
                },
                ...
            ]
        },
        {
            "name": "3G Data",
            "details": [
                {
                    "amount": "3",
                    "talk_time": "N.A",
                    "validity": "1 day",
                    "description": {
                        "short": "Recharge of Rs. 3 by BSNL",
                        "long": "Data charges @ 9paisa/MB from 02.00AM to 06.00AM"
                    }
                },
                ...
            ]
        }
    ]
}

Response Code Fail

{
    "status": false,
    "errors": {
        "code": 309,
        "message": "This Plan not available for this Operator"
    }
}

Recharge Plans Identifiers

Prepaid
Id Name
1 Top up
2 2G Data
3 3G Data
4 Full Talktime
5 SMS
6 Local
7 STD
8 ISD
9 Roaming
10 Other
11 Validity
12 Plan
13 FRC

Get Balance

  • Get Company Balance
  • Send GET request to https://testapi.tymksoftwares.in/api/balance or https://tymksoftwares.in/api/balance
Keyword Type Requirement Description
key string mandatory API Key received from Developer Panel

Response Code

{
    "status": true,
    "balance": 10000, // In Paisa
}

Error Codes

  • errors key would be returned with response for the below mentioned errors

API Level

Code Message
100 Some services are not working properly, contact (support)
101 Invalid API Authentication Key
102 Account has been suspended, please contact support
103 Company / Agency does not have enough balance for this transaction
104 Too many attempts, please slow down the request.
If request rate limit is exceeded per IP Address

Recharge Level

Code Message
301 Invalid Service Identifier or not a Recharge Service Identifier
302 Company or Client does not have access to this service
303 No Circle & Operator found for this Mobile Number
304 Currently we are unable to provide Prepaid Recharge service for Vodafone
305 Invalid account number
306 Invalid recharge amount
307 Duplicate recharge request, Try after 15 Minutes
308 Unknown error, contact support
311 Electricity Unit / Area Code is Mandatory for MSEB Bill Payment

Recharge Plan Level

Code Message
309 This Plan not available for this Operator
310 No any Plans available for this Operator
{
    "errors": [
        {
            "code": 101,
            "message" : "Invalid API Authentication Key"
        }
    ]
}

Support

  • Email: sid@tymkgroup.com / support@tymksoftwares.in
  • Phone: 9510447773