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