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 if you have not signed one
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 data refill product list

Access URL: https://www.mychinaunicom.com/gateway/flowapi/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/flowapi/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.
productid	String	10	Tutom data refill productid. E.g: 17
type	Integer	2	1 = Normal; 2 = International travel card;
operator	String	50	China Telecom \| China Unicom \| China Mobile
data	String	10	500M \| 2GB \| ...
data_value	Integer	10	500 \| 1024 \| 2048... Unit: M;
expiration_date	String	25	E.g: 2017-05-31 00:00:00
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":[{"productid":"23","type":"2","operator":"China Unicom","data":"6GB","data_value":"6144","expiration_date":"2017-08-06 15:19:34","price":"46.0000","currency":"USD"},{"productid":"24","type":"2","operator":"China Unicom","data":"11GB","data_value":"11264","expiration_date":"2017-08-06 15:19:34","price":"78.0000","currency":"USD"}]}

Get mobile number that is good for data refill

Access URL: https://www.mychinaunicom.com/gateway/flowapi/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/flowapi/ListByPhone?appkey=7bf7d2fd6d9c5012ae7c82ab7617&mdn=18610865680

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.
productid	String	10	Tutom data refill productid. E.g: 17
type	Integer	2	1 = Regular product: effective immediantly, expires at the end of each calendar month; 2 = International travel card: valid for 90 days;
operator	String	50	China Telecom \| China Unicom \| China Mobile
data	String	10	500M \| 2GB \| ...
data_value	Integer	10	500 \| 1024 \| 2048... Unit: M;
expiration_date	String	25	E.g: 2017-05-31 00:00:00
price	Currency	12	The price of this product. E.g: 10.86
currency	String	3	E.g: USD \| CNY

Response Example:

Error

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

Success

Submit recharge request, create order

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

Http Method: GET/POST

Usage Notes: If there is network issues such as http errors or return code is 21108, 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
productid	String	Yes	10	Get ProductID via calling inqury API ( ListByPhone )
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 + productid).

Request Example:

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

&sign=1B6BC19B605360C63144A08F11301D4B&mdn=18610865680&productid=8

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 data 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":"21103","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/flowapi/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/flowapi/OrderQuery?appkey=7bf7d2fd6d9c5012ae7c82ab7617&orderid=test001

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 data 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":"21106","response_text":"Cannot find the order."}

Success

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

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 data 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: TutomGateway 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 top-up | Data refill ], and callback address to support@tutompay.com. We will configure callback address

Response Code	Response Text
0	Success
21102/11008/11010	Sorry, you cannot refill due to a low account balance, please add more fund to your account.
21103	Sorry, your order is pending process, please do not re-submit orders.
21104/21120	Sorry, something wrong with your recharging request, please check phone number and productid; please contact system administrator at support@tutompay.com
21105	sign value is wrong
21106	Cannot find the order
21107	Please check ResponseText if there is a problem for request
21108	Network is not normal. please contact system support at support@tutompay.com! DO NOT treate order as failure until you contact system support!
21121	This ProductID is not suitable for this mobile number
21140	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

Callback format description

Message