API - TutomGateway

These top-up APIs are created to refill or top up mobile phone services provided by China Mobile, China Unicom and China Telecom. Recharging requests are normally completed with seconds, but sometimes it could take up to 24 hours due to network or system issues with related operators. Please follow the following steps if you would like to use them:

Contact support@tutompay.com about your requirements.
Sign a Chinese mobile operator airtime transfer agreement with Unimobile
Receive account login/password and keys from Unimobile. Please change your password once you are able to login
Make an initial deposit based on the commerical agreement
Visit www.mychinaunicom.com/gateway
Check your account balance
Configure white listed IP addresses
Integrate API calls based on the developer resources
Start using it

Get all airtime refill product list

Access URL: https://www.mychinaunicom.com/gateway/refillapi/List

Http Method: GET/POST

Request Parameters:

Field Name	Type	Required	Max Length	Definition
appkey	String	Yes	64	AppKey

Request Example:

https://www.mychinaunicom.com/gateway/refillapi/List?appkey=7bf7d2fd6d9c5012ae7c82ab7617

Response Parameters:

Field Name	Type	Max Length	Definition
response_code	Integer	5	0 = Success. and non-zero = an error occurred. Possible values: See Response Code Messages.
response_text	String	1024	For non-zero ResponseCode, this will be a description of the error that occurred. See Response Code Messages.
facevalue	String	3	Face value. Available options: 30 \| 50 \| 100 \| 300
operator	String	50	China Telecom \| China Unicom \| China Mobile
price	Currency	12	The price of this product. E.g: 10.86
currency	String	3	E.g: USD \| CNY

Response Example:

Error

{"response_code":"11001","response_text":"appkey is not valid"}

Success

{"response_code":"0","response_text":"Success.","productlist":[{"facevalue":"100""operator":"China Telecom","price":"16.3200","currency":"USD"},{"facevalue":"100""operator":"China Unicom","price":"16.3200","currency":"USD"},{"facevalue":"100""operator":"China Mobile","price":"16.3200","currency":"USD"}]}

Get mobile number that is good for airtime refill

Access URL: https://www.mychinaunicom.com/gateway/refillapi/ListByPhone

Http Method: GET/POST

Request Parameters:

Field Name	Type	Required	Max Length	Definition
mdn	String	Yes	11	Mobile phone number. E.g: 18610865680
appkey	String	Yes	64	AppKey

Request Example:

https://www.mychinaunicom.com/gateway/refillapi/ListByPhoneNo?appkey=7bf7d2fd6d9c5012ae7c82ab7617

Response Parameters:

Field Name	Type	Max Length	Definition
response_code	Integer	5	0 = Success. and non-zero = an error occurred. Possible values: See Response Code Messages.
response_text	String	1024	For non-zero ResponseCode, this will be a description of the error that occurred. See Response Code Messages.
operator_id	Integer	10	10000(China Telecom) \| 10010(China Unicom) \| 10086(China Mobile)
operator_name	String	50	China Telecom \| China Unicom \| China Mobile
facevalue	Integer	3	Face value. Available options: 30 \| 50 \| 100 \| 300
price	Currency	12	The price of this product. E.g: 10.86
currency	String	3	E.g: USD \| CNY

Response Example:

Error

{"response_code":"11001","response_text":"appkey is not valid"}

Success

{"response_code":"0","response_text":"Success.","operator_id":"10010","operator_name":"China Unicom","productlist":[{"facevalue":"50","price":"8.1600","currency":"USD"},{"facevalue":"100","price":"16.3200","currency":"USD"}]}

Submit recharge request, create order

Access URL: https://www.mychinaunicom.com/gateway/refillapi/OrderCreate

Http Method: GET/POST

Usage Notes: If there is network issues such as http errors or return code is 11708, please contact system support at support@tutompay.com! DO NOT treate order as failure until you contact system support!

Request Parameters:

Field Name	Type	Required	Max Length	Definition
mdn	String	Yes	11	Mobile phone number. E.g: 18610865680
facevalue	Integer	Yes	3	Face value. Available options: 30 \| 50 \| 100 \| 300
orderid	String	Yes	32	User's order id. Minimum length: 5.
appkey	String	Yes	64	AppKey
sign	String	Yes	32	MD5(openId + appkey + orderid + mdn + facevalue).

Request Example:

https://www.mychinaunicom.com/gateway/refillapi/OrderCreate?appkey=7bf7d2fd6d9c5012ae7c82ab7617&orderid=test10001

&sign=098F6BCD4621D373CADE4E832627B4F6&mdn=18610865680&facevalue=100

Response Parameters:

Field Name	Type	Max Length	Definition
response_code	Integer	5	0 = Success. and non-zero = an error occurred. Possible values: See Response Code Messages.
response_text	String	1024	For non-zero ResponseCode, this will be a description of the error that occurred. See Response Code Messages.
id	String	20	Tutom Airtime Refill id. E.g: 1XNPXS
state	Integer	2	-1 = New; 2 = Processing (In most cases); 6 = Failed; 10 = Complete;
price	Currency	12	The price of this payment. E.g: 22.86
currency	String	3	The currency of this payment. E.g: USD

Response Example:

Error

{"response_code":"11703","response_text":"Sorry, your order is pending process, please do not re-submit orders."}

Success

{"response_code":"0","response_text":"Success","id":"1XNPYB","state":"2","price":"18.2800","currency":"USD"}

Check latest order status

Access URL: https://www.mychinaunicom.com/gateway/refillapi/OrderQuery

Http Method: GET/POST

Usage Notes:

Request Parameters:

Field Name	Type	Required	Max Length	Definition
orderid	String	Yes	32	User's order id. Minimum length: 5.
appkey	String	Yes	64	AppKey

Request Example:

https://www.mychinaunicom.com/gateway/refillapi/OrderQuery?appkey=7bf7d2fd6d9c5012ae7c82ab7617&orderid=test10001

Response Parameters:

Field Name	Type	Max Length	Definition
response_code	Integer	5	0 = Success. and non-zero = an error occurred. Possible values: See Response Code Messages.
response_text	String	1024	For non-zero ResponseCode, this will be a description of the error that occurred. See Response Code Messages.
id	String	20	Tutom Airtime Refill id. E.g: 1XNPXS
state	Integer	2	-1 = New; 2 = Processing; 6 = Failed; 10 = Complete;
price	Currency	12	The price of this payment. E.g: 22.86
currency	String	3	The currency of this payment. E.g: USD

Response Example:

Error

{"response_code":"11706","response_text":"Cannot find the order."}

Success

{"response_code":"0","response_text":"Success","id":"1XNPYB","state":"10","price":"18.2800","currency":"USD"}

Query account balance

Access URL: https://www.mychinaunicom.com/gateway/refillapi/QueryAccountBalance

Http Method: GET

Request Parameters:

Field Name	Type	Required	Max Length	Definition
appkey	String	Yes	64	AppKey

Request Example:

https://www.mychinaunicom.com/gateway/refillapi/QueryAccountBalance?appkey=7bf7d2fd6d9c5012ae7c82ab7617

Response Parameters:

Field Name	Type	Max Length	Definition
response_code	Integer	5	0 = Success. and non-zero = an error occurred. Possible values: See Response Code Messages.
response_text	String	1024	For non-zero ResponseCode, this will be a description of the error that occurred. See Response Code Messages.
Currency	String	3	E.g: USD \| CNY
Balance	Float	50
Frozen	Float	50
Available	Float	50

Response Example:

Error

{"response_code":"11001","response_text":"appkey is not valid"}

Success

{"response_code":"0","response_text":"Success.","list":[{"Currency":"USD","Balance":"0.0000","Frozen":"0.0000","Available":"0.0000"},{"Currency":"CNY","Balance":"123.0000","Frozen":"23.0000","Available":"100.0000"}]}

Push address: https://www.example.com/XXX

Push method: POST

Push parameter format: Common parameter key pair, non JSON

Push Parameters:

Field Name	Type	Max Length	Definition
tutomid	String	20	Tutom Airtime Refill id. E.g: 1XNPXS
orderid	String	32	User's order id. Minimum length: 5.
sign	String	32	MD5(appkey + tutomid + orderid ).
state	Integer	2	6 = Failed; 10 = Complete;

Process success return: success

Retry Mechanism: Tutom Gateway When the callback address is requested, if there is no response, will be re-initiated up to 2 times, with 12s interval

Usage Notes: If the interface has been debugged as described above, please send the username, service name[ Airtime Refill Service ], and callback address to support@tutompay.com. We will configure callback address

Response Code	Response Text
0	Success
11701	Denomination is not available, please contact your sales rep if needed
11702/11008/11010	Sorry, you cannot refill due to a low account balance, please add more fund to your account.
11703	Sorry, your order is pending process, please do not re-submit orders.
11704	Sorry, something wrong with your recharging request, please check phone number and denomination; please contact system administrator at support@tutompay.com
11705	sign value is wrong
11706	Cannot find the order
11720	recharging is not available for this phone number and denomination
11721	Service is temporarily not available
11740	recharge failed
11001	appkey is not valid
11002	Service is not activated, please contact system administrator
11003	Your account is locked, please contact system administrator to reactivate.
11004	Please contact system administrator to apply the service
11005	Only requests from white-listed IP address will be processed.
11007/11011	For more currency options, please contact system administrator.

Developer Resources

Instruction

List

ListByPhone

Order Create

Order Query

QueryAccountBalance

Callback format description

Message