• API文档

    • 安全规范

    签名算法:

    第一步，设所有发送或者接收到的数据为集合M，将集合M内非空参数值的参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA。

    特别注意以下重要规则：

    • 参数名ASCII码从小到大排序(字典序);

    • 如果参数的值为空不参与签名;

    • 参数名区分大小写;

    • 传送的sign参数和signType参数不参与签名;

    • 黄页平台接口可能增加字段，验证签名时必须支持增加的扩展字段。

    第二步，在stringA最后拼接上发给服务商的appsecret得到了待签名的字符串。最终形式为key1=value1&key2=value2&...&appsecret=yourAppSecret，然后使用RSA或MD5签名，签名过后须转为全大写。

    API列表

    后台接口正式网址为http://open.cootekservice.com
    后接接口，如http://open.cootekservice.com/user/profile

    1. 账户信息查询: /user/profile
    2. 创建支付订单: /pay/create
    3. 黄页平台异步通知支付结果
    4. 申请退款: /refund/apply
    5. 异步通知退款结果
    6. 订单回传接口: /order/push

    具体API

    1) 账户信息查询: http://open.cootekservice.com/user/profile

    请求参数

    参数
    json示例
    参数名参数类型参数描述可空
    系统参数
    apiVersionSTRINGAPI版本NO
    appkeySTRING(32)平台发放给开发者的标识开发者身份的标识符NO
    timestampNUMBER时间戳，防回放攻击NO
    charsetSTRING编码方式，仅支持UTF-8NO
    signTypeSTRING签名类型，MD5NO
    signSTRING防篡改签名NO
    业务参数
    accessTokenSTRING由js接口获取的用户accessTokenNO
    {
    "appkey": "7168092738333613",
    "charset": "UTF-8",
    "accessToken": "eyJ0b2tlbiI6IjUyZTZlMTM4LTgxYjUtNGVhMi04ZjdmLTJiNWQwMGRhZWIyMSIsImV0b2tlbiI6IiJ8",
    "timestamp": 1444654204,
    "signType": "MD5",
    "apiVersion": "1.1",
    "sign": "5FB2E02192069E93F9FD5EBD5F2046B3"
}

    响应参数

    参数
    json示例
    参数名参数类型参数描述可空
    系统参数
    apiVersionSTRINGAPI版本NO
    appkeySTRING请求参数appkeyNO
    timestampNUMBER时间戳，防回放攻击NO
    charsetSTRING编码方式，仅支持UTF-8NO
    signTypeSTRING签名类型MD5NO
    signSTRING签名字符串NO
    resultSTRING返回状态码: SUCCESS/FAILNO
    errorCodeNUMBER业务结果码，当returnCode为FAIL时不可为空YES
    errorMessageSTRING业务结果信息，errorCode的具体描述YES
    业务参数
    userIdSTRING用户在黄页平台的唯一标识NO
    phoneSTRING用户的电话号码YES
    {
    "appkey": "7168092738333613",
    "signType": "MD5",
    "timestamp": 1444654230,
    "charset": "UTF-8",
    "userId": "11395416635002153251",
    "apiVersion": "1.1",
    "sign": "8A0361B8596D30773F58EC7F3C8D1D9E",
    "phone": "+8613812345678",
    "result": "SUCCESS"
}

    2) 创建支付订单: http://open.cootekservice.com/pay/create

    请求参数

    参数
    json示例
    参数名参数类型参数描述可空
    系统参数
    apiVersionSTRINGAPI版本NO
    appkeySTRING平台发放给开发者的标识开发者身份的标识符NO
    sellerIdSTRING平台发放给开发者的支付账户标识NO
    timestampNUMBER时间戳，防回放攻击NO
    charsetSTRING编码方式，仅支持UTF-8NO
    signTypeSTRING签名类型RSANO
    signSTRING签名字符串NO
    userIdSTRING用户身份唯一标识符NO
    accessTokenSTRING用户授权凭证，当用户登出时accessToken失效，API报4010错误码，需要重新登录NO
    业务参数
    notifyUrlSTRING服务商在黄页平台上注册的支付回调地址NO
    tradeNoSTRING(64)外部订单号，在服务商系统中，唯一标识的一笔订单NO
    tradeServiceSTRING(64)服务identifier,如com.cootek.rechargeNO
    tradeNameSTRING(128)交易主题NO
    tradeDescSTRING(512)交易描述NO
    totalFeeNUMBER交易金额[1~100000000], 正整数,单位为分NO
    expireTimeSTRING(14)订单失效时间,格式为yyyyMMddHHmmss,不填写代表无限制YES
    attachSTRING(1024)附加数据，在支付通知中原样返回YES
    tradeStrSTRINGjs接口select()返回的tradeStr，加密字符串，不得修改NO
    {
    "appkey": "1000688004371726",
    "signType": "RSA",
    "notifyUrl": "http://search.cootekservice.com/yellowpage_v3/trade_paid_notify",
    "timestamp": 1444654234,
    "charset": "UTF-8",
    "accessToken": "eyJ0b2tlbiI6IjUyZTZlMTM4LTgxYjUtNGVhMi04ZjdmLTJiNWQwMGRhZWIyMSIsImV0b2tlbiI6IiJ8",
    "userId": 14207037938152585000,
    "apiVersion": "1.1",
    "sign": "BN9KwKB2HlFsAQzj8BnPndRV+41kqOdBSSauhsWOmJxRKFEYvxCj4Z8siToyAIfqYZM54rZb7S7CIH46ZpAZiURVHZQJxO42l7HGPN0FhzF7GVaBPZS/VIxu++XUT/GHIXZKhQ+xJLqcNsbuWMQf2Dx10pmaqKzFLtKGEwzuW7k=",
    "attach": "触宝-话费充值",
    "tradeStr": "eyJwYXltZW50VHlwZSI6IndlaXBheSJ9",
    "tradeName": "触宝-话费充值",
    "tradeNo": "V2_10_6_1444654234",
    "sellerId": "6424025377829648",
    "tradeService": "com.cootek.recharge",
    "tradeDesc": "触宝-话费充值",
    "totalFee": 9950
}

    响应参数

    参数
    json示例
    参数名参数类型参数描述可空
    系统参数
    apiVersionSTRINGAPI版本NO
    appkeySTRING输入参数appkeyNO
    sellerIdSTRING输入参数sellerIdNO
    timestampNUMBER时间戳，防回放攻击NO
    charsetSTRING编码方式，仅支持UTF-8NO
    signTypeSTRING签名类型RSANO
    signSTRING签名字符串NO
    userIdSTRING用户身份唯一标识符NO
    resultSTRING返回状态码: SUCCESS/FAILNO
    errorCodeNUMBER业务结果码，当returnCode为FAIL时不可为空YES
    errorMessageSTRING业务结果信息，errorCode的具体描述YES
    业务参数
    transactionIdSTRING(64)黄页平台交易号NO
    tradeStatusSTRING交易状态: TRADE_CREATE(交易创建，待支付)
    TRADE_SUCCESS(支付成功，可退款)
    TRADE_FINISH(交易完成，不可退款)
    TRADE_CLOSED(因超时或全额退款而关闭)
    		NO
    payStrSTRING用于JS发起支付的参数，编码信息，不可改变，payStr不可缓存，当用户当前支付失败(取消或网络故障)，继续支付需要重新选择支付方式，并且重新创建支付订单NO
    {
    "appkey": "1000688004371726",
    "signType": "RSA",
    "timestamp": 1444654234,
    "charset": "UTF-8",
    "payStr": "eyJwYXltZW50VHlwZSI6ICJ3ZWlwYXkiLCAidHJhbnNhY3Rpb25JZCI6ICI0NTFkNDI0YS1iZWU4LTRjMjAtOGMzYy03MTY1YjgzZDBhMGEiLCAicGF5bWVudERhdGEiOiAie1wiYXBwa2V5XCI6IFwiNmk4azcyb3FiVmhQbjZQVDF6V29FbjZHblpvV2ZaTmxZR3liVzVqTWVNMEFKQTVKZHpZYUllS2loZ2pvRWhqY0Z6MVhQWHBVZkJUSXNkc3RLaFlxaERPcnBLbWdLb1VRY1hDOUdPZHhvV0RuYXh3WVZqVU5WbVY1UkgzV0lJcmNcIiwgXCJwYWNrYWdlXCI6IFwiU2lnbj1XWHBheVwiLCBcInRpbWVzdGFtcFwiOiAxNDQ0NjU0MjM0LCBcInNpZ25cIjogXCIyZmQ3ZTI1MTkyY2FmYmE0NWNhOWJhNjc0ZjkxNTkzYmI3MWJjZTM0XCIsIFwicGFydG5lcmlkXCI6IFwiMTIxODc5NDAwMVwiLCBcImFwcGlkXCI6IFwid3gzNmY5YTRjOGU4MWNjOGE4XCIsIFwicHJlcGF5aWRcIjogXCIyMjAxMDMyMDAwMTUxMDEyMTM3Zjg4ZGNmNDI5MTViYlwiLCBcIm5vbmNlc3RyXCI6IFwiYmM2MWUwNTZhY2IzNGFkMThjMDM3ZGFmODQ5NzYwYjlcIn0ifQ==",
    "apiVersion": "1.1",
    "sign": "Ltr1ysFWiC8VW2Sw219L9smt/mNUjCk/83fMQj+j/zAvPhpe0iFWQHfu17Ic+TAEgyFM/JXsRQ8p80gfxvOaZ4lV63ozKcLHbMgp/HOHG2HxUdbcHCkU+GXgo0fwJWQHITrZ7ZbMCyelrznW7Nzoz7yVmGbxgWpp6IzAJbqdM3g=",
    "result": "SUCCESS",
    "sellerId": "6424025377829648",
    "tradeStatus": "TRADE_CREATE",
    "transactionId": "451d424a-bee8-4c20-8c3c-7165b83d0a0a"
}

    3) 黄页平台异步通知支付结果

    URL: 黄页平台会将支付状态异步通知服务商注册的支付回调地址(notifyUrl)

    请求参数

    参数
    json示例
    参数名参数类型参数描述可空
    系统参数
    apiVersionSTRINGAPI版本NO
    appkeySTRING创建订单appkeyNO
    sellerIdSTRING创建订单sellerIdNO
    timestampNUMBER时间戳，防回放攻击NO
    charsetSTRING编码方式，仅支持UTF-8NO
    signTypeSTRING签名类型RSANO
    signSTRING签名字符串NO
    userIdSTRING用户身份唯一标识符NO
    resultSTRING返回状态码: SUCCESS/FAILNO
    errorCodeNUMBER业务结果码，当returnCode为FAIL时不可为空YES
    errorMessageSTRING业务结果信息，errorCode的具体描述YES
    业务参数
    paymentTypeSTRING支付方式,"alipay"或者"weipay"NO
    tradeNoSTRING(64)输入参数tradeNoNO
    tradeServiceSTRING(64)服务identifier,如com.cootek.rechargeNO
    tradeNameSTRING(128)交易主题NO
    tradeDescSTRING(512)交易描述NO
    totalFeeNUMBER交易金额[1~100000000], 正整数,单位为分NO
    cashFeeNUMBER用户需要支付的现金额度NO
    settleFeeNUMBER商户结算时应该收到的现金额度NO
    transactionIdSTRING(64)触宝开放平台交易号NO
    notifyTimeSTRING通知发送时间NO
    notifyIdSTRING(64)通知id，防止重复通知NO
    tradeCreateTimeSTRING交易创建时间NO
    tradeSuccessTimeSTRING付款成功时间NO
    tradeStatusTRADE-STATUS交易状态，详见定义NO
    attachSTRING(1024)附加数据，订单创建时的数据NO
    {
    "tradeSuccessTime": "20151013102700",
    "userId": "17014826786697905368",
    "sign": "AWOROZk8EUUDjytzyR19CSp0xqwyQ6huHKR1qbIcx8rwuHrhEnS3dHWDRW3s/aiz/pwiAOh29pq5llPIMpPYrI1m8t9R3oGuVWEP30cop8ZEMpEViXewQlxkl3ibIPJhNpkdd4rVCWBjdoc+CqRUk+bNsbORckYn8jWl1QUVwnQ=",
    "result": "SUCCESS",
    "tradeNo": "V2_10_6_1444703187",
    "notifyTime": "20151013102700",
    "tradeService": "com.cootek.recharge",
    "tradeCreateTime": "20151013102627",
    "charset": "UTF-8",
    "attach": "触宝-话费充值",
    "tradeName": "触宝-话费充值",
    "sellerId": "6424025377829648",
    "tradeStatus": "TRADE_SUCCESS",
    "tradeDesc": "触宝-话费充值",
    "totalFee": 9950,
    "timestamp": 1444703220,
    "paymentType": "weipay",
    "cashFee": 9950,
    "appkey": "1000688004371726",
    "settleFee": 9950,
    "signType": "RSA",
    "apiVersion": "1.1",
    "transactionId": "43db91f7-2b1f-4d98-bfec-3a62a2d6c696",
    "notifyId": "f04719cd-6562-4529-9923-8ec35efb185f"
}

    响应参数

    SUCCESS

    注: 合作方对异步通知的响应必须是"SUCCESS"(不包含引号，全大写)；如果响应不是SUCCESS这7个字符，平台服务器会不断重发通知，直到超出重试策略（下同）。

    4) 申请退款: http://open.cootekservice.com/refund/apply

    请求参数

    参数
    json示例
    参数名参数类型参数描述可空
    系统参数
    apiVersionSTRINGAPI版本NO
    appkeySTRING平台发放给开发者的标识开发者身份的标识符NO
    sellerIdSTRING平台发放给开发者的支付账户标识NO
    timestampNUMBER时间戳，防回放攻击NO
    charsetSTRING编码方式，仅支持UTF-8NO
    signTypeSTRING签名类型RSANO
    signSTRING签名字符串NO
    userIdSTRING用户身份唯一标识符NO
    业务参数
    notifyUrlSTRING服务商在黄页平台上注册的退款回调地址NO
    transactionIdSTRING(64)黄页平台交易号NO
    refundNoSTRING(64)服务商系统退款单号，需保证唯一性NO
    totalFeeNUMBER订单额度,整数,单位为分NO
    cashFeeNUMBER订单现金支付额度NO
    refundFeeNUMBER申请退款额度,refundFee不得大于cashFeeNO
    {
    "appkey": "1000688004371726",
    "signType": "RSA",
    "refundFee": 1000,
    "timestamp": 1444494518,
    "charset": "UTF-8",
    "userId": 3305463365835551000,
    "apiVersion": "1.1",
    "sign": "dUlKoaGylwUJQF+KqgZZm0IUdxaAkSGkgxxOF559cDI3ovV7GFIItQ+xmcJaJ7O6mB5C5nC/mFgPPjYGV03P8D2m91XTk6fXK9mIXtGEV3LPkyHCuaA10/3ElLwHLxjrNXCRKBeVgmtH6XrkNz8vFO4K6GhrCAV3zK50bsQxxw8=",
    "refundNo": "refund_V2_10_3_1444489742",
    "cashFee": 1000,
    "sellerId": "6424025377829648",
    "notifyUrl": "http://search.cootekservice.com/yellowpage_v3/trade_refund_notify",
    "transactionId": "d0e29277-35c6-4609-b9fb-fef19cf93273",
    "totalFee": 1000
}

    响应参数

    参数
    json示例
    参数名参数类型参数描述可空
    系统参数
    apiVersionSTRINGAPI版本NO
    appkeySTRING输入参数appkeyNO
    sellerIdSTRING输入参数sellerIdNO
    timestampNUMBER时间戳，防回放攻击NO
    charsetSTRING编码方式，仅支持UTF-8NO
    signTypeSTRING签名类型RSANO
    signSTRING签名字符串NO
    userIdSTRING用户身份唯一标识符NO
    resultSTRING返回状态码: SUCCESS/FAILNO
    errorCodeNUMBER业务结果码，当returnCode为FAIL时不可为空YES
    errorMessageSTRING业务结果信息，errorCode的具体描述YES
    业务参数
    refundIdSTRING(64)黄页平台退款单号NO
    refundStatusSTRING退款状态: REFUND_PROCESSING(退款已接受，处理中)
    REFUND_SUCCESS(退款成功)
    REFUND_FAIL(退款失败)
    		NO
    {
    "appkey": "1000688004371726",
    "signType": "RSA",
    "refundStatus": "REFUND_PROCESSING",
    "timestamp": 1444494518,
    "charset": "UTF-8",
    "apiVersion": "1.1",
    "sign": "RZLeomhx9Dtd8l8BEeQWMqLna4X78eRZhqR2OZc3e+dQXWrtJYb/QwxTP4uNxXylRxiO34utZ41nEjp0TTbqdZoJ7u+BDd4FftzaSSHmBnLxvrmfapDdKJi5HoLRF0gS3WB88PlhJbiY+JEAHvFz5U/MfK2wUHI2/aLz/tMh0g8=",
    "result": "SUCCESS",
    "sellerId": "6424025377829648",
    "refundId": "750ad1ae-d953-4ac5-89ca-236f62eb5e88"
}

    5) 异步通知退款结果，地址为服务商注册的退款回调地址(notifyUrl)

    请求参数

    参数
    json示例
    参数名参数类型参数描述可空
    系统参数
    apiVersionSTRINGAPI版本NO
    appkeySTRING申请退款appkeyNO
    sellerIdSTRING申请退款sellerIdNO
    timestampNUMBER时间戳，防回放攻击NO
    charsetSTRING编码方式，仅支持UTF-8NO
    signTypeSTRING签名类型RSANO
    signSTRING签名字符串NO
    userIdSTRING用户身份唯一标识符NO
    resultSTRING返回状态码: SUCCESS/FAILNO
    errorCodeNUMBER业务结果码，当returnCode为FAIL时不可为空YES
    errorMessageSTRING业务结果信息，errorCode的具体描述YES
    业务参数
    transactionIdSTRING(64)黄页平台交易号NO
    refundNoSTRING(64)服务商系统退款单号，需保证唯一性NO
    refundIdSTRING(64)黄页平台退款单号NO
    totalFeeNUMBER订单额度,整数,单位为分NO
    cashFeeNUMBER订单现金支付额度NO
    refundFeeNUMBER申请退款额度,refundFee不得大于cashFeeNO
    refundStatusSTRING退款状态: REFUND_PROCESSING(退款已接受，处理中)
    REFUND_SUCCESS(退款成功)
    REFUND_FAIL(退款失败)
    		NO
    {
    "userId": "16331517825208896891",
    "result": "SUCCESS",
    "tradeNo": "V2_10_3_1444397899",
    "notifyTime": "20151009220029",
    "tradeService": "com.cootek.mobiledata",
    "refundStatus": "REFUND_SUCCESS",
    "charset": "UTF-8",
    "sellerId": "6424025377829648",
    "refundId": "d432ebf1-4bba-4524-b5f7-ee90a4589af2",
    "totalFee": 1500,
    "timestamp": 1444399229,
    "cashFee": 1500,
    "appkey": "1000688004371726",
    "refundFee": 1500,
    "signType": "RSA",
    "apiVersion": "1.1",
    "refundNo": "refund_V2_10_3_1444397899",
    "transactionId": "6249c4b9-b665-412f-9684-1c6b749d1e35",
    "notifyId": "7d50483f-3ca7-4e1c-a315-0ef6c021687e"
}

    响应参数

    SUCCESS

    6) 订单回传接口: http://open.cootekservice.com/order/push

    请求参数

    参数
    json示例
    参数名参数类型参数描述可空
    系统参数
    apiVersionSTRINGAPI版本NO
    appkeySTRING平台发放给开发者的标识开发者身份的标识符NO
    timestampNUMBER时间戳，防回放攻击NO
    charsetSTRING编码方式，仅支持UTF-8NO
    signTypeSTRING签名类型MD5NO
    signSTRING防篡改签名NO
    userIdSTRING用户身份唯一标识符NO
    业务参数
    orderIdSTRING(64)订单id，在服务商系统中，是一笔订单唯一标识NO
    orderServiceSTRING(64)订单所属服务identifierNO
    orderTitleSTRING(128)订单概要信息NO
    orderShortInfoSTRING(512)订单详细信息NO
    orderStatusSTRING(32)订单状态的文字描述，一个用户可理解的汉子串，由业务自行决定NO
    orderCreateTimeSTRING订单创建时间，格式为yyyyMMddHHmmssNO
    orderFinishTimeSTRING订单完成时间，格式为yyyyMMddHHmmssYES
    orderUrlSTRING用户可以访问到的该订单的详情页地址NO
    attachSTRING附件信息，JSON结构，如{"received_code": "439289"}YES
    {
    "orderId": "559631712918",
    "orderTitle": "订单559631712918",
    "orderCreateTime": "20151010171931",
    "charset": "UTF-8",
    "signType": "MD5",
    "timestamp": 1444656557,
    "orderUrl": "http://www.dangaoss.com/h5/order/show?channel_no=chubao&id=420302",
    "userId": "1221494761561051784",
    "apiVersion": "1.1",
    "sign": "BE5AF9A130C7FFF1E7A1B3C47854EC77",
    "appkey": "7168665963237765",
    "orderService": "com.cootek.recharge",
    "orderShortInfo": "淘豆麻团（红豆味） 145g x1",
    "sellerId": "5885807508620232",
    "attach": "{"received_code": "439289"}",
    "orderStatus": "已支付"
}

    响应参数

    参数
    json示例
    参数名参数类型参数描述可空
    系统参数
    apiVersionSTRINGAPI版本NO
    appkeySTRING申请退款appkeyNO
    timestampNUMBER时间戳，防回放攻击NO
    charsetSTRING编码方式，仅支持UTF-8NO
    signTypeSTRING签名类型RSANO
    signSTRING签名字符串NO
    userIdSTRING用户身份唯一标识符NO
    resultSTRING返回状态码: SUCCESS/FAILNO
    errorCodeNUMBER业务结果码，当returnCode为FAIL时不可为空YES
    errorMessageSTRING业务结果信息，errorCode的具体描述YES
    业务参数
    {
    "appkey": "7168665963237765",
    "signType": "MD5",
    "timestamp": 1444656608,
    "charset": "UTF-8",
    "apiVersion": "1.1",
    "sign": "CC60B133FD9AEAFBBC2BD0FA11E4EC63",
    "result": "SUCCESS",
    "sellerId": "5885807508620232"
}

    错误码

    errorCodeerrorMessage描述发生业务
    系统错误码
    4001appkey not existappkey不存在，请检查配置，测试与正式环境的appkey不可混用ALL
    4002sellerId not existsellerId不存在，请检查配置，测试与正式环境的sellerId不可混用ALL
    4003appkey not match with sellerIdappkey与sellerId不匹配，请检查配置，测试与正式环境的appkey&sellerId不可混用ALL
    4004timestamp illegal时间戳非法，请检查系统时间，时间戳要求误差不超过30sALL
    4005require post method未使用POST提交请求ALL
    4006post data illegalPOST提交数据非法，可能原因有:
    1. 空数据
    2. 编码错误
    3. 缺少必须参数
    4. JSON格式错误
    		ALL
    4007sign error签名不正确，请仔细核对签名算法ALL
    4008no auth未经授权，开发者无访问该API的权限ALL
    4009userId not exist用户不存在，请重新授权ALL
    4010access token invalid用户授权凭证失效，请重新授权ALL
    5001system error系统错误，请稍后(>30s)重试ALL
    业务错误码
    4101order exist订单已存在，新建请求与系统中存储的订单信息不符，如金额等，处于"待支付"状态的订单是可以重复创建创建订单
    4102order success订单已支付成功创建订单
    支付结果通知
    取消订单
    JS pay
    4103order finish订单已完成创建订单
    支付结果通知
    取消订单
    申请退款
    4104order closed订单已关闭创建订单
    支付结果通知
    取消订单
    申请退款
    4105order dealing订单处理中创建订单
    支付结果通知
    取消订单
    JS pay
    4106order paid failed订单支付失败支付结果通知
    JS pay
    4107order canceled用户中途取消JS pay
    4108order network error支付网络故障JS pay
    4109order no exist订单不存在取消订单
    申请退款
    4110order no paid订单尚未支付成功，可能是微信或支付宝系统延迟申请退款
    4111refund processing退款申请处理中，请勿重复发起退款申请申请退款
    4112refund success退款已成功，请勿重复发起退款申请申请退款
    退款结果通知
    4113refund failed退款失败，请勿重复发起退款申请，可转人工客服处理申请退款
    退款结果通知

    上海触宝信息技术有限公司（触宝科技）版权所有 ©2012 沪ICP备12012934号-1