API 文档简介

Ping++ API 采用 REST 风格设计。所有接口请求地址都是可预期的以及面向资源的。使用规范的 HTTP 响应代码来表示请求结果的正确或错误信息。使用 HTTP 内置的特性,如 HTTP Authentication 和 HTTP 请求方法让接口易于理解。所有的 API 请求都会以规范友好的 JSON 对象格式返回(包括错误信息)。

官方 SDK

Ping++ 提供多语言多平台的 官方客户端和服务端 SDK

定义

GET
https://api.pingxx.com

认证

在调用 API 时,必须提供 API Key 作为每个请求的身份验证。你可以在管理平台内管理你的 API Key。API Key 是商户在 Ping++ 系统中的身份标识,请安全存储,确保其不要被泄露。如需获取或更新 API Key ,也可以在管理平台的「企业设置」->「开发设置」内进行操作

Ping++ API 使用 HTTP Basic Auth 进行认证。 将 API Key 作为 basic auth 的用户名。不需要填写密码。

API Key 分为 live 和 test 两种模式。分别对应真实交易环境和模拟测试交易环境并且可以实时切换。测试模式下的 API Key 会模拟交易等请求,但是不会产生任何真实交易行为和费用,便于调试和接入。 所有的 API 请求必须通过 HTTPS 发送,使用 HTTP 会被 Ping++ 服务器拒绝。

请求示例

curl https://api.pingxx.com/v1/charges \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

请将示例中的 sk_test_ibbTe5jLGCi5rzfH4OqPW9KC 替换成你自己的 API Key。

错误

Ping++ API 使用 HTTP 状态码 (status code) 来表明一个 API 请求的成功或失败状态。返回 HTTP 2XX 表明 API 请求成功。返回 HTTP 4XX 表明在请求 API 时提供了错误信息,例如参数缺失、参数错误、支付渠道错误等。返回 HTTP 5XX 表明 API 请求时,Ping++ 服务器发生了错误。

HTTP 返回状态码

状态码
200 - OK 一切正常。
400 - Bad Request 一般由缺失参数,参数格式不正确等引起。
401 - Unauthorized 没有提供正确的 API Key。
402 - Request Failed 参数格式正确但是请求失败,一般由业务错误引起。
403 - Forbidden 调用接口超过 Ping++ 套餐的并发限制,请 升级套餐 或限流。
404 - Not Found 请求的资源不存在。
500, 502, 503, 504 - Server Errors Ping++ 服务器出错。

错误汇总

返回属性
type 错误类型,可以是 invalid_request_errorapi_errorchannel_errorcard_error
message 返回具体的错误描述。
code optional 错误码,由第三方支付渠道返回的错误代码。
param optional 当发生参数错误时返回具体的参数名,如 id。

错误类型 (type)

错误类型
invalid_request_error 请求错误,传入了不正确的地址,参数或值。
api_error Ping++ 服务器出现的异常错误。
channel_error 第三方支付渠道出现的错误导致请求出现错误。通常你需要对这些可能出现的情况进行处理或者联系我们。

错误码 (code)

错误码
charge_closed 支付订单已结束,不能进行后续操作。
charge_unexpected_status 支付返回意外的状态码。
refund_wait_operation 退款需要等待用户进一步操作。
refund_refused 退款失败,被支付渠道拒绝。
refund_retry 退款失败,需要重新发起退款。
refund_manual_intervention 退款失败,需要通过线下或转账进行退款。
refund_unexpected_status 退款返回意外的状态码。
channel_connection_error 支付渠道通讯异常。
channel_request_error 请求支付渠道接口失败。
channel_parse_error 支付渠道返回意外的数据格式发生的解析错误。
channel_sign_error 支付渠道返回的数据没有通过签名验证。
channel_unexpected_error 支付渠道遇到未知错误。
channel_parameter_error 支付渠道参数错误。
channel_auth_error 支付渠道参数错误
channel_response_code_fail 支付渠道响应码错误。
channel_parameters_consistency_error 支付渠道参数一致性检测失败。
channel_not_support_red_envelope 您的微信参数版本不支持发送红包。请联系微信升级为新版本。
channel_not_support_transfer 您的微信参数版本不支持发送企业付款。请联系微信升级为新版本。
channel_request_info 来自渠道的信息
query_right_error 支付渠道查询权限错误,请登录支付宝在线人工窗口,免费签约“账务明细”接口和“交易查询”接口。
channel_notify_id_error 支付渠道的NOTIFY ID非法或已失效
charge_order_no_used 订单号已使用。请用新的订单号发起交易。
transfer_wait_operation 转账需要打开地址进行下一步付款操作
refund_refused_msg 退款已被支付渠道拒绝。
refund_pending 退款状态未明,请稍后查询。
refund_failed 退款失败
refund_info_from_channel 来自渠道的退款信息。
refund_not_found 未在渠道查找到相应退款信息。
red_system_busy 支付渠道系统繁忙,请稍后用同一商户单号再次调用。只会发送一个红包。
transfer_system_busy 支付渠道系统繁忙,请稍后用同一商户单号再次调用。只会发送一笔转账。
qgbc_term_amount_too_small 订单金额过小,不支持分期。

分页

所有的 Ping++ 资源都可以被 list API 方法支持,例如分页 chargesrefunds。这些 list API 方法拥有相同的数据结构。Ping++ 是基于 cursor 的分页机制,使用参数 starting_after 来决定列表从何处开始,使用参数 ending_before 来决定列表从何处结束。

请求参数
limit optional 限制每页可以返回多少对象,限制范围是从 1~100 项,默认是 10 项。
starting_after optional 在分页时使用的指针,决定了列表的第一项从何处开始。假设你的一次请求返回列表的最后一项的 idobj_end ,你可以使用 starting_after = obj_end 去获取下一页。
ending_before optional 在分页时使用的指针,决定了列表的最末项在何处结束。假设你的一次请求返回列表的第一项的 idobj_start ,你可以使用 ending_before = obj_start 去获取上一页。
created optional 对象的创建时间,用 Unix 时间戳表示。具体参考下表 created 参数。
created 参数
created [ gt ] optional int 大于 charge 对象的创建时间,用 Unix 时间戳表示。
created [ gte ] optional int 大于或等于 charge 对象的创建时间,用 Unix 时间戳表示。
created [ lt ] optional int 小于 charge 对象的创建时间,用 Unix 时间戳表示。
created [ lte ] optional int 小于或等于 charge 对象的创建时间,用 Unix 时间戳表示。
返回
object string 值为 "list"
url string 表明获取该列表所使用的 URL。
has_more boolean 表明获取列表之后是否还有更多的元素实体。如果值为 false ,表明当前页是最后一页。
data array 包含一个由请求参数分页后的返回元素实体。

请求示例

curl https://api.pingxx.com/v1/charges/?limit=3 \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
  "object": "list",
  "url": "/v1/charges",
  "has_more": false,
  "data": [
    {
      "id": "ch_Hm5uTSifDOuTy9iLeLPSurrD",
      "object": "charge",
      "created": 1410767648,
      "livemode": true,
      "paid": false,
      "refunded": false,
      "app": "app_1Gqj58ynP0mHeX1q",
      "channel": "upacp",
      "order_no": "123456789012",
      "client_ip": "127.0.0.1",
      "amount": 900,
      "amount_settle": 0,
      "currency": "cny",
      "subject": "Your Subject",
      "body": "Your Body",
      "time_expire": 1410771248,
      "time_settle": null,
      "transaction_no": null,
      "refunds": {
        "object": "list",
        "url": "/v1/charges/ch_Hm5uTSifDOuTy9iLeLPSurrD/refunds",
        "has_more": false,
        "data": [ ]
      },
      "amount_refunded": 0,
      "failure_code": null,
      "failure_msg": null,
      "metadata": {},
      "credential": {},
      "description": null
    }
  ]
}

可展开对象

Ping++ 内有很多对象包含了其他对象的 id,如果这些对象带有 expandable 展开特性,你可以在请求参数后加入额外的展开参数来展开子对象。例如在创建 charge 对象时,使用 expand[]=app 参数来展开返回 charge 对象内部的 app 对象。

请求示例

curl https://api.pingxx.com/v1/charges/ch_Hm5uTSifDOuTy9iLeLPSurrD?expand[]=app \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

元数据

一些 Ping++ 对象支持加入用户指定的 metadata 参数。你可以使用键值对的形式来构建自己的 metadata,例如 metadata[color] = red,你可以在每一个 charge 对象中加入订单的一些详情,如颜色、型号等属性,在查询时获得更多信息。每一个对象的 metadata 最多可以拥有 10 个键值对,数据总长度在 1000 个 Unicode 字符以内。

如果你即将或正在使用 Ping++ 大数据产品,规范 Charge 字段信息可以帮助你更全面地多维度分析你的交易,详情请参考:《大数据产品支付数据字段说明文档》

属性
phone_number optional,string 手机号(11位)。
user_id optional,string 用户 ID,商户 App 内用户的唯一标识。

请求示例

curl https://api.pingxx.com/v1/charges \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d order_no=123456789 \
-d amount=100 \
-d app[id]=app_1Gqj58ynP0mHeX1q \
-d channel=upacp \
-d currency=cny \
-d client_ip=127.0.0.1 \
-d subject="Your Subject" \
-d body="Your Body" \
-d metadata[color]=red
-d metadata[phone_number]=13918651111

返回示例

{
  "id": "ch_Hm5uTSifDOuTy9iLeLPSurrD",
  "object": "charge",
  "created": 1410775686,
  "livemode": true,
  "paid": false,
  "refunded": false,
  "app": "app_1Gqj58ynP0mHeX1q",
  "channel": "upacp",
  "order_no": "123456789",
  "client_ip": "127.0.0.1",
  "amount": 100,
  "amount_settle": 0,
  "currency": "cny",
  "subject": "Your Subject",
  "body": "Your Body",
  "time_expire": 1410779286,
  "time_settle": null,
  "transaction_no": null,
  "refunds": {
    "object": "list",
    "url": "/v1/charges/ch_Hm5uTSifDOuTy9iLeLPSurrD/refunds",
    "has_more": false,
    "data": []
  },
  "amount_refunded": 0,
  "failure_code": null,
  "failure_msg": null,
  "metadata": {
    "color": "red",
    "phone_number": "13918651111"
  },
  "credential": {
    "object": "credential",
    "upacp": {
      "tn": "201409151808060000000",
      "mode": "01"
    }
  },
  "description": null
}

Charges 支付

你可以创建一个 charge 对象向用户收款。 charge 是一个支付凭据对象,所有和支付相关的要素信息都存储在这个对象中,你的服务端可以通过发起支付请求来创建一个新的 charge 对象,也可以随时查询一个或者多个 charge 对象的状态。每个 charge 对象都拥有一个标识 id,该 id 在 Ping++ 系统内唯一。

如果你即将或正在使用 Ping++ 大数据产品,规范 Charge 字段信息可以帮助你更全面地多维度分析你的交易,详情请参考:《大数据产品支付数据字段说明文档》

属性
id string 由 Ping++ 生成的支付对象 ID, 27 位字符串。
object string 值为 "charge"。
created timestamp 支付创建时的 Unix 时间戳。
livemode boolean 是否处于 live 模式。
paid boolean 是否已付款。
refunded boolean 是否存在退款信息,无论退款是否成功。
reversed boolean 订单是否撤销。
app expandable string 支付使用的 app 对象的 id ,expandable 可展开,查看 如何获取App ID
channel string 支付使用的第三方支付渠道,详情参考 支付渠道属性值
order_no string 商户订单号,适配每个渠道对此参数的要求,必须在商户系统内唯一。( alipayalipay_wapalipay_qralipay_scanalipay_pc_direct : 1-64 位,可包含字母、数字、下划线; wx : 2-32 位; wx_pub_scan :1-32 位的数字和字母组合; bfb : 1-20 位; upacp : 8-40 位; yeepay_wap :1-50 位; jdpay_wap : 1-30 位; qpay :1-30 位; cmb_wallet : 6-32 位的数字和字母组合,一天内不能重复,订单日期+订单号唯一定位一笔订单,示例: 20170808test01)。注:推荐使用 8-20 位,要求数字或字母,不允许特殊字符。
client_ip ip address 发起支付请求客户端的 IP 地址,格式为 IPv4 整型,如 127.0.0.1。
amount int 订单总金额(必须大于 0),单位为对应币种的最小货币单位,人民币为分。如订单总金额为 1 元, amount 为 100,么么贷商户请查看申请的借贷金额范围。
amount_settle int 清算金额,单位为对应币种的最小货币单位,人民币为分。
currency string 3 位 ISO 货币代码,人民币为 cny
subject string 商品标题,该参数最长为 32 个 Unicode 字符。银联全渠道( upacp / upacp_wap )限制在 32 个字节;支付宝部分渠道不支持特殊字符。大数据产品使用该字段请参考: 《大数据产品支付数据字段说明文档》
body string 商品描述信息,该参数最长为 128 个 Unicode 字符。 yeepay_wap 对于该参数长度限制为 100 个 Unicode 字符;支付宝部分渠道不支持特殊字符。大数据产品使用该字段请参考: 《大数据产品支付数据字段说明文档》
extra object 特定渠道发起交易时需要的额外参数,以及部分渠道支付成功返回的额外参数,详细参考 支付渠道 extra 参数说明
time_paid timestamp 订单支付完成时的 Unix 时间戳。(银联支付成功时间为接收异步通知的时间)
time_expire timestamp 订单失效时的 Unix 时间戳。时间范围在订单创建后的 1 分钟到 15 天,默认为 1 天,创建时间以 Ping++ 服务器时间为准。 微信对该参数的有效值限制为 2 小时内;银联对该参数的有效值限制为 1 小时内。
time_settle timestamp 订单清算时间,用 Unix 时间戳表示。(暂不生效)
transaction_no string 支付渠道返回的交易流水号。
refunds list 退款详情列表,详见 Refunds 退款
amount_refunded int 已退款总金额,单位为对应币种的最小货币单位,例如:人民币为分。
failure_code string 订单的错误码,详见 错误 中的错误码描述。
failure_msg string 订单的错误消息的描述。
metadata hash 详见 元数据
credential object 支付凭证,用于客户端发起支付。
description string 订单附加说明,最多 255 个 Unicode 字符。

对象示例

{
  "id": "ch_Hm5uTSifDOuTy9iLeLPSurrD",
  "object": "charge",
  "created": 1410778843,
  "livemode": true,
  "paid": false,
  "refunded": false,
  "reversed": false,
  "app": "app_1Gqj58ynP0mHeX1q",
  "channel": "upacp",
  "order_no": "123456789",
  "client_ip": "127.0.0.1",
  "amount": 100,
  "amount_settle": 100,
  "currency": "cny",
  "subject": "Your Subject",
  "body": "Your Body",
  "extra":{},
  "time_paid": null,
  "time_expire": 1410782443,
  "time_settle": null,
  "transaction_no": null,
  "refunds": {
    "object": "list",
    "url": "/v1/charges/ch_Hm5uTSifDOuTy9iLeLPSurrD/refunds",
    "has_more": false,
    "data": []
  },
  "amount_refunded": 0,
  "failure_code": null,
  "failure_msg": null,
  "credential": {
    "object": "credential",
    "upacp": {
      "tn": "201409151900430000000",
      "mode": "01"
    }
  },
  "description": null
}

创建 Charge 对象

发起一次支付请求时需要创建一个新的 charge 对象,获取一个可用的支付凭据用于客户端向第三方渠道发起支付请求。如果使用测试模式的 API Key,则不会发生真实交易。当支付成功后,Ping++ 会发送 Webhooks 通知。

请求参数
order_no required 商户订单号,适配每个渠道对此参数的要求,必须在商户系统内唯一。( alipayalipay_wapalipay_qralipay_scanalipay_pc_direct : 1-64 位,可包含字母、数字、下划线; wx : 2-32 位; wx_pub_scan :1-32 位的数字和字母组合; bfb : 1-20 位; upacp : 8-40 位; yeepay_wap :1-50 位; jdpay_wap : 1-30 位; qpay :1-30 位; cmb_wallet : 6-32 位的数字和字母组合,一天内不能重复,订单日期+订单号唯一定位一笔订单,示例: 20170808test01)。注:推荐使用 8-20 位,要求数字或字母,不允许特殊字符。
app [ id ] expandable required 支付使用的 app 对象的 idexpandable 可展开,查看 如何获取App ID
channel required 支付使用的第三方支付渠道。参考 支付渠道属性值
amount required 订单总金额(必须大于 0),单位为对应币种的最小货币单位,人民币为分。如订单总金额为 1 元, amount 为 100,么么贷商户请查看申请的借贷金额范围。
client_ip required 发起支付请求客户端的 IPv4 地址,如: 127.0.0.1。
currency required 三位 ISO 货币代码,目前仅支持人民币 cny
subject required 商品标题,该参数最长为 32 个 Unicode 字符。银联全渠道( upacp / upacp_wap )限制在 32 个字节;支付宝部分渠道不支持特殊字符。大数据产品使用该字段请参考: 《大数据产品支付数据字段说明文档》
body required 商品描述信息,该参数最长为 128 个 Unicode 字符。 yeepay_wap 对于该参数长度限制为 100 个 Unicode 字符;支付宝部分渠道不支持特殊字符。大数据产品使用该字段请参考: 《大数据产品支付数据字段说明文档》
extra optional 特定渠道发起交易时需要的额外参数,以及部分渠道支付成功返回的额外参数,详细参考 支付渠道 extra 参数说明
time_expire optional 订单失效时间,用 Unix 时间戳表示。时间范围在订单创建后的 1 分钟到 15 天,默认为 1 天,创建时间以 Ping++ 服务器时间为准。 微信对该参数的有效值限制为 2 小时内;银联对该参数的有效值限制为 1 小时内。
metadata optional 参考 元数据
description optional 订单附加说明,最多 255 个 Unicode 字符。

返回

返回一个支付凭据 charge 对象。鉴于支付渠道对 order_no 的合法性要求,为了保证支付请求的正确处理,请务必保证对于同一支付渠道下,不同支付产品间 order_no 的唯一性。例如:已在微信公众号下使用的 order_no 则无法在微信支付以及微信公众号扫码下重复使用,该规则同样适用于其他同类渠道。如果发生错误,则会返回错误码和错误详情,详见 错误

定义

POST https://api.pingxx.com/v1/charges

请求示例

curl https://api.pingxx.com/v1/charges \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d order_no=123456789 \
-d amount=100 \
-d app[id]=app_1Gqj58ynP0mHeX1q \
-d channel=upacp \
-d currency=cny \
-d client_ip=127.0.0.1 \
-d subject="Your Subject" \
-d body="Your Body"

返回示例

{
  "id": "ch_L8qn10mLmr1GS8e5OODmHaL4",
  "object": "charge",
  "created": 1410834527,
  "livemode": true,
  "paid": false,
  "refunded": false,
  "reversed": false,
  "app": "app_1Gqj58ynP0mHeX1q",
  "channel": "upacp",
  "order_no": "123456789",
  "client_ip": "127.0.0.1",
  "amount": 100,
  "amount_settle": 100,
  "currency": "cny",
  "subject": "Your Subject",
  "body": "Your Body",
  "extra":{},
  "time_paid": null,
  "time_expire": 1410838127,
  "time_settle": null,
  "transaction_no": null,
  "refunds": {
    "object": "list",
    "url": "/v1/charges/ch_L8qn10mLmr1GS8e5OODmHaL4/refunds",
    "has_more": false,
    "data": [ ]
  },
  "amount_refunded": 0,
  "failure_code": null,
  "failure_msg": null,
  "metadata": {},
  "credential": {
    "object": "credential",
    "upacp": {
      "tn": "201409161028470000000",
      "mode": "01"
    }
  },
  "description": null
}

撤销 Charge 对象

针对已经创建的 Charge,你可以调用撤销接口进行交易的关闭。此接口仅接受 wx_pub_scanalipay_scan 渠道的订单调用。

本接口有两重作用,对于未成功付款的订单进行撤销,则关闭交易,使用户后期不能支付成功;对于成功付款的订单进行撤销,系统将订单金额返还给用户,相当于对此交易做退款(不允许撤销接口当做退款接口使用)。

注: 1、wx_pub_scan渠道可在交易产生 7 天内调用撤销接口,alipay_scan渠道可在交易产生 24 小时内调用撤销接口。 2、对于成功付款的订单直接调用退款接口进行退款,只有针对未支付的订单,我们建议你调用撤销接口。

请求参数
CHARGE_ID required charge 对象 ID。

返回

返回一个 charge 对象。如果发生错误,则会返回错误码和错误详情,详见 错误

定义

POST /v1/charges/{CHARGE_ID}/reverse

请求示例

curl https://api.pingxx.com/v1/charges/ch_injTG4KGWPePS88WPGPyfzz5/reverse \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Content-Type: application/json" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:
-d '{}'

返回示例

{
  "id": "ch_injTG4KGWPePS88WPGPyfzz5",
  "object": "charge",
  "created": 1495694197,
  "livemode": true,
  "paid": true,
  "refunded": false,
  "reversed": true,
  "app": "app_4OOi9SGuD88GGqbL",
  "channel": "isv_scan",
  "order_no": "149569419725834",
  "client_ip": "127.0.0.1",
  "amount": 1,
  "amount_settle": 1,
  "currency": "cny",
  "subject": "cm isv_scan",
  "body": "cm isv_scan",
  "extra": {
    "scan_code": "130141564083799183",
    "terminal_id": "00000001",
    "pay_channel": "wx",
    "buyer_account": "omYJss9x8g2TzmrxnUtrOr7qWhwc",
    "chcd_discount": "0.00",
    "mer_discount": "0.00"
  },
  "time_paid": 1495694546,
  "time_expire": 1495780597,
  "time_settle": null,
  "transaction_no": "4002362001201705252516756579",
  "refunds": {
    "object": "list",
    "url": "/v1/charges/ch_injTG4KGWPePS88WPGPyfzz5/refunds",
    "has_more": false,
    "data": []
  },
  "amount_refunded": 0,
  "failure_code": null,
  "failure_msg": null,
  "metadata": {},
  "credential": {},
  "description": null
}

查询 Charge 对象

你可以在后台异步通知之前,通过查询接口确认支付状态。通过charge对象的id查询一个已创建的charge对象。

请求参数
id required 查询的 charge 对象 id

返回

返回一个已存在的 charge 对象或者一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/charges/{CHARGE_ID}

请求示例

curl https://api.pingxx.com/v1/charges/ch_L8qn10mLmr1GS8e5OODmHaL4 \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
  "id": "ch_L8qn10mLmr1GS8e5OODmHaL4",
  "object": "charge",
  "created": 1410834527,
  "livemode": true,
  "paid": false,
  "refunded": false,
  "reversed": false,
  "app": "app_1Gqj58ynP0mHeX1q",
  "channel": "upacp",
  "order_no": "123456789",
  "client_ip": "127.0.0.1",
  "amount": 100,
  "amount_settle": 100,
  "currency": "cny",
  "subject": "Your Subject",
  "body": "Your Body",
  "extra":{},
  "time_paid": null,
  "time_expire": 1410838127,
  "time_settle": null,
  "transaction_no": null,
  "refunds": {
    "object": "list",
    "url": "/v1/charges/ch_L8qn10mLmr1GS8e5OODmHaL4/refunds",
    "has_more": false,
    "data": [ ]
  },
  "amount_refunded": 0,
  "failure_code": null,
  "failure_msg": null,
  "metadata": {},
  "credential": {
    "object": "credential",
    "upacp": {
      "tn": "201409161028470000000",
      "mode": "01"
    }
  },
  "description": null
}

查询 Charge 对象列表

返回之前创建过 charge 对象的一个列表。列表是按创建时间进行排序,总是将最新的 charge 对象显示在最前。

请求参数
limit optional 限制有多少对象可以被返回,限制范围是从 1~100 项,默认是 10 项。
starting_after optional 在分页时使用的指针,决定了列表的第一项从何处开始。假设你的一次请求返回列表的最后一项的 idobj_end ,你可以使用 starting_after = obj_end 去获取下一页。
ending_before optional 在分页时使用的指针,决定了列表的最末项在何处结束。假设你的一次请求返回列表的第一项的 idobj_start ,你可以使用 ending_before = obj_start 去获取上一页。
created optional 对象的创建时间,用 Unix 时间戳表示。具体参考下表 created 参数。
app [ id ] expandable required 支付使用的 app 对象的 id ,expandable 可展开,查看 如何获取App ID
channel optional 支付使用的支付渠道。参考 支付渠道属性值
paid optional 是否已付款。
refunded optional 是否存在退款信息,无论退款是否成功。
reversed optional 是否已撤销。
created 参数
created [ gt ] optional int 大于 charge 对象的创建时间,用 Unix 时间戳表示。
created [ gte ] optional int 大于或等于 charge 对象的创建时间,用 Unix 时间戳表示。
created [ lt ] optional int 小于 charge 对象的创建时间,用 Unix 时间戳表示。
created [ lte ] optional int 小于或等于 charge 对象的创建时间,用 Unix 时间戳表示。

返回

返回一个已存在的 charge 对象列表或者一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/charges?expand[]=app

请求示例

curl https://api.pingxx.com/v1/charges/?limit=3&expand[]=app \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
  "object": "list",
  "url": "/v1/charges",
  "has_more": false,
  "data": [
    {
      "id": "ch_L8qn10mLmr1GS8e5OODmHaL4",
      "object": "charge",
      "created": 1410834527,
      "livemode": true,
      "paid": false,
      "refunded": false,
      "reversed": false,
      "app": "app_1Gqj58ynP0mHeX1q",
      "channel": "upacp",
      "order_no": "123456789",
      "client_ip": "127.0.0.1",
      "amount": 100,
      "amount_settle": 100,
      "currency": "cny",
      "subject": "Your Subject",
      "body": "Your Body",
      "extra":{},
      "time_paid": null,
      "time_expire": 1410838127,
      "time_settle": null,
      "transaction_no": null,
      "refunds": {
        "object": "list",
        "url": "/v1/charges/ch_L8qn10mLmr1GS8e5OODmHaL4/refunds",
        "has_more": false,
        "data": [ ]
      },
      "amount_refunded": 0,
      "failure_code": null,
      "failure_msg": null,
      "metadata": {},
      "credential": {
        "object": "credential",
        "upacp": {
          "tn": "201409161028470000000",
          "mode": "01"
        }
      },
      "description": null
    }
  ]
}

Charge 相关的 Event 类型

该类型的 Event 对象会在 charge 对象支付成功后触发,以 Webhooks 形式发送至客户配置的 Webhooks URL。详情请参考 Events 事件

事件类型
charge.succeeded 支付对象,支付成功时触发。

示例对象

{
	"id": "evt_ugB6x3K43D16wXCcqbplWAJo",
	"created": 1427555101,
	"livemode": true,
	"type": "charge.succeeded",
	"data": {
		"object": {
			"id": "ch_Xsr7u35O3m1Gw4ed2ODmi4Lw",
			"object": "charge",
			"created": 1427555076,
			"livemode": true,
			"paid": true,
			"refunded": false,
			"reversed": false,
			"app": "app_1Gqj58ynP0mHeX1q",
			"channel": "upacp",
			"order_no": "123456789",
			"client_ip": "127.0.0.1",
			"amount": 100,
			"amount_settle": 100,
			"currency": "cny",
			"subject": "Your Subject",
			"body": "Your Body",
			"extra": {},
			"time_paid": 1427555101,
			"time_expire": 1427641476,
			"time_settle": null,
			"transaction_no": "1224524301201505066067849274",
			"refunds": {
				"object": "list",
				"url": "/v1/charges/ch_L8qn10mLmr1GS8e5OODmHaL4/refunds",
				"has_more": false,
				"data": []
			},
			"amount_refunded": 0,
			"failure_code": null,
			"failure_msg": null,
			"metadata": {},
			"credential": {},
			"description": null
		}
	},
	"object": "event",
	"pending_webhooks": 0,
	"request": "iar_qH4y1KbTy5eLGm1uHSTS00s"
}

Refunds 退款

refund 对象允许你可以对已经支付的 charge 对象发起退款请求。

属性
id string 退款对象 id ,由 Ping++ 生成,27 位长度字符串。
object string 值为 "refund"。
order_no string 退款的订单号,由 Ping++ 生成。
amount int 退款金额大于 0,单位为对应币种的最小货币单位,例如:人民币为分(如退款金额为 1 元,此处请填 100)。
succeed boolean 退款是否成功。
status string 退款状态(目前支持三种状态: pending: 处理中; succeeded: 成功; failed: 失败)。
created timestamp 退款创建的时间,用 Unix 时间戳表示。
time_succeed timestamp 退款成功的时间,用 Unix 时间戳表示。
description string 退款详情,最多 255 个 Unicode 字符。
failure_code string 退款的错误码,详见 错误 中的错误码。
failure_msg string 退款消息的描述。
metadata hash 参考 元数据
charge string refund 对象的所在 charge 对象的 id
charge_order_no string 商户订单号,这边返回的是 charge 对象中的 order_no 参数。
transaction_no string 支付渠道返回的交易流水号,部分渠道返回该字段为空。
funding_source string 微信退款资金来源。取值范围: unsettled_funds :使用未结算资金退款; recharge_funds :使用可用余额退款。注:默认值 unsettled_funds ,该参数仅适用于所有微信渠道老资金流商户使用,包括 wxwx_pubwx_pub_qrwx_litewx_wap 五个渠道;新资金流退款资金默认从基本账户中扣除。该参数仅在请求退款,传入该字段时返回。

示例对象

{
  "id": "re_y1u944PmfnrTHyvnL0nD0iD1",
  "object": "refund",
  "order_no": "y1u944PmfnrTHyvnL0nD0iD1",
  "amount": 9,
  "created": 1409634160,
  "succeed": true,
  "status": "succeeded",
  "time_succeed": 1409634192,
  "description": "Refund Description",
  "failure_code": null,
  "failure_msg": null,
  "metadata": {},
  "charge": "ch_L8qn10mLmr1GS8e5OODmHaL4",
  "charge_order_no": "123456789",
  "transaction_no": "2004450349201512090096425284"
}

创建 Refund 对象

通过发起一次退款请求创建一个新的 refund 对象,只能对已经发生交易并且没有全额退款的 charge 对象发起退款。当进行全额退款之前,可以进行多次退款,直至全额退款。当一次退款成功后,会发送 Webhooks 通知。

请求参数
id required charge 对象的 id
amount optional 退款金额大于 0, 单位为对应币种的最小货币单位,例如:人民币为分(如退款金额为 1 元,此处请填 100)。必须小于等于可退款金额,默认为全额退款。
metadata optional 参考 元数据
description required 退款详情,最多 255 个 Unicode 字符。
funding_source optional 微信退款资金来源。取值范围: unsettled_funds :使用未结算资金退款; recharge_funds :使用可用余额退款。注:默认值 unsettled_funds ,该参数仅适用于所有微信渠道老资金流商户使用,包括 wxwx_pubwx_pub_qrwx_litewx_wap 五个渠道;新资金流退款资金默认从基本账户中扣除。该参数仅在请求退款,传入该字段时返回。

返回

如果发起退款成功,返回一个退款 refund 对象。如果发生错误,则会返回错误码和错误详情,详见 错误

定义

POST https://api.pingxx.com/v1/charges/{CHARGE_ID}/refunds

请求示例

curl https://api.pingxx.com/v1/charges/ch_L8qn10mLmr1GS8e5OODmHaL4/refunds \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d description="Refund Description" \
-X POST

返回示例

{
  "id": "re_y1u944PmfnrTHyvnL0nD0iD1",
  "object": "refund",
  "order_no": "y1u944PmfnrTHyvnL0nD0iD1",
  "amount": 9,
  "created": 1409634160,
  "succeed": true,
  "status": "succeeded",
  "time_succeed": 1409634192,
  "description": "Refund Description",
  "failure_code": null,
  "failure_msg": null,
  "metadata": {},
  "charge": "ch_L8qn10mLmr1GS8e5OODmHaL4",
  "charge_order_no": "123456789",
  "transaction_no": "2004450349201512090096425284"
}

查询 Refund 对象

可以通过 charge 对象的查询接口查询某一个 charge 对象的退款列表,也可以通过 refund 对象的 id 查询一个已创建的 refund 对象。可以在 Webhooks 通知之前,通过查询接口确认退款状态。

请求参数
id required 查询的 refund 对象 id
charge required 退款的 charge 对象 id

返回

返回一个已存在的 refund 对象或者一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/charges/{CHARGE_ID}/refunds/{REFUND_ID}

请求示例

curl https://api.pingxx.com/v1/charges/ch_L8qn10mLmr1GS8e5OODmHaL4/refunds/re_TmbvDKHiXLCSG0mnj9jnDyjA \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
  "id": "re_y1u944PmfnrTHyvnL0nD0iD1",
  "object": "refund",
  "order_no": "y1u944PmfnrTHyvnL0nD0iD1",
  "amount": 9,
  "created": 1409634160,
  "succeed": true,
  "status": "succeeded",
  "time_succeed": 1409634192,
  "description": "Refund Description",
  "failure_code": null,
  "failure_msg": null,
  "metadata": {},
  "charge": "ch_L8qn10mLmr1GS8e5OODmHaL4",
  "charge_order_no": "123456789",
  "transaction_no": "2004450349201512090096425284"
}

查询 Refund 对象列表

返回之前创建 charge 对象的一个 refund 对象列表。列表是按创建时间进行排序,总是将最新的 refund 对象显示在最前。

请求参数
id required 指定退款所在 charge 对象的 id
limit optional 限制每页可以返回多少对象,范围为 1~100 项,默认是 10 项。
starting_after optional 在分页时使用的指针,决定了列表的第一项从何处开始。假设你的一次请求返回列表的最后一项的 idobj_end ,你可以使用 starting_after = obj_end 去获取下一页。
ending_before optional 在分页时使用的指针,决定了列表的最末项在何处结束。假设你的一次请求返回列表的第一项的 idobj_start ,你可以使用 ending_before = obj_start 去获取上一页。

返回

根据请求参数返回一个 refund 对象列表,如果列表为空,则返回的 data 为空数组。遇到错误时返回相应错误信息,详见 错误

定义

GET https://api.pingxx.com/v1/charges/{CHARGE_ID}/refunds

请求示例

curl https://api.pingxx.com/v1/charges/ch_L8qn10mLmr1GS8e5OODmHaL4/refunds?limit=3 \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
  "object": "list",
  "url": "/v1/charges/ch_L8qn10mLmr1GS8e5OODmHaL4/refunds",
  "has_more": false,
  "data": [
    {
      "id": "re_TmbvDKHiXLCSG0mnj9jnDyjA",
      "object": "refund",
      "order_no": "TmbvDKHiXLCSG0mnj9jnDyjA",
      "amount": 100,
      "created": 1410835214,
      "succeed": true,
      "status": "succeeded",
      "time_succeed": 1410835652,
      "description": "Refund Description",
      "failure_code": null,
      "failure_msg": null,
      "metadata": {},
      "charge": "ch_L8qn10mLmr1GS8e5OODmHaL4",
      "charge_order_no": "123456789",
      "transaction_no": "2004450349201512090096425284"
    }
  ]
}

Refund 相关的 Event 类型

该类型的 Event 对象会在 refund 对象退款成功后触发,以 Webhooks 形式发送至客户配置的 Webhooks URL。详情请参考 Events 事件

事件类型
refund.succeeded 退款对象,退款成功时触发.

示例对象

{
    "id": "evt_gJKelawq06CiPojS5gt3noQA",
    "created": 1427555348,
    "livemode": true,
    "type": "refund.succeeded",
    "data": {
        "object": {
            "id": "re_SG0mnjTD3jAHimbvDKjnXLC9",
            "object": "refund",
            "order_no": "SG0mnjTD3jAHimbvDKjnXLC9",
            "amount": 100,
            "created": 1427555346,
            "succeed": true,
            "status": "succeeded",
            "time_succeed": 1427555348,
            "description": "Refund Description",
            "failure_code": null,
            "failure_msg": null,
            "metadata": {},
            "charge": "ch_Xsr7u35O3m1Gw4ed2ODmi4Lw"
        }
    },
    "object": "event",
    "pending_webhooks": 0,
    "request": "iar_Ca1Oe10OqTSOPOmzX9Hi1a5"
}

Batch Refunds 批量退款

支付宝的退款流程比较特殊,需要人工介入(点击退款链接输入商家密码完成退款),所以你可以调用该接口完成支付宝 alipayalipay_wapalipay_pc_direct 三个渠道的订单批量退款;其他渠道的退款,可以通过重复调用退款接口实现。 以下是该退款接口的注意点:

  • 批量退款接口,目前只支持全额退款,若存在部分退款的订单,则会把此类订单的剩余金额全部退完;
  • 目前支持三个渠道的订单 alipay, alipay_wap, alipay_pc_direct
  • 需要发起退款的 charge 列表,不可以有重复的 charge id,必须全部是已支付并且未全额退款的状态;
  • 批量退款中,任意一笔订单信息不符合以上 3 条规则之一,则批量请求中的所有订单退款均会失败,抛出首个报错的 charge 信息;
  • 批量退款对象创建成功后,需要使用浏览器打开 refund_url 字段所对应的地址,商家进行退款操作并且输入支付宝支付密码;
  • 批量退款成功后,调用批量退款查询接口不会返回退款链接,refund_url字段为空;
  • 批量退款请求中同时有不同的支付宝渠道时,必须是同一套参数(公私钥),否则打开链接跳转后会报错。
  • 查询批量退款列表接口的 GET 请求强制要求签名,必须生成 RSA 签名(SHA256)并在请求头中添加 Pingplusplus-Signature 字段,需在管理平台上配置商户公钥;同时必须在请求头中添加 Pingplusplus-Request-Timestamp 字段,其值为请求接口的 Unix 时间戳;其他接口请求暂不要求强制签名。
属性
id string 批量退款对象 id ,由 Ping++ 生成。
app string 批量退款对应的 app 对象 ID,查看 如何获取App ID
object string 值为 "batch_refund"。
batch_no string 批量退款批次号,3-24位,允许字母和英文。
created int 批量退款创建时间,用 Unix 时间戳表示。
description string 批量退款详情,最多 255 个 Unicode 字符。
metadata hash 参考 元数据
charges array 需要退款的 charge id 列表。
refunds list 退款详情列表,详见 refund 退款
refund_url string 退款 URL,仅在渠道为支付宝时有值,你需要获取该地址,在浏览器中打开并且输入支付宝支付密码才能完成退款。

对象示例

{
    "id": "151608161453545102",
    "app": "app_abcdefghweqzadfs",
    "object": "batch_refund",
    "batch_no": "batchrefund20160801001",
    "created": 1409634192,
    "description": "Batch refund description.",
    "charges": [
        "ch_L8qn10mLmr1GS8e5OODmHaL4",
        "ch_fdOmHaLmLmr1GOD4qn1dS8e5"
    ],
    "refunds": {
        "object": "list",
        "url": null,
        "has_more": false,
        "data": [
            {
                "id": "re_y1u944PmfnrTHyvnL0nD0iD1",
                "object": "refund",
                "order_no": "y1u944PmfnrTHyvnL0nD0iD1",
                "amount": 10,
                "created": 1409634160,
                "succeed": true,
                "status": "succeeded",
                "time_succeed": 1409634192,
                "description": "Batch refund description.",
                "failure_code": null,
                "failure_msg": null,
                "metadata": {},
                "charge": "ch_L8qn10mLmr1GS8e5OODmHaL4",
                "charge_order_no": "123456789",
                "transaction_no": "2004450349201512090096425280"
            },
            {
                "id": "re_nL0nD0iDPmfy1u944HyvnrT1",
                "object": "refund",
                "order_no": "nL0nD0iDPmfy1u944HyvnrT1",
                "amount": 10,
                "created": 1409634160,
                "succeed": true,
                "status": "succeeded",
                "time_succeed": 1409634192,
                "description": "Batch refund description.",
                "failure_code": null,
                "failure_msg": null,
                "metadata": {},
                "charge": "ch_fdOmHaLmLmr1GOD4qn1dS8e5",
                "charge_order_no": "123456789",
                "transaction_no": "2004450349201512090096425281"
            }
        ]
    },
    "refund_url": null
}

创建 Batch Refund 对象

创建一个 batch refund 对象来发起支付宝批量退款。

请求参数
app required 批量退款对应的 app 对象 ID,查看 如何获取App ID
batch_no required 批量退款批次号,3-24位,允许字母和英文。
charges required 需要退款的 charge id 列表,一次最多 100 个。
description optional 批量退款详情,最多 255 个 Unicode 字符。
metadata optional 参考 元数据

返回

返回一个 batch refund 对象或者一个错误,详见 错误

定义

POST https://api.pingxx.com/v1/batch_refunds

请求示例

curl  https://api.pingxx.com/v1/batch_refunds \
-H "Content-Type: application/json" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "app": "app_abcdefghweqzadfs",
    "batch_no": "batchrefund20160801001",
    "description": "Batch refund description.",
    "charges": [
        "ch_L8qn10mLmr1GS8e5OODmHaL4",
        "ch_fdOmHaLmLmr1GOD4qn1dS8e5"
    ]
}'

返回示例

{
    "id": "151608161453545122",
    "app": "app_abcdefghweqzadfs",
    "object": "batch_refund",
    "batch_no": "batchrefund20160801001",
    "created": 1409634192,
    "description": "Batch refund description.",
    "charges": [
        "ch_L8qn10mLmr1GS8e5OODmHaL4",
        "ch_fdOmHaLmLmr1GOD4qn1dS8e5"
    ],
    "refunds": {
        "object": "list",
        "url":null,
        "has_more": false,
        "data": [
            {
                "id": "re_y1u944PmfnrTHyvnL0nD0iD1",
                "object": "refund",
                "order_no": "y1u944PmfnrTHyvnL0nD0iD1",
                "amount": 10,
                "created": 1409634160,
                "succeed": true,
                "status": "succeeded",
                "time_succeed": 1409634192,
                "description": "Batch refund description.",
                "failure_code": null,
                "failure_msg": null,
                "metadata": {},
                "charge": "ch_L8qn10mLmr1GS8e5OODmHaL4",
                "charge_order_no": "123456789",
                "transaction_no": "2004450349201512090096425284"
            },
            {
                "id": "re_nL0nD0iDPmfy1u944HyvnrT1",
                "object": "refund",
                "order_no": "nL0nD0iDPmfy1u944HyvnrT1",
                "amount": 10,
                "created": 1409634160,
                "succeed": true,
                "status": "succeeded",
                "time_succeed": 1409634192,
                "description": "Batch refund description.",
                "failure_code": null,
                "failure_msg": null,
                "metadata": {},
                "charge": "ch_fdOmHaLmLmr1GOD4qn1dS8e5",
                "charge_order_no": "123456789",
                "transaction_no": "2004450349201512090096425285"
            }
        ]
    },
    "refund_url": "https://mapi.alipay.com/gateway.do?..."
}

查询 Batch Refund 对象

你可以使用 batch_refund_id 来查询对应的 batch refund 对象信息。

请求参数
id required 批量退款对象 id ,由 Ping++ 生成。

返回

返回一个 batch refund 对象或者一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/batch_refunds/{BATCH_REFUND_ID}

请求示例

curl https://api.pingxx.com/v1/batch_refunds/151608161453545122 \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "id": "151608161453545102",
    "app": "app_abcdefghweqzadfs",
    "object": "batch_refund",
    "batch_no": "batchrefund20160801001",
    "created": 1409634192,
    "description": "Batch refund description.",
    "charges": [
        "ch_L8qn10mLmr1GS8e5OODmHaL4",
        "ch_fdOmHaLmLmr1GOD4qn1dS8e5"
    ],
    "refunds": {
        "object": "list",
        "url": null,
        "has_more": false,
        "data": [
            {
                "id": "re_y1u944PmfnrTHyvnL0nD0iD1",
                "object": "refund",
                "order_no": "y1u944PmfnrTHyvnL0nD0iD1",
                "amount": 10,
                "created": 1409634160,
                "succeed": true,
                "status": "succeeded",
                "time_succeed": 1409634192,
                "description": "Batch refund description.",
                "failure_code": null,
                "failure_msg": null,
                "metadata": {},
                "charge": "ch_L8qn10mLmr1GS8e5OODmHaL4",
                "charge_order_no": "123456789",
                "transaction_no": "2004450349201512090096425280"
            },
            {
                "id": "re_nL0nD0iDPmfy1u944HyvnrT1",
                "object": "refund",
                "order_no": "nL0nD0iDPmfy1u944HyvnrT1",
                "amount": 10,
                "created": 1409634160,
                "succeed": true,
                "status": "succeeded",
                "time_succeed": 1409634192,
                "description": "Batch refund description.",
                "failure_code": null,
                "failure_msg": null,
                "metadata": {},
                "charge": "ch_fdOmHaLmLmr1GOD4qn1dS8e5",
                "charge_order_no": "123456789",
                "transaction_no": "2004450349201512090096425281"
            }
        ]
    },
    "refund_url": null
}

查询 Batch Refund 对象列表

你可以使用调用该接口来查询对应的 batch refund 对象列表信息。

请求参数
page optional int 页码,取值范围:1~1000000000;默认值为"1"。
per_page optional int 每页数量,取值范围:1~100;默认值为"10"。
created [ gt ] optional int 创建时间大于该值。
created [ gte ] optional int 创建时间大于或等于该值。
created [ lt ] optional int 创建时间小于该值。
created [ lte ] optional int 创建时间小于或等于该值。
app optional string 批量退款对应的 app 对象 ID,查看 如何获取App ID

返回

返回一个 batch refund 对象列表或者一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/batch_refunds?app={app_id}

请求示例

curl https://api.pingxx.com/v1/batch_refunds?app={app_id} \
-H "Content-Type: application/json; charset=utf-8" \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Pingplusplus-Request-Timestamp: 1476067085" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
  "object": "list",
  "url": "/v1/batch_refunds",
  "has_more": true,
  "data": [
      {
          "id": "151608191520130289",
          "object": "batch_refund",
          "app": "app_abcdefghweqzadfs",
          "created": 1471591213,
          "livemode": true,
          "batch_no": "batchrefundw20e8016w00w5",            
          "charges": [
              "ch_m5iTe9vfP4a5nfPuz99OmT48",
              "ch_nLCK8O0yHqP4zDybLGi1GOKS",
              "ch_8K8qL0aLuz1CDCu58K0m9SO4"
          ],
          "refunds": {
              "object": "list",
              "url": null,
              "has_more": false,
              "data": [
                  {
                     "id": "re_480mXL8eDq1KSGOGKSebnTu9",
                     "object": "refund",
                     "order_no": "480mXL8eDq1KSGOGKSebnTu9",
                     "amount": 1,
                     "succeed": false,
                     "status": "pending",
                     "created": 1471591213,
                     "time_succeed": null,
                     "description": "Batch refund description.",
                     "failure_code": null,
                     "failure_msg": null,
                     "metadata": {
                     },
                     "charge": "ch_nLCK8O0yHqP4zDybLGi1GOKS",
                     "charge_order_no": "20160426012",
                     "transaction_no": null
                   },
                   {
                      "id": "re_80unvLij1WTSbLGOGSHmnzP0",
                      "object": "refund",
                      "order_no": "80unvLij1WTSbLGOGSHmnzP0",
                      "amount": 9,
                      "succeed": false,
                      "status": "pending",
                      "created": 1471591213,
                      "time_succeed": null,
                      "description": "Batch refund description.",
                      "failure_code": null,
                      "failure_msg": null,
                      "metadata": {
                      },
                      "charge": "ch_8K8qL0aLuz1CDCu58K0m9SO4",
                      "charge_order_no": "T160226095516pQ",
                      "transaction_no": null
                  },
                  {
                     "id": "re_LCWD8O8GaP441arfb5qn9efP",
                     "object": "refund",
                     "order_no": "LCWD8O8GaP441arfb5qn9efP",
                     "amount": 1,
                     "succeed": false,
                     "status": "pending",
                     "created": 1471591213,
                     "time_succeed": null,
                     "description": "Batch refund description.",
                     "failure_code": null,
                     "failure_msg": null,
                        "metadata": {
                        },
                        "charge": "ch_m5iTe9vfP4a5nfPuz99OmT48",
                        "charge_order_no": "20160125103012",
                        "transaction_no": null
                    }
                ]
            },
            "refund_url": "https://mapi.alipay.com/gateway.do?service=refund_fastpay_by_platform_pwd&partner=2088711316963982&_input_charset=utf-8&notify_url=http%3A%2F%2F218.244.151.190%2Fnotify%2Fbatch_refunds%2F151608191520130289&seller_user_id=2088711316963982&refund_date=2016-08-19%2015%3A20%3A13&batch_no=20160819batchrefundw20e8016w00w5&batch_num=3&detail_data=2016022621001004920228205160%5E0.09%5EBatch%20refund%20description.%232016012521001004920027269239%5E0.01%5EBatch%20refund%20description.%232016042621001004290267984563%5E0.01%5EBatch%20refund%20description.&sign=p431TPLEdayicFAKxwhnBUknZyV7Fe21vAzTimXwMMBcoCa58hEBFaldOVLmMNkUB6NDbu5Uf6CigPkQlIqF8QP4qLtNLnTrwsGvYncTwO6bduTN2kIjSIeQhKYHl%2B%2BbQtb56q9V2JVoGFCz3IfHjcODC4hP2bTfqrL6f26rdNE%3D&sign_type=RSA",
            "description": "Batch refund description.",
            "metadata": {
            }
        },
        {
            "id": "151608191443239949",
            "object": "batch_refund",
            "app": "app_abcdefghweqzadfs",
            "created": 1471589003,
            "livemode": true,
            "batch_no": "batchrefundw20e801600w5",
            "charges": [
                "ch_m5iTe9vfP4a5nfPuz99OmT48"
            ],
            "refunds": {
                "object": "list",
                "url": null,
                "has_more": false,
                "data": [
                    {
                      "id": "re_CC4O44LuXvH8SevvLGSa5y94",
                      "object": "refund",
                      "order_no": "CC4O44LuXvH8SevvLGSa5y94",
                      "amount": 1,
                      "succeed": false,
                      "status": "pending",
                      "created": 1471589003,
                      "time_succeed": null,
                      "description": "Batch refund description.",
                      "failure_code": null,
                      "failure_msg": null,
                      "metadata": {
                     },
                      "charge": "ch_m5iTe9vfP4a5nfPuz99OmT48",
                      "charge_order_no": "20160125103012",
                      "transaction_no": null
                  }
              ]
          },
          "refund_url": "https://mapi.alipay.com/gateway.do?service=refund_fastpay_by_platform_pwd&partner=2088711316963982&_input_charset=utf-8&notify_url=http%3A%2F%2F218.244.151.190%2Fnotify%2Fbatch_refunds%2F151608191443239949&seller_user_id=2088711316963982&refund_date=2016-08-19%2014%3A43%3A23&batch_no=20160819batchrefundw20e801600w5&batch_num=1&detail_data=2016012521001004920027269239%5E0.01%5EBatch%20refund%20description.&sign=HpYKWf4ZJSVN6gShkiCl82kEEKLtGJRuNmlIjrjOdeVJrvW1LjytpME8ivxykwG3U6AzO%2BUDgHrasIdHSokSSQXzEQRC4cmMqt4aSOQYEQ5fmUDkg44WvnjqJqVCBKtU6NugiNXKVm9YSIpk5cCd9szbkOKu04Y2MUK5AS1Fp4o%3D&sign_type=RSA",
          "description": "Batch refund description.",
          "metadata": {
            }
        },
        {...}
    ]
}

Batch Refund 相关的 Event 类型

该类型的 Event 对象会在 batch_refund 对象批量退款成功后触发,以 Webhooks 形式发送至客户配置的 Webhooks URL。详情请参考 Events 事件

事件类型
batch_refund.succeeded 批量退款对象,批量退款成功时触发。

示例对象

{
  "id": "evt_401170207171021000437700",
  "created": 1486458621,
  "livemode": true,
  "type": "batch_refund.succeeded",
  "data": {
      "object": {
      "app": "app_LibTW1n1SOq9Pin1",
      "batch_no": "467223445889520",
      "charges": [
        {
          "charge": "ch_Pi504CajrLyHLSCOOKpyXnX5",
          "status": "succeeded"
        },
        {
          "charge": "ch_CWDKSKbvHq981TSOO8uk0Se5",
          "status": "succeeded"
        },
        {
          "charge": "ch_9ejPy94qj519bTejT8u1X9GC",
          "status": "succeeded"
        }
      ],
      "created": 1486458591,
      "description": "Batch refund description.",
      "id": "1511702071709512304",
      "livemode": true,
      "metadata": {},
      "object": "batch_refund",
      "refund_url": null,
      "refunds": {
        "data": [
          {
            "amount": 5,
            "charge": "ch_CWDKSKbvHq983TSOO8u00Se5",
            "charge_order_no": "T170207050849Sh",
            "created": 1486458594,
            "description": "Batch refund description.",
            "failure_code": null,
            "failure_msg": null,
            "id": "re_rLWHWHKajPu9urPqvPmnrbrP",
            "metadata": {},
            "object": "refund",
            "order_no": "rLWHWHKajPu9urPqvPmnrbrP",
            "status": "succeeded",
            "succeed": true,
            "time_succeed": 1486458602,
            "transaction_no": "2000000001001702070816030296"
          },
          {
            "amount": 5,
            "charge": "ch_9ejPy94qj5u9bTej08uzX9GC",
            "charge_order_no": "T170207050840eA",
            "created": 1486458595,
            "description": "Batch refund description.",
            "failure_code": null,
            "failure_msg": null,
            "id": "re_rbTGi11yDKqP0ujnL4mnPinP",
            "metadata": {},
            "object": "refund",
            "order_no": "rbTGi11yDKqP0ujnL4mnPinP",
            "status": "succeeded",
            "succeed": true,
            "time_succeed": 1486458604,
            "transaction_no": "2700002001201700370816029893"
          },
          {
            "amount": 5,
            "charge": "ch_Pi504CajrLyHLSCOO0DyXnX5",
            "charge_order_no": "T170207050857df",
            "created": 1486458596,
            "description": "Batch refund description.",
            "failure_code": null,
            "failure_msg": null,
            "id": "re_n9SCCCy9WL00inz5WPazX94S",
            "metadata": {},
            "object": "refund",
            "order_no": "n9SCCCy9WL00inz5WPazX94S",
            "status": "succeeded",
            "succeed": true,
            "time_succeed": 1486458604,
            "transaction_no": "2000002001201702071815736474"
          }
        ],
        "has_more": false,
        "object": "list",
        "url": null
      },
      "status": "succeeded",
      "time_succeeded": 1486458621
    }
  },
  "object": "event",
  "request": "iar_rDmfnTyb5ab1z61SOO9qPSKS",
  "pending_webhooks": 0
}

Transfers 企业付款

你可以请求一个 transfer 对象向个人用户或企业账户发起微信(仅支持向个人用户转账)、支付宝或者银行卡的转账。所有与企业付款相关的要素信息都存储在 transfer 对象之中,你可以通过发起企业付款请求创建新的 transfer 对象,也可以随时查看企业付款对象的状态。每个 transfer 对象都拥有一个标识 id,该 id 在系统内唯一。

注:微信服务商模式商户暂不支持企业付款。

属性
id string 企业付款对象 id ,由 Ping++ 生成,27 位长度字符串。
object string 值为 "transfer"。
type string 付款类型,转账到个人用户为 b2c,转账到企业用户为 b2b(微信公众号、小程序和余额的企业付款,仅支持 b2c)。
created timestamp 创建时间,用 Unix 时间戳表示。
time_transferred timestamp 支付完成时间, 用 Unix 时间戳表示。由第三方支付渠道返回。
livemode boolean 是否是 live 模式。
status string 付款状态。目前支持 5 种状态:pending: 处理中; paid: 付款成功; failed: 付款失败;scheduled:待发送,unionpay渠道的转账会在请求成功后延时5分钟发送,5分钟内处于待发送状态;canceled:取消发送,更新(取消)转账后的订单状态。
app expandable string 转账对应的 app 对象的 idexpandable 可展开,查看 如何获取App ID
channel string 付款使用的第三方支付渠道名称。目前支持 wx_pub (微信公众号)、 wx_lite (微信小程序)、 alipay (支付宝)、 unionpay (银联电子代付)、 allinpay (通联代付)、 jdpay (京东代付)、 unionpay_gz (贵州银联代付)和 balance (余额)。
order_no string 付款使用的商户内部订单号。 wx_pubwx_lite 规定为 1 ~ 32 位不能重复的数字字母组合; alipay 为 1 ~ 64 位不能重复的数字字母组合; unionpay 为1~16位的纯数字; allinpay 为 20 ~ 40 位不能重复的数字字母组合,必须以签约的通联的商户号开头(建议组合格式:通联商户号 + 时间戳 + 固定位数顺序流水号,不包含+号); unionpay_gz 为 1 ~ 32 位不能重复的数字字母组合; jdpay 为 1 ~ 64 位不能重复的数字字母组合。
amount int 付款金额,相关渠道的限额,请查看 帮助中心 。单位为对应币种的最小货币单位,例如:人民币为分。
amount_settle int 清算金额,单位为对应币种的最小货币单位,例如:人民币为分。
currency string 三位 ISO 货币代码,目前仅支持人民币 cny。
recipient string 接收者 id, 微信企业付款时为用户在 wx_pubwx_lite 下的 open_id ;渠道为 unionpayunionpay_gz 时,不需要传该参数;渠道为 alipay 时,若 type 为 b2c,为个人支付宝账号,若 type 为 b2b,为企业支付宝账号;渠道为 jdpayallinpay 时,可不传该参数。渠道为 balance 时,为用户在当前 app 下的用户 id。
description string 备注信息,最多 255 个 Unicode 字符。渠道为 unionpay 时,最多 99 个 Unicode 字符;渠道为 wx_pubwx_lite 时,最多 99 个英文和数字的组合或最多 33 个中文字符,不可以包含特殊字符;渠道为 alipayjdpay 时,最多 100 个 Unicode 字符;渠道为 unionpay_gz 时,最多 20 个 Unicode 字符;为渠道为 allinpay 时,最多 30 个 Unicode 字符。
metadata hash 参考 元数据
transaction_no string 交易流水号,由第三方渠道提供。
failure_msg string 企业付款订单的错误消息的描述。
extra object transfer 相关的附加参数,详情参考 extra参数说明

示例对象

{
  "id": "tr_HqbzHCvLOaL4La1ezHfDWTqH",
  "object": "transfer",
  "type": "b2c",
  "created": 1432724825,
  "time_transferred": null,
  "livemode": true,
  "status": "pending",
  "app": "app_1Gqj58ynP0mHeX1q",
  "channel": "wx_pub",
  "order_no": "123456789",
  "amount": 100,
  "amount_settle": 100,
  "currency": "cny",
  "recipient": "o7zpMs5MW2-52GAy5hRrjdYVCktU",
  "description": "Your Description",
  "transaction_no": "1000018301201505200184147302",
  "failure_msg":null,
  "extra": {
      "user_name": "User Name",
      "force_check": true
  }
}

创建 Transfer 对象

你可以请求一个新的 transfer 对象发起一次企业付款。如果支付失败,请检查错误信息,一般是由于账户余额不足引起的。

使用测试模式的 API Key,则不会发生真实交易。测试模式需要主动查询transfer 对象的状态,Ping++ 才会发送 Webhooks 通知。

注:1、渠道为wx_litealipayunionpayallinpayjdpayunionpay_gz 时,强制要求签名(Pingplusplus-Signature),需在管理平台上配置商户公钥,但无须开启;2、unionpay 渠道的转账会延时5分钟发送,5分钟内可以调用更新Transfer接口取消该笔转账;3、微信服务商模式商户暂不支持企业付款。

请求参数
app [ id ] expandable required 转账使用的 app 对象的 idexpandable 可展开,查看 如何获取App ID
channel required 付款使用的第三方支付渠道名称。目前支持 wx_pub (微信公众号)、 wx_lite (微信小程序)、 alipay (支付宝)、 unionpay (银联电子代付)、 allinpay (通联代付)、 jdpay (京东代付)、 unionpay_gz (贵州银联代付)和 balance (余额)。
order_no required 付款使用的商户内部订单号。 wx_pubwx_lite 规定为 1 ~ 32 位不能重复的数字字母组合; alipay 为 1 ~ 64 位不能重复的数字字母组合; unionpay 为1~16位的纯数字; allinpay 为 20 ~ 40 位不能重复的数字字母组合,必须以签约的通联的商户号开头(建议组合格式:通联商户号 + 时间戳 + 固定位数顺序流水号,不包含+号); unionpay_gz 为 1 ~ 32 位不能重复的数字字母组合; jdpay 为 1 ~ 64 位不能重复的数字字母组合。
amount required 付款金额,相关渠道的限额,请查看 帮助中心 。单位为对应币种的最小货币单位,例如:人民币为分。
type required 付款类型,转账到个人用户为 b2c,转账到企业用户为 b2b(微信公众号、小程序和余额的企业付款,仅支持 b2c)。
currency required 三位 ISO 货币代码,目前仅支持人民币: cny
recipient required 接收者 id, 微信企业付款时为用户在 wx_pubwx_lite 下的 open_id ;渠道为 unionpayunionpay_gz 时,不需要传该参数;渠道为 alipay 时,若 type 为 b2c,为个人支付宝账号,若 type 为 b2b,为企业支付宝账号;渠道为 jdpayallinpay 时,可不传该参数。渠道为 balance 时,为用户在当前 app 下的用户 id。
description required 备注信息,最多 255 个 Unicode 字符。渠道为 unionpay 时,最多 99 个 Unicode 字符;渠道为 wx_pubwx_lite 时,最多 99 个英文和数字的组合或最多 33 个中文字符,不可以包含特殊字符;渠道为 alipayjdpay 时,最多 100 个 Unicode 字符;渠道为 unionpay_gz 时,最多 20 个 Unicode 字符;为渠道为 allinpay 时,最多 30 个 Unicode 字符。
metadata optional 参考 元数据
extra optional 相关的附加参数,详情参考 extra参数说明

返回

同步返回付款支付结果。如果发生错误,则会返回错误码和错误详情,详见 错误

定义

POST https://api.pingxx.com/v1/transfers

请求示例

curl https://api.pingxx.com/v1/transfers \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d order_no=123456789 \
-d app[id]=app_1Gqj58ynP0mHeX1q \
-d channel=wx_pub \
-d amount=100 \
-d currency=cny \
-d type=b2c \
-d recipient=Openid \
-d description="Your Description"

返回示例

{
  "id": "tr_HqbzHCvLOaL4La1ezHfDWTqH",
  "object": "transfer",
  "type": "b2c",
  "created": 1432724825,
  "time_transferred": null,
  "livemode": true,
  "status": "pending",
  "app": "app_1Gqj58ynP0mHeX1q",
  "channel": "wx_pub",
  "order_no": "123456789",
  "amount": 100,
  "amount_settle": 100,
  "currency": "cny",
  "recipient": "o7zpMs5MW2-52GAy5hRrjdYVCktU",
  "description": "Your Description",
  "transaction_no": "1000018301201505200184147302",
  "failure_msg":null,
  "extra": {
      "user_name": "User Name",
      "force_check": true
     }
}

查询 Transfer 对象

通过 transfer 对象的 id 查询一个已创建的 transfer 对象。

属性
id required 付款对象 id

返回

返回一个已存在的 transfer 对象或者一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/transfers/{TRANSFER_ID}

请求示例

curl https://api.pingxx.com/v1/transfers/tr_HqbzHCvLOaL4La1ezHfDWTqH \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "id": "tr_HqbzHCvLOaL4La1ezHfDWTqH",
    "object": "transfer",
    "type": "b2c",
    "created": 1432724825,
    "time_transferred": null,
    "livemode": true,
    "status": "pending",
    "app": "app_1Gqj58ynP0mHeX1q",
    "channel": "wx_pub",
    "order_no": "123456789",
    "amount": 100,
    "amount_settle": 100,
    "currency": "cny",
    "recipient": "o7zpMs5MW2-52GAy5hRrjdYVCktU",
    "description": "Your Description",
    "transaction_no": "1000018301201505200184147302",
    "failure_msg":null,
    "extra": {
        "user_name": "User Name",
        "force_check": true
    }
}

查询 Transfer 对象列表

返回之前创建过 transfer 对象的一个列表。列表是按创建时间进行排序,总是将最新的 transfer 对象显示在最前。

请求参数
limit optional 限制每页可以返回多少对象,范围为 1~100 项,默认是 10 项。
starting_after optional 在分页时使用的指针,决定了列表的第一项从何处开始。假设你的一次请求返回列表的最后一项的 idobj_end ,你可以使用 starting_after = obj_end 去获取下一页。
ending_before optional 在分页时使用的指针,决定了列表的最末项在何处结束。假设你的一次请求返回列表的第一项的 idobj_start ,你可以使用 ending_before = obj_start 去获取上一页。
created optional 对象的创建时间,用 Unix 时间戳表示,具体参考下表 created 参数。
app [ id ] expandable optional 转账使用的 app 对象的 idexpandable 可展开,查看 如何获取App ID
channel optional 付款使用的第三方支付渠道名称。目前支持 wx_pub (微信公众号)、 wx_lite (微信小程序)、 alipay (支付宝)、 unionpay (银联电子代付)、 allinpay (通联代付)、 jdpay (京东代付)、 unionpay_gz (贵州银联代付)和 balance (余额)。
status optional 付款状态。目前支持 5 种状态:pending: 处理中; paid: 付款成功; failed: 付款失败;scheduled:待发送,unionpay渠道的转账会在请求成功后延时5分钟发送,5分钟内处于待发送状态;canceled:取消发送,更新(取消)转账后的订单状态。
type optional 付款类型,转账到个人用户为 b2c,转账到企业用户为 b2b。
created 参数说明
created [ gt ] optional int 大于 transfer 对象的创建时间,用 Unix 时间戳表示。
created [ gte ] optional int 大于或等于 transfer 对象的创建时间,用 Unix 时间戳表示。
created [ lt ] optional int 小于 transfer 对象的创建时间,用 Unix 时间戳表示。
created [ lte ] optional int 小于或等于 transfer 对象的创建时间,用 Unix 时间戳表示。

返回

返回一个已存在的 transfer 对象的列表或者一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/transfers?expand[]=app

请求示例

curl https://api.pingxx.com/v1/transfers/?limit=3&expand[]=app
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
  "object": "list",
  "url": "/v1/transfers",
  "has_more": true,
  "data": [
      {
        "id": "tr_HqbzHCvLOaL4La1ezHfDWTqH",
        "object": "transfer",
        "type": "b2c",
        "created": 1432724825,
        "time_transferred": null,
        "livemode": true,
        "status": "pending",
        "app": "app_1Gqj58ynP0mHeX1q",
        "channel": "wx_pub",
        "order_no": "123456789",
        "amount": 100,
        "amount_settle": 100,
        "currency": "cny",
        "recipient": "Openid",
        "description": "Your Description",
        "transaction_no": "1000018301201505200184147302",
        "failure_msg":null,
        "extra": {
           "user_name": "User Name",
           "force_check": true
        }
     }
  ]
}

更新 Transfer 对象

你可以调用更新 transfer 对象接口来取消银联电子代付的转账订单。该接口只适用 unionpay 渠道,该渠道在 transfer 对象请求成功后,延时5分钟发送转账,5分钟内订单处于scheduled的准备发送状态,且可调用该接口通过 transfer 对象的 id 更新一个已创建的 transfer 对象,即取消该笔转账。

请求参数
id required unionpay 渠道的 transfer 对象 id
status required 更新 transfer 的状态,只支持 canceled

返回

返回一个更新成功的 transfer 对象或者一个错误,详见 错误

定义

PUT https://api.pingxx.com/v1/transfers/{TRANSFER_ID}

请求示例

curl https://api.pingxx.com/v1/transfers/tr_0eTi1OGqr9iH0i9CePf1a9C0 \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Content-Type: application/json" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "status":"canceled"
}'

返回示例

{
  "id": "tr_0eTi1OGqr9iH0i9CePf1a9C0",
  "object": "transfer",
  "type": "b2c",
  "created": 1467615446,
  "time_transferred": null,
  "livemode": true,
  "status": "canceled",
  "app": "app_1Gqj58ynP0mHeX1q",
  "channel": "unionpay",
  "order_no": "123456789",
  "amount": 100,
  "amount_settle": 100,
  "currency": "cny",
  "recipient": null,
  "description": "Your Description",
  "transaction_no": "371646",
  "failure_msg": null,
  "extra": {
      "card_number": "6225220317083517",
      "user_name": "张三丰",
      "open_bank_code": "0102"
  }
}

Transfer 相关的 Event 类型

该类型的 Event 对象会在 transfer 对象付款成功或失败时触发,以 Webhooks 形式发送至客户配置的 Webhooks URL。详情请参考 Events 事件

事件类型
transfer.succeeded 付款成功时触发。
transfer.failed 付款失败时触发。

示例对象

付款成功:
{
    "id": "evt_NMO13SJt1jrOaxRMhXC4wj0k",
    "created": 1435752329,
    "type": "transfer.succeeded",
    "livemode": true,
    "object": "event",
    "data": {
        "object": {
            "id": "tr_fXTq1OHufjHOvbDiPG0qTSiP",
            "object": "transfer",
            "type": "b2c",
            "created": 1435752318,
            "time_transferred": 1435752318,
            "livemode": true,
            "status": "paid",
            "app": "app_1234567890abcDEF",
            "channel": "wx_pub",
            "order_no": "123456789",
            "amount": 1,
            "amount_settle": 1,
            "currency": "cny",
            "recipient": "Openid",
            "description": "Your Description",
            "transaction_no": "1010018301201507010307923793",
            "extra": {
                "user_name": "User Name",
                "force_check": true
            }
        }
    },
    "pending_webhooks": 0,
    "request": "iar_TqvPiDH8SGeHm5GaTKbLuDWL"
}

付款失败:
{
    "id": "evt_NMO13SJt1jrOaxRMhXC4wjkk",
    "created": 1435752329,
    "type": "transfer.failed”,
    "livemode": true,
    "object": "event",
    "data": {
        "object": {
            "id": "tr_fXTq1OHufjHOvbDiPG0qTSiP",
            "object": "transfer",
            "type": "b2c",
            "created": 1435752318,
            "time_transferred": 1435752318,
            "livemode": true,
            "status": "failed",
            "app": "app_1234567890abcDEF",
            "channel": "wx_pub",
            "order_no": "123456789",
            "amount": 1,
            "amount_settle": 1,
            "currency": "cny",
            "recipient": "Openid",
            "description": "Your Description",
            "transaction_no": "1010018301201507010307923793",
            "extra": {
                "user_name": "User Name",
                "force_check": true
            }
        }
    },
    "pending_webhooks": 0,
    "request": "iar_TqvPiDH8SGeHm5GaTKbLuDkk"
}

Batch Transfers 批量企业付款

此批量付款接口适用于以下 8 个渠道接口:支付宝alipay、银联电子代付unionpay、微信公众号wx_pub、微信小程序wx_lite、通联代付allinpay、京东代付jdpay、余额balance、贵州银联代付unionpay_gz

以下是该付款接口的注意点:

  • 微信服务商模式商户暂不支持企业付款。

  • 支付宝 1.0 接口在调用该批量企业付款接口时,仅需要点击退款确认链接,输入一次商户密码即可完成退款;支付宝 2.0 接口的企业付款接口则不需要输入密码。

  • 支付宝 1.0 批量付款手续费率 0.5%,最低 1 元,最高 25 元。手续费按单笔分别计算,批量对象中的手续费 fee 字段会在批量企业付款成功后更新;支付宝 2.0 接口无手续费,详情参考帮助中心

  • 支付宝的批量企业付款状态 status 包含一个特殊的 partially_succeeded 状态,若批量企业付款中存在部分成功,部分失败的情况,批量企业付款对象将处于该状态,对于成功部分的付款也会发送 batch_transfer.succeeded 事件

  • 批量银联电子代付的付款状态 status 包含两个特殊状态:scheduled 为待发送状态,该渠道的企业付款会在请求成功后延时 5 分钟发送,5 分钟内处于待发送状态;canceled 为取消发送状态,更新(取消)企业付款后的订单状态。

  • 批量企业付款对象 batch_transferrecipients 字段里的元素中,会有每笔付款对象的 transfer (对应的 transfer 对象 ID) 和 status(对应的 transfer 对象状态)字段。

  • 批量企业付款接口单次最多只能请求 200 笔企业付款订单。

  • 此接口的所有请求强制要求签名,必须生成 RSA 签名(SHA256)并在请求头中添加 Pingplusplus-Signature 字段,需在管理平台上配置商户公钥;同时必须在请求头中添加 Pingplusplus-Request-Timestamp 字段,其值为请求接口的 Unix 时间戳。(注:强制验签的含义是:你无须开启 Ping++ 管理平台上的验签开关,只需要在管理平台上传公钥,在服务端代码中设置私钥,就可以直接验签。)

属性
id string 由 Ping++ 生成的批量企业付款对象 ID
object string 值为 batch_transfer
app string 创建批量企业付款使用的 app 对象 id ,查看 如何获取App ID
amount int 批量企业付款总金额。
batch_no string 批量企业付款批次号,11 ~ 32 位,允许字母和英文。
channel string 渠道参数,目前支持 alipay (支付宝,包含 1.0 和 2.0 接口)、 unionpay (银联电子代付)、 wx_pub (微信公众号)、 wx_lite (微信小程序)、 allinpay (通联代付)、 jdpay (京东代付)、 balance (余额)和 unionpay_gz (贵州银联代付)。
currency string 三位 ISO 货币代码,人民币为 cny
created int 批量企业付款创建时的 Unix 时间戳。
description string 批量企业付款描述。
extra hash 额外信息,当前该字段为空。
failure_msg string 错误消息的描述。首次请求支付宝 1.0 批量企业付款成功时,该字段包含了确认付款的 URL 链接地址,仅在渠道为支付宝时有值,你需要获取该地址,在浏览器中打开并且输入支付宝商户密码才能完成批量企业付款;支付宝 2.0 产品接口无密,所以首次请求的 URL 中无付款链接;批量银联电子代付的接口不需要输入密码。
fee int 批量企业付款手续费。
livemode boolean 是否处于 live 模式。
metadata hash 参考 元数据
recipients array 接收者信息。具体参考下表的 recipients 参数说明。
status string 批量企业付款状态。目前支持 7 种状态,created: 已创建;pending: 处理中;succeeded: 成功;failed: 失败;partially_succeeded: 部分成功;scheduled: 待发送,unionpay 渠道的转账会在请求成功后延时5分钟发送,5分钟内处于待发送状态;canceled: 取消发送。
time_succeeded int 成功的 Unix 时间戳。
type string 付款类型,取值范围:b2c(打款给个人用户)和 b2b(打款给企业用户)。当前 wx_pubwx_litebalance 仅支持:b2c ; alipayunionpayallinpayjdpayunionpay_gz 支持:b2b、b2c。
recipients 参数说明
account string 接收者账号。
amount int 付款金额。
name string 接收者姓名。
description string 批量企业付款描述。
transfer string 对应的单笔 transfer 对象 ID
status string 对应的单笔 transfer 对象状态。
open_bank string 1~15位,开户银行名称,unionpay 渠道会用到此字段。
open_bank_code string 4位,开户银行编号,unionpay 渠道会用到此字段,详情请参考 银联电子代付银行编号说明
open_bank_gz string 开户银行名称,unionpay_gz 渠道会用到此字段。
open_bank_code_gz string 开户银行编号,unionpay_gz 渠道会用到此字段,详情请 点击下载附件
account_type string 账户类型,alipay 2.0 渠道会用到此字段,字段值:ALIPAY_USERID、ALIPAY_LOGONID。
fee int 单笔 transfer 的渠道手续费。
failure_msg string 单笔 transfer 的错误信息。
order_no string 单笔 transfer 的订单号,可选字段,如果不传程序就自动生成。
transaction_no string 单笔 transfer 的流水号。
business_code string 5位业务代码,allinpay 渠道会用到此字段,根据通联业务人员提供,不填使用通联提供默认值 09900。
card_type int 银行卡号类型,allinpay 渠道会用到此字段。1位,0:银行卡、1:存折、2:信用卡,不填默认使用银行卡。

示例对象

{
  "id": "181610101014367590",
  "object": "batch_transfer",
  "app": "app_ribgW1n2SOqcPxn1",
  "amount": 8000,
  "batch_no": "2016101010380007",
  "channel": "alipay",
  "currency": "cny",
  "created": 1476067087,
  "description": "付款说明",
  "extra": {},
  "failure_msg": null,
  "fee": 0,
  "livemode": true,
  "metadata": {},
  "recipients": [
      {
          "account": "account01@alipay.com",
          "amount": 5000,
          "name": "张三",
          "transfer": "tr_jHWfvDnTKG0SiPmbfPbHW1eH",
          "status": "pending"
      },
      {
          "account": "account02@alipay.com",
          "amount": 3000,
          "name": "李四",
          "transfer": "tr_8u1yPK1eHWv9D08OePzDe1CK",
          "status": "pending"
      }
  ],
  "status": "pending",
  "time_succeeded": null,
  "type": "b2c"
}

创建 Batch Transfer 对象

创建一个 batch transfer 对象来发起批量企业付款。注:微信服务商模式商户暂不支持企业付款。

请求参数
app required 批量企业付款对应的 app 对象 id ,查看 如何获取App ID
batch_no required 批量企业付款批次号,11 ~ 32 位,允许字母和英文。
channel required 渠道参数,目前支持 alipay (支付宝,包含 1.0 和 2.0 接口)、 unionpay (银联电子代付)、 wx_pub (微信公众号)、 wx_lite (微信小程序)、 allinpay (通联代付)、 jdpay (京东代付)、 balance (余额)和 unionpay_gz (贵州银联代付)。
amount required 批量企业付款总金额,单位为分。
description required 批量企业付款描述,最多 200 个字节。
metadata optional 参考 元数据
recipients required 接收者信息。具体参考下表的针对各渠道的 recipients 参数说明。
currency optional 三位 ISO 货币代码,人民币为 cny
type required 付款类型,取值范围:b2c(打款给个人用户)和 b2b(打款给企业用户)。当前 wx_pubwx_litebalance 仅支持:b2c ; alipayunionpayallinpayjdpayunionpay_gz 支持:b2b、b2c。
支付宝 recipients 参数说明
account required 接收者支付宝账号。
amount required 金额,单位为分
name required 接收者姓名。在 alipay 为 1.0 接口时必填,在 alipay 为 2.0 接口时选填。
description optional 批量企业付款描述,最多 200 字节。
account_type optional 账户类型,alipay 2.0 渠道会用到此字段,取值范围: 1、ALIPAY_USERID:支付宝账号对应的支付宝唯一用户号。以2088开头的16位纯数字组成。 2、ALIPAY_LOGONID(默认值):支付宝登录号,支持邮箱和手机号格式。
order_no optional 订单号, 1 ~ 64 位不能重复的数字字母组合。
银联电子代付 recipients 参数说明
account required 接收者银行卡账号。
amount required 付款金额,单位为分。
name required 接收者姓名。
description optional 批量企业付款描述,最多 200 字节。
open_bank optional 1~15位,开户银行。
open_bank_code optional 4位,开户银行编号,详情请参考 银联电子代付银行编号说明
order_no optional 订单号,1 ~ 16 位不能重复的数字字母组合。

注: open_bank_codeopen_bank 两个参数必传一个,建议使用 open_bank_code,若都传参则优先使用 open_bank_code 读取规则。

微信公众号、小程序企业付款 recipients 参数说明
open_id required 接收者 id,为用户在 wx_pub 下的 open_id。
amount required 金额,单位为分。
name optional 收款人姓名。当该参数为空,则不校验收款人姓名。
description optional 不填默认使用外层参数中的 description 最多 99 个英文和数字的组合或最多 33 个中文字符,不可以包含特殊字符。
force_check optional 是否强制校验收款人姓名。仅当 name 参数不为空时该参数生效。
order_no optional 订单号,1 ~ 32 位不能重复的数字字母组合。
通联代付 recipients 参数说明
account required 接收者银行卡账号。
amount required 付款金额,单位为分。
name required 接收者姓名。
open_bank_code required 4位,银行编号。
business_code optional 5位业务代码,根据通联业务人员提供,不填使用通联提供默认值 09900。
description optional 批量企业付款描述,最多 30 个 Unicode 字符。
card_type optional 银行卡号类型。0:银行卡、1:存折、2:信用卡,不填默认使用银行卡。
order_no optional 订单号,20 ~ 40 位不能重复的数字字母组合(必须以通联的商户号开头,建议组合格式:通联商户号 + 时间戳 + 固定位数顺序流水号,不包含+号),这里不传的话程序会调用商户的通联商户号加上随机数自动生成 order_no。
京东代付 recipients 参数说明
account required 接收者银行卡账号。
amount required 付款金额,单位为分。
name required 接收者姓名。
open_bank_code required 4位,银行编号。
order_no optional 订单号,jdpay 限长 1~64 位不能重复的数字字母组合。
card_type optional 银行卡号类型。0:银行卡、2:信用卡,不填默认使用银行卡。description optional
余额 recipients 参数说明
user required 接收者用户 ID。
amount required 付款金额,单位为分。
order_no optional 订单号,1~64 位不能重复的数字字母组合。
description optional 批量企业付款描述,最多 100 个 Unicode 字符。
贵州银联代付 recipients 参数说明
account required 接收者银行卡账号。
amount required 付款金额,单位为分。
name required 接收者姓名。
description optional 批量企业付款描述,最多 200 字节。
open_bank_gz optional 4~25位,开户银行名称。
open_bank_code_gz optional 4~12位,开户银行编号,详情请 点击下载附件
order_no optional 订单号,1 ~ 32 位不能重复的数字字母组合。

返回

返回一个 batch transfer 对象或者一个错误,详见 错误

定义

POST https://api.pingxx.com/v1/batch_transfers

请求示例

curl https://api.pingxx.com/v1/batch_transfers \
-H "Content-Type: application/json; charset=utf-8" \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Pingplusplus-Request-Timestamp: 1476067085" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "amount": 8000,
    "app": "app_ribgW1n2SOqcPxn1",
    "batch_no": "2016101010380007",
    "channel": "alipay",
    "description": "付款说明",
    "recipients": [
        {
            "account": "account01@alipay.com",
            "amount": 5000,
            "name": "张三"
        },
        {
            "account": "account02@alipay.com",
            "amount": 3000,
            "name": "李四"
        }
    ],
    "type": "b2c"
}'

返回示例

{
  "id": "181610101014367590",
  "object": "batch_transfer",
  "app": "app_ribgW1n2SOqcPxn1",
  "amount": 8000,
  "batch_no": "2016101010380007",
  "channel": "alipay",
  "currency": "cny",
  "created": 1476067087,
  "description": "付款说明",
  "extra": {},
  "failure_msg": null,
  "fee": 0,
  "livemode": true,
  "metadata": {},
  "recipients": [
      {
          "account": "account01@alipay.com",
          "amount": 5000,
          "name": "张三",
          "transfer": "tr_jHWfvDnTKG0SiPmbfPbHW1eH",
          "status": "pending"
      },
      {
          "account": "account02@alipay.com",
          "amount": 3000,
          "name": "李四",
          "transfer": "tr_8u1yPK1eHWv9D08OePzDe1CK",
          "status": "pending"
      }
  ],
  "status": "pending",
  "time_succeeded": null,
  "type": "b2c"
}

更新批量银联电子代付 Batch Transfer 对象

更新(取消)一个 batch transfer 对象来取消这笔批量银联电子代付。

请求参数
status required 只支持 canceled

返回

返回一个取消状态的 batch transfer 对象或者一个错误,详见 错误

定义

PUT https://api.pingxx.com/v1/batch_transfers/{BATCH_TRANSFER_ID}

请求示例

curl https://api.pingxx.com/v1/batch_transfers/181610101014367590 \
-H "Content-Type: application/json; charset=utf-8" \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Pingplusplus-Request-Timestamp: 1476067085" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "status": "canceled"
}'

返回示例

{
    "id": "181610101014367590",
    "object": "batch_transfer",
    "app": "app_ribgW1n2SOqcPxn1",
    "amount": 8000,
    "batch_no": "2016101010380007",
    "channel": "unionpay",
    "currency": "cny",
    "created": 1476067087,
    "description": "付款说明",
    "extra": {},
    "failure_msg": null,
    "fee": 0,
    "livemode": true,
    "metadata": {},
    "recipients": [
        {
            "account": "3210120312031200",
            "amount": 5000,
            "name": "张三",
            "open_bank": "招商银行",
            "open_bank_code": "0308",
            "transfer": "tr_jHWfvDnTKG0SiPmbfPbHW1eH",
            "status": "canceled"
        },
        {
            "account": "321012031212031200",
            "amount": 3000,
            "name": "李四",
            "open_bank": "招商银行",
            "open_bank_code": "0308",
            "transfer": "tr_8u1yPK1eHWv9D08OePzDe1CK",
            "status": "canceled"
        }
    ],
    "status": "canceled",
    "time_succeeded": null,
    "type": "b2c"
}

查询 Batch Transfer 对象

你可以使用 batch_transfer_id 来查询对应的 batch transfer 对象信息。

请求参数
id string 批量企业付款对象 id ,由 Ping++ 生成。

返回

返回一个 batch transfer 对象或者一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/batch_transfers/{BATCH_TRANSFER_ID}

请求示例

curl https://api.pingxx.com/v1/batch_transfers/181610101014367590 \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Pingplusplus-Request-Timestamp: 1476067095" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "id": "1818282929292221323",
    "object": "batch_transfer",
    "app": "app_ribgW1n2SOqcPxn1",
    "amount": 8000,
    "batch_no": "1231231231",
    "channel": "alipay",
    "currency": "cny",
    "created": 1111111,
    "description": "付款说明",
    "extra": {},
    "failure_msg": null,
    "fee": 100,
    "livemode": true,
    "metadata": {},
    "recipients": [
        {
            "account": "account01@alipay.com",
            "amount": 5000,
            "name": "张三",
            "transfer": "tr_jHWfvDnTKG0SiPmbfPbHW1eH",
            "status": "pending"
        },
        {
            "account": "account02@alipay.com",
            "amount": 3000,
            "name": "李四",
            "transfer": "tr_8u1yPK1eHWv9D08OePzDe1CK",
            "status": "pending"
        }
    ],
    "status": "pending",
    "time_succeeded": 123123123,
    "type": "b2c"
}

查询 Batch Transfer 对象列表

你可以使用调用该接口来查询对应的 batch transfer 对象列表信息。

请求参数
page optional int 页码,取值范围:1~1000000000;默认值为"1"。
per_page optional int 每页数量,取值范围:1~100;默认值为"10"。
created [ gt ] optional int 创建时间大于该值。
created [ gte ] optional int 创建时间大于或等于该值。
created [ lt ] optional int 创建时间小于该值。
created [ lte ] optional int 创建时间小于或等于该值。
app optional string 批量企业付款对应的 app 对象 ID,查看 如何获取App ID

返回

返回一个 batch transfer 对象列表或者一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/batch_transfers?app={app_id}

请求示例

curl https://api.pingxx.com/v1/batch_transfers?app=app_ribgW1n2SOqcPxn1&per_page=3 \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Pingplusplus-Request-Timestamp: 1476067095" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "object": "list",
    "url": "/v1/batch_transfers",
    "has_more": true,
    "data": [
        {
            "id": "181610101014367590",
            "object": "batch_transfer",
            "app": "app_ribgW1n2SOqcPxn1",
            "amount": 8000,
            "batch_no": "2016101010380007",
            "channel": "alipay",
            "currency": "cny",
            "created": 1476067087,
            "description": "付款说明",
            "extra": {},
            "failure_msg": null,
            "fee": 0,
            "livemode": true,
            "metadata": {},
            "recipients": [
                {
                    "account": "account01@alipay.com",
                    "amount": 5000,
                    "name": "张三",
                    "transfer": "tr_jHWfvDnTKG0SiPmbfPbHW1eH",
                    "status": "pending"
                },
                {
                    "account": "account02@alipay.com",
                    "amount": 3000,
                    "name": "李四",
                    "transfer": "tr_8u1yPK1eHWv9D08OePzDe1CK",
                    "status": "pending"
                }
            ],
            "status": "pending",
            "time_succeeded": null,
            "type": "b2c"
        },
        {...},
        {...}
    ]
}

Batch Transfers 相关的 Event 类型

该类型的 Event 对象会在 batch_transfer 对象批量付款成功后触发,以 Webhooks 形式发送至客户配置的 Webhooks URL。详情请参考 Events 事件

事件类型
batch_transfer.succeeded 批量企业付款成功时触发。

示例对象

{
    "id": "evt_ca16CoQsiP2ja1JKs5gx3j4q",
    "object": "event",
    "created": 1475924802,
    "livemode": false,
    "data": {
        "object": {
            "id": "181610101014367590",
            "object": "batch_transfer",
            "app": "app_ribgW1n2SOqcPxn1",
            "amount": 8000,
            "batch_no": "2016101010380007",
            "channel": "alipay",
            "currency": "cny",
            "created": 1476067087,
            "description": "付款说明",
            "extra": {},
            "failure_msg": null,
            "fee": 200,
            "livemode": true,
            "metadata": {},
            "recipients": [
                {
                    "account": "account01@alipay.com",
                    "amount": 5000,
                    "name": "张三",
                    "transfer": "tr_jHWfvDnTKG0SiPmbfPbHW1eH",
                    "status": "paid"
                },
                {
                    "account": "account02@alipay.com",
                    "amount": 3000,
                    "name": "李四",
                    "transfer": "tr_8u1yPK1eHWv9D08OePzDe1CK",
                    "status": "paid"
                }
            ],
            "status": "succeeded",
            "time_succeeded": 1476067147,
            "type": "b2c"
        }
    },
    "pending_webhooks": 0,
    "request": "iar_1KeD0GHi58yLfDyHK4HCOyDS",
    "type": "batch_transfer.succeeded"
}

Red Envelopes 红包

你可以请求一个 red_envelope 红包对象向你的用户发红包。所有和红包支付相关的要素信息都存储在 red_envelope 对象之中,你可以通过发起红包请求创建新的 red_envelope 对象,也可以随时查看红包对象的状态。每个 red_envelope 对象都拥有一个标识 id,该 id 在系统内唯一。

属性
id string 红包对象 id ,由 Ping++ 生成,28 位长度字符串。
object string 值为 red_envelope
created timestamp 支付红包的时间,用 Unix 时间戳表示。
received timestamp 红包的接收时间,用 Unix 时间戳表示。
refunded timestamp 红包超过 24 小时未领取的退回时间,用 Unix 时间戳表示。
livemode boolean 支付是否处于 live 模式。
status string 红包状态。目前支持 6 种状态: sending : 发放中; sent : 已发放待领取; failed : 发放失败; received : 已领取; refunding : 退款中; refund : 已退款。
app expandable string 红包使用的 app 对象的 idexpandable 可展开,查看 如何获取App ID
channel string 红包使用的第三方支付渠道。目前仅支持 wx_pub
order_no string 红包使用的商户订单号。 wx_pub 渠道规定为 1 ~ 28 位不能重复的数字。
transaction_no string 第三方支付渠道的交易流水号。
amount int 总金额大于 0,单位为对应币种的最小货币单位,例如:人民币为分。 wx_pub 限制在 100 ~ 20000 之间,即 1 ~ 200 元。
amount_settle int 清算金额,单位为对应币种的最小货币单位,例如:人民币为分。
currency string 三位 ISO 货币代码,目前仅支持人民币 cny。
recipient string 接收者 id, 为用户在 wx_pub 渠道下的 open_id
subject string 红包主题名称,最多 32 个字节。
body string 红包祝福语,最多 128 个字节。
description string 备注信息,最多 255 个字节。
metadata hash 参考 元数据
failure_msg string 红包订单的错误消息的描述。
extra object 支付渠道相关的附加参数,具体参考下表 extra 参数说明。
extra 参数
send_name string 商户名称,最多 32 个字节。
scene_id string 发放红包使用场景,红包金额大于 200 时必传。具体属性请看请求参数中的 scene_id 属性值。

示例对象

{
   "id": "red_KCabLO58W5G0rX90iT0az5a9",
   "object": "red_envelope",
   "created": 1428499439,
   "received": null,
   "refunded": null,
   "livemode": true,
   "status": "sending",
   "app": "app_1Gqj58ynP0mHeX1q",
   "channel": "wx_pub",
   "order_no": "123456789",
   "transaction_no": null,
   "amount": 100,
   "amount_settle": 100,
   "currency": "cny",
   "recipient": "Openid",
   "subject": "Your Subject",
   "body": "Your Body",
   "description": "Your Description",
   "failure_msg":null,
   "extra": {
       "send_name": "Send Name"
   }
 }

创建 Red Envelope 对象

发起一次红包请求需要创建一个新的 red_envelope 对象。如果支付失败,请检查错误信息,一般是由于账户余额不足引起的。使用测试模式的 API Key,则不会发生真实交易,且需要主动调用下方的红包查询接口才能刷新红包订单的状态且触发 Webhooks 回调。同步返回交易结果,不会发送 Webhooks 通知。

请求参数
app [ id ] expandable required 红包使用的 app 对象的 idexpandable 可展开,查看 如何获取App ID
channel required 红包使用的第三方支付渠道。目前仅支持 wx_pub
order_no required 红包使用的商户订单号。 wx_pub 渠道规定为 1 ~ 28 位不能重复的数字。
amount required 总金额大于 0,单位为对应币种的最小货币单位,例如:人民币为分。 wx_pub 限制在 100 ~ 20000 之间,即 1 ~ 200 元。
currency required 三位 ISO 货币代码,目前仅支持人民币 cny
recipient required 接收者 id, 为用户在 wx_pub 下的 open_id
subject required 红包主题名称,最多 32 个字节。
body required 红包祝福语,最多 128 个字节。
description required 备注信息,最多 255 个字节。
metadata optional 参考 元数据
extra required 支付渠道相关的附加参数,具体参考下表 extra 参数说明。
extra 参数
send_name required 商户名称,最多 32 个字节。
scene_id optional 发放红包使用场景,红包金额大于 200 时必传。具体属性看 scene_id 属性值。
scene_id 参数
PRODUCT_1 string 商品促销
PRODUCT_2 string 抽奖
PRODUCT_3 string 虚拟物品兑奖
PRODUCT_4 string 企业内部福利
PRODUCT_5 string 渠道分润
PRODUCT_6 string 保险回馈
PRODUCT_7 string 彩票派奖
PRODUCT_8 string 税务刮奖

返回

同步返回红包支付结果。如果发生错误,则会返回错误码和错误详情,详见 错误

定义

POST https://api.pingxx.com/v1/red_envelopes

请求示例

curl https://api.pingxx.com/v1/red_envelopes \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d order_no=123456789 \
-d app[id]=app_1Gqj58ynP0mHeX1q \
-d channel=wx_pub \
-d amount=100 \
-d currency=cny \
-d subject="Your Subject" \
-d body="Your Body" \
-d extra[send_name]="Send Name" \
-d recipient=Openid \
-d description="Your Description"

返回示例

{
  "id": "red_KCabLO58W5G0rX90iT0az5a9",
  "object": "red_envelope",
  "created": 1428499439,
  "received": null,
  "refunded": null,
  "livemode": true,
  "status": "sending",
  "app": "app_1Gqj58ynP0mHeX1q",
  "channel": "wx_pub",
  "order_no": "123456789",
  "transaction_no": null,
  "amount": 100,
  "amount_settle": 100,
  "currency": "cny",
  "recipient": "Openid",
  "subject": "Your Subject",
  "body": "Your Body",
  "description": "Your Description",
  "failure_msg":null,
  "extra": {
    "send_name": "Send Name"
  }
}

查询 Red Envelope 对象

通过 red_envelope 对象的 id 查询一个已创建的 red_envelope 对象。

请求参数
id required 红包 id

返回

返回一个已存在的 red_envelope 对象或者一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/red_envelopes/{RED_ID}

请求示例

curl https://api.pingxx.com/v1/red_envelopes/red_KCabLO58W5G0rX90iT0az5a9 \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
  "id": "red_KCabLO58W5G0rX90iT0az5a9",
  "object": "red_envelope",
  "created": 1428499439,
  "received": null,
  "refunded": null,
  "livemode": true,
  "status": "sending",
  "app": "app_1Gqj58ynP0mHeX1q",
  "channel": "wx_pub",
  "order_no": "123456789",
  "transaction_no": null,
  "amount": 100,
  "amount_settle": 100,
  "currency": "cny",
  "recipient": "Openid",
  "subject": "Your Subject",
  "body": "Your Body",
  "description": "Your Description",
  "failure_msg":null,
  "extra": {
      "send_name": "Send Name"
  }
}

查询 Red Envelope 对象列表

返回之前创建 red_envelope 对象的一个列表。列表是按创建时间进行排序,总是将最新的 red_envelope 对象显示在最前。

请求参数
limit optional 限制每页可以返回多少对象,范围为 1~100 项,默认是 10 项。
starting_after optional 在分页时使用的指针,决定了列表的第一项从何处开始。假设你的一次请求返回列表的最后一项的 idobj_end ,你可以使用 starting_after = obj_end 去获取下一页。
ending_before optional 在分页时使用的指针,决定了列表的最末项在何处结束。假设你的一次请求返回列表的第一项的 idobj_start ,你可以使用 ending_before = obj_start 去获取上一页。
app [ id ] expandable required 红包使用的 app 对象的 idexpandable 可展开,查看 如何获取App ID
channel optional 支付使用的第三方支付渠道,目前仅支持 wx_pub
status optional 红包状态。目前支持 6 种状态: sending : 发放中; sent : 已发放待领取; failed : 发放失败; received : 已领取; refunding : 退款中; refund : 已退款。
created optional 对象的创建时间,用 Unix 时间戳表示,具体参考下表 created 参数。
created参数
created [ gt ] optional int 大于 red_envelope 对象的创建时间,用 Unix 时间戳表示。
created [ gte ] optional int 大于或等于 red_envelope 对象的创建时间,用 Unix 时间戳表示。
created [ lt ] optional int 小于 red_envelope 对象的创建时间,用 Unix 时间戳表示。
created [ lte ] optional int 小于或等于 red_envelope 对象的创建时间,用 Unix 时间戳表示。

返回

根据请求参数返回一个 red_envelope 对象列表,如果列表为空,则返回的 data 为空数组。遇到错误时返回相应错误信息,详见 错误

定义

GET https://api.pingxx.com/v1/red_envelopes?expand[]=app

请求示例

curl https://api.pingxx.com/v1/red_envelopes/?limit=3?expand[]=app \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
  "object": "list",
  "url": "/v1/red_envelopes",
  "has_more": true,
  "data": [
      {
        "id": "red_KCabLO58W5G0rX90iT0az5a9",
        "object": "red_envelope",
        "created": 1428499439,
        "received": null,
        "refunded": null,
        "livemode": true,
        "status": "sending",
        "app": "app_1Gqj58ynP0mHeX1q",
        "channel": "wx_pub",
        "order_no": "123456789",
        "transaction_no": null,
        "amount": 100,
        "amount_settle": 100,
        "currency": "cny",
        "recipient": "Openid",
        "subject": "Your Subject",
        "body": "Your Body",
        "description": "Your Description",
        "failure_msg":null,
        "extra": {
          "send_name": "Send Name"
          }
      }
  ]
}

Red envelope 相关的 Event 类型

该类型的 Event 对象会在 red_envelope 对象红包发送成功和接收成功后触发,以 Webhooks 形式发送至客户配置的 Webhooks URL。详情请参考 Events 事件

事件类型
red_envelope.sent 红包对象,红包发送成功时触发
red_envelope.received 红包对象,红包接收成功时触发

示例对象

事件类型为 red_envelope.sent :
{
    "id": "evt_5BpbV0tYK4ySvodDG2RT6XRq",
    "created": 1436855491,
    "type": "red_envelope.sent",
    "livemode": true,
    "object": "event",
    "data": {
        "object": {
            "id": "red_z1O8iLmXXXX5uPqLiDzLCavP",
            "object": "red_envelope",
            "created": 1436855474,
            "received": null,
            "refunded": null,
            "livemode": true,
            "status": "sent",
            "app": "app_1234567890abcDEF",
            "channel": "wx_pub",
            "order_no": "123456789",
            "transaction_no": "0010037269201507140154722852",
            "amount": 100,
            "amount_settle": 100,
            "currency": "cny",
            "recipient": "Openid",
            "subject": "Your Subject",
            "body": "Your Body",
            "description": "Your Description",
            "extra": {
                "nick_name": "Nick Name",
                "send_name": "Send Name"
            }
        }
    },
    "pending_webhooks": 0,
    "request": "iar_zjLGC8zfLOS8WPS0WLi14ynD"
}
事件类型为 red_envelope.received :
{
    "id": "evt_hMGV2eR15fMupHUdDYibhLxe",
    "object": "event",
    "type": "red_envelope.received",
    "livemode": true,
    "created": 1436753800,
    "data": {
        "object": {
            "id": "red_4qLGO84GaXHOWTSO80mLO8i9",
            "object": "red_envelope",
            "created": 1436753573,
            "received": null,
            "refunded": null,
            "livemode": true,
            "status": "received",
            "app": "app_1234567890abcDEF",
            "channel": "wx_pub",
            "order_no": "123456789",
            "transaction_no": "0010037269201507130153706663",
            "amount": 100,
            "amount_settle": 100,
            "currency": "cny",
            "recipient": "Openid",
            "subject": "Your Subject",
            "body": "Your Body",
            "description": "Your Description",
            "extra": {
                "nick_name": "Nick Name",
                "send_name": "Send Name"
            }
        }
    },
    "pending_webhooks": 0,
    "request": "iar_jf1iT0fT0a18v1u5qDvb1uDS"
}

User 用户

通过创建一个用户对象,让 Ping++ 连通你的系统中的用户。可以通过用户对象管理个人信息,查看余额、优惠券等相关信息。 在每个应用创建时,我们会为其分配一个初始用户,id 为 “0”,表示该应用的系统用户,除此之外,所有用户都由你传入的用户 id 创建。 用户分为 customer 类型和 business 类型,customer 类型可以通过用户对象创建接口创建,也可以在使用其他带有用户 id 字段的模块相关接口(如充值、优惠券)时由 Ping++ 自动创建并初始化; business 类型目前只能通过创建子商户时创建,详情请参考 商户层级

如果你需要使用订单、余额、优惠券、商户层级、分润等模块的相关功能时,你需要了解并使用用户的相关接口。

属性
id string 用户 ID ,64 位以内,首字母必须是英文、数字或者下划线。
object string 值为 "user"。
app string 对应 app 对象的 id ,查看 如何获取 App ID
type string 用户类型,取值范围: customer 为个人用户, business 为企业用户。
related_app string type 值为 business 时,该用户关联的 Ping++ 的 app 对象 id
address string 用户地址。
available_coupons int 可用优惠券数量。
avatar string 头像图片地址。
available_balance int 可用余额,可用于消费。
withdrawable_balance int 可提现余额,可用于消费、提现、转账等。
created int 创建时间,使用 unix 时间戳表示。
disabled boolean 是否被禁用。禁用后,相关用户的功能均不可使用。
email string 邮箱地址。
gender string 性别。 MALE :男; FEMALE :女,为空时表示未填写。
identified boolean 是否经过实名认证。
livemode boolean 是否处于 live 模式。
mobile string 手机号码。
name string 用户昵称。
metadata hash 详见 元数据
settle_accounts hash 用户结算账户列表,请参考 用户结算账户对象

示例对象

{
  "id": "test_user_003",
  "object": "user",
  "app": "app_1Gqj58ynP0mHeX1q",
  "address": null,
  "available_coupons": 0,
  "avatar": null,
  "available_balance": 0,
  "withdrawable_balance": 0,
  "created": 1470215837,
  "disabled": false,
  "email": null,
  "gender": "MALE",
  "identified": false,
  "livemode": true,
  "metadata": {},
  "mobile": null,
  "name": "name003",
  "type": `customer`,
  "related_app": null,
  "settle_accounts": []
}

创建 User 对象

你可以通过该接口创建一个 user 对象。使用该接口时必须确保用户 id 未被使用。

请求参数
app required string 对应 app 对象的 id ,查看 如何获取 App ID
id required string 用户 ID ,64 位以内,首字母必须是英文、数字或者下划线。
address optional string 用户地址。
avatar optional string 头像图片地址。
email optional string 邮箱地址。
gender optional string 性别。MALE:男,FEMALE:女。
mobile optional string 手机号码。
name optional string 用户昵称。
metadata optional hash 详见 元数据

返回

返回一个 user 对象,或者返回一个错误,详见 错误

定义

POST https://api.pingxx.com/v1/apps/{APP_ID}/users

请求示例

curl https://api.pingxx.com/v1/apps/{APP_ID}/users \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Content-Type: application/json" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:
-d '{
  "id": "test_user_003",
  "address": null,
  "avatar": null,
  "email": null,
  "gender": "MALE",
  "metadata": {},
  "mobile": null,
  "name": "name003"
}'

返回示例

{
  "id": "test_user_003",
  "object": "user",
  "app": "app_1Gqj58ynP0mHeX1q",
  "address": null,
  "available_coupons": 0,
  "avatar": null,
  "available_balance": 0,
  "withdrawable_balance": 0,
  "created": 1470215837,
  "disabled": false,
  "email": null,
  "gender": "MALE",
  "identified": false,
  "livemode": true,
  "metadata": {},
  "mobile": null,
  "name": "name003",
  "type": `customer`,
  "related_app": null,
  "settle_accounts": []
}

查询 User 对象

通过 user 对象的 id 查询一个已创建的 user 对象。传入一个不存在 user 对象的 id 时,Ping++ 不会为此 id 自动创建 user 对象。

请求参数
app required string 对应 app 对象的 id ,查看 如何获取 App ID
id required string user 对象的 id

返回

返回一个 user 对象,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/users/{USER_ID}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/users/test_user_003 \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
  "id": "test_user_003",
  "object": "user",
  "app": "app_1Gqj58ynP0mHeX1q",
  "address": null,
  "available_coupons": 0,
  "avatar": null,
  "available_balance": 0,
  "withdrawable_balance": 0,
  "created": 1470215837,
  "disabled": false,
  "email": null,
  "gender": "MALE",
  "identified": false,
  "livemode": true,
  "metadata": {},
  "mobile": null,
  "name": "name003",
  "type": `customer`,
  "related_app": null,
  "settle_accounts": []
}

更新 User 对象

通过 user 对象的 id 更新一个已创建的 user 对象。 你可以调用该接口更新 user 对象中的个人信息,或者你也可以禁用/启用该用户,当用户被禁用后,相关的订单支付、余额、优惠券等功能会受限制。

请求参数
app required string 对应 app 对象的 id ,查看 如何获取 App ID
id required string user 对象的 id
address optional string 用户地址。
avatar optional string 头像。
email optional string 邮箱地址。
gender optional string 性别。MALE:男,FEMALE:女。
mobile optional string 手机号码。
name optional string 用户昵称。
metadata optional hash 详见 元数据
disabled optional bool 是否禁用该商户。该参数不能与其他参数同时使用。

返回

返回一个更新后的 user 对象,或者返回一个错误,详见 错误

定义

PUT https://api.pingxx.com/v1/apps/{APP_ID}/users/{USER_ID}

请求示例

curl https://api.pingxx.com/v1/apps/{APP_ID}/users/{USER_ID} \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Content-Type: application/json" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:
-d '{
  "address": null,
  "avatar": null,
  "email": null,
  "gender": "MALE",
  "metadata": {},
  "mobile": null,
  "name": "name003"
}'

返回示例

{
  "id": "test_user_003",
  "object": "user",
  "app": "app_1Gqj58ynP0mHeX1q",
  "address": null,
  "available_coupons": 0,
  "avatar": null,
  "available_balance": 0,
  "withdrawable_balance": 0,
  "created": 1470215837,
  "disabled": false,
  "email": null,
  "gender": "MALE",
  "identified": false,
  "livemode": true,
  "metadata": {},
  "mobile": null,
  "name": "name003",
  "type": `customer`,
  "related_app": null,
  "settle_accounts": []
}

查询 User 对象列表

你可以调用此接口查询 user 用户列表。

请求参数
app required string 支付使用的 app 对象的 id ,查看 如何获取App ID
page optional int 页码,默认值为"1",取值范围(1~100000000)。
per_page optional int 每页数量,默认值为"20",取值范围(1~100)。
created [ gt ] optional timestamp 大于 user 对象的创建时间,用 Unix 时间戳表示。
created [ gte ] optional timestamp 大于或等于 user 对象的创建时间,用 Unix 时间戳表示。
created [ lt ] optional timestamp 小于 user 对象的创建时间,用 Unix 时间戳表示。
created [ lte ] optional timestamp 小于或等于 user 对象的创建时间,用 Unix 时间戳表示。
disabled optional boolean 是否禁用。使用该参数时,不能同时使用其他参数。
identified optional boolean 是否经过实名认证。
type optional string 用户类型,取值范围: customer 为个人用户, business 为企业用户。

返回

返回一个 user 对象,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/users

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/users \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
  "object": "list",
  "url": "/v1/apps/app_4OOi9SGuD88GGqbL/users",
  "has_more": true,
  "data": [
    {
      "id": "test_user_031",
      "object": "user",
      "app": "app_4OOi9SGuD88GGqbL",
      "address": null,
      "available_balance": 0,
      "available_coupons": 0,
      "avatar": null,
      "withdrawable_balance": 0,
      "created": 1488332846,
      "disabled": false,
      "email": null,
      "gender": null,
      "identified": false,
      "livemode": true,
      "metadata": {},
      "mobile": null,
      "name": null,
      "type": `business`,
      "related_app": "app_q5eff1jHKqXP9qvr",
      "settle_accounts": []
    },
    {...},
    {...}
  ]
}

Settle Account 用户结算账户

可以在 user 对象上绑定一个或多个用户结算账户,用户结算账户用于提现或者接收分润。

属性
id string 用户结算账户对象 ID。
object string 值为 "settle_account"。
created timestamp 创建时的 Unix 时间戳。
channel string 结算账号渠道名称,目前支持 alipay、wx _ pub、bank _ account。
recipient object 脱敏的结算账号接收者信息,详情参见请求参数 recipient 部分。

对象示例

{
  "id": "320217022818035400000601",
  "object": "settle_account",
  "created": 1488276234,
  "livemode": true,
  "channel": "bank_account",
  "recipient": {
    "open_bank_code": "0102",
    "account": "622262***2145",
    "name": "***哥"
  }
}

创建 Settle Account 对象

你可以为一个用户创建一个用户结算账户,每个用户在一个渠道下最多支持创建一个用户结算账户。

请求参数
app required string 对应 app 对象的 id ,查看 如何获取App ID
uid required string 用户 ID ,64 位以内,首字母必须是英文、数字或者下划线。
channel required string 结算账号渠道名称,目前支持 alipaywx_pubbank_account
recipient required object 结算账号渠道名称,见请求参数 recipient 部分,目前支持的渠道有 alipay (支付宝), wx_pub (微信公众号), bank_account (银行卡)。
支付宝 alipay 渠道 recipient 参数说明
account required string 接收者支付宝账号。
name required string 接收者姓名。
type optional string 转账类型,分为两种: b2c :企业向个人付款, b2b :企业向企业付款。不传时默认为 b2c 类型。
account_type optional string 收款方账户类型。 ALIPAY_USERID :支付宝账号对应的支付宝唯一用户号,以 2088 开头的 16 位纯数字组成; ALIPAY_LOGONID :支付宝登录号,支持邮箱和手机号格式。不传时默认为: ALIPAY_LOGONID
微信公众号 wx_pub 渠道 recipient 参数说明
account required string 接收者 open_id
name optional string 收款人姓名。当该参数为空,则不校验收款人姓名。
force_check optional boolean 是否强制校验收款人姓名。仅当 name 参数不为空时该参数生效。
type optional string 转账类型。仅支持 b2c :企业向个人付款。默认值为 b2c
银行卡 bank_account 渠道 recipient 参数说明
account required string 接收者银行卡账号。
name required string 接收者姓名。
type required string 转账类型。 b2c :企业向个人付款, b2b :企业向企业付款。
open_bank_code required string 开户银行编号,详情请参考 银联电子代付银行编号说明
open_bank optional string 开户银行。
business_code optional string 业务代码,根据通联业务人员提供,不填使用通联提供默认值 “09900`。
card_type optional int 银行卡号类型,0:银行卡;1:存折。
prov optional string 开户银行所在省份。
city optional string 开户银行所在城市。
term_type optional string 代付业务使用场景, 07: 互联网, 08: 移动端。默认为“07”.
sub_bank optional string 开户支行名称。

返回

返回一个 settle_account 对象,或者返回一个错误,详见 错误

定义

POST https://api.pingxx.com/v1/apps/{APP_ID}/users/{USER_ID}/settle_accounts
 

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/users/user_test_003/settle_accounts \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Content-Type: application/json" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:
-d '{
  "channel": "alipay",
  "recipient": {
    "account": "account01@gmail.com",
    "name": "李三哥",
    "type": "b2c"
  }
}'

返回示例

{
  "id": "320217022818035400000601",
  "object": "settle_account",
  "created": 1488276234,
  "livemode": true,
  "channel": "alipay",
  "recipient": {
    "account": "a***@gmail.com",
    "name": "***哥",
    "type": "b2c"
  }
}

查询 Settle Account 对象

你可以使用此接口来查询对应的用户结算账户对象。

请求参数
app required string 对应 app 对象的 id ,查看 如何获取App ID
uid required string 用户 ID ,64 位以内,首字母必须是英文、数字或者下划线。
id required string 用户结算账户对象 ID。

返回

返回一个 settle_account 对象,或者返回一个错误,详见 错误

定义

  GET https://api.pingxx.com/v1/apps/{APP_ID}/users/{USER_ID}/settle_accounts/{SETTLE_ACCOUNT_ID}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/users/test_user_003/settle_accounts/320217022818035400000601 \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
  "id": "320217022818035400000601",
  "object": "settle_account",
  "created": 1488276234,
  "livemode": true,
  "channel": "unionpay",
  "recipient": {
    "open_bank_code": "0102",
    "account": "622262***2145",
    "name": "***哥"
  }
}

删除 Settle Account 对象

可以调用此接口,将绑定的用户结算账户删除。 如果你需要更新用户结算账户的信息,你可以先通过该接口删除,然后再重新创建。

请求参数
app required string 对应 app 对象的 id ,查看 如何获取App ID
uid required string 用户 ID ,64 位以内,首字母必须是英文、数字或者下划线。
id required string 用户结算账户对象 ID,有商户提供。

返回

返回一个 JSON 格式的响应对象,或者返回一个错误,详见 错误

定义

DELETE https://api.pingxx.com/v1/apps/{APP_ID}/users/{USER_ID}/settle_accounts/{SETTLE_ACCOUNT_ID}

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/users/test_user_001/settle_accounts/320217022818035400000601 \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Content-Type: application/json" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "deleted": true,
    "id": "320217022818035400000601"
}

查询 Settle Account 对象列表

请求参数
app required string 支付使用的 app 对象的 id ,查看 如何获取App ID
uid required string 用户 ID ,64 位以内,首字母必须是英文、数字或者下划线。
page optional int 页码,默认值为 "1" ,取值范围(1~100000000)。
per_page optional int 每页数量,默认值为 "10",取值范围(1~100)。
created [ gt ] optional timestamp 大于 settle_account 对象的创建时间,用 Unix 时间戳表示。
created [ gte ] optional timestamp 大于或等于 settle_account 对象的创建时间,用 Unix 时间戳表示。
created [ lt ] optional timestamp 小于 settle_account 对象的创建时间,用 Unix 时间戳表示。
created [ lte ] optional timestamp 小于或等于 settle_account 对象的创建时间,用 Unix 时间戳表示。

返回

返回一个 settle_account 对象列表,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/users/{USER_ID}/settle_accounts

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/users/test_user_003/settle_accounts?page=1&per_page=15 \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
  "object": "list",
  "url": "/v1/apps/app_LibTW1n1SOq9Pin1/users/test_user_003/settle_accounts",
  "has_more": false,
  "data": [
    {
      "id": "320217022818035400000601",
      "object": "settle_account",
      "created": 1488276234,
      "livemode": true,
      "channel": "bank_account",
      "recipient": {
        "open_bank_code": "0102",
        "account": "622262***2145",
        "name": "***哥"
    },
    {...},
    {...}
  ]
}

Sub Apps 子商户应用

你可以通过创建 sub_app 对象满足业务模式中包含多层级的子商户应用,创建时使用的 app 对象 id 称之为平台。子商户和平台一样,也会生成一个独立的 Ping++ 账号,其中 sub_app 对象的 id 则是该账户下的 app 对象的 id。 如果子商户有登录管理平台的需求,可以在 Dashboard 上为子商户填写邮箱作为登录账号。

属性
id string 子商户应用对象 ID,由 Ping++ 生成。
object string 值为 "sub_app"。
created timestamp 创建时的 Unix 时间戳。
display_name string 子商户应用名称,2~50 位。
account string 子商户应用所属的 account。
description string 附加说明,2~50 位。
metadata hash 详见 元数据
available_methods list 可用的支付渠道列表。目前子商户不支持余额 balance 收付款。
user expandable string 子商户对应在平台下的 user 对象 id ,expandable 可展开。
level int 当前层级,值为 1~5。
parent_app string 父级商户的应用对象的 id

对象示例

{
  "id": "app_q5eff1jHKqXP9qvr",
  "object": "sub_app",
  "created": 1488332846,
  "display_name": "sub_app_display_name",
  "account": "acct_14yPiHyrb1GGub1m",
  "description": "Your description",
  "metadata": {
    "a": "b",
    "c": "d"
  },
  "available_methods": {},
  "user": "test_user_031"
}

创建 Sub App 对象

调用该接口创建一个 sub_app 对象。 每个子商户都有唯一一个父级商户的应用 id,该 id 可以是平台也可以是其他子商户,所有层级的子商户都只能通过平台查看和管理。 子商户创建时需要填写一个 user 对象 id,该 id 是平台应用下的一个用户。该用户用于接收分润以及其他用户相关的功能。

请求参数
APP_ID required string 对应 app 对象的 id ,expandable 可展开,查看 如何获取App ID
display_name required string 应用名称,2~50 位。
user expandable required string 子商户对应在平台下的 user 对象 id ,expandable 可展开。
parent_app optional string 父级商户的 sub_app 对象的 id ,必须为平台或者平台下其他的子商户,默认值为平台。
metadata optional hash 详见 元数据
description optional string 附加说明,2~50 位。

返回

返回一个 sub_app 对象,或者返回一个错误,详见 错误

定义

POST https://api.pingxx.com/v1/apps/{APP_ID}/sub_apps

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/sub_apps \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Content-Type: application/json" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "display_name": "sub_app_display_name",
    "user": "test_user_031",
    "metadata": {
        "a": "b",
        "c": "d"
    },
    "description": "Your description",
    "parent_app": "app_rDyHSCy14aL8m9ev"
}'

返回示例

{
  "id": "app_q5eff1jHKqXP9qvr",
  "object": "sub_app",
  "created": 1488332846,
  "display_name": "sub_app_display_name",
  "account": "acct_14yPiHyrb1GGub1m",
  "description": "Your description",
  "metadata": {
    "a": "b",
    "c": "d"
  },
  "available_methods": {},
  "user": "test_user_031",
  "parent_app": "app_rDyHSCy14aL8m9ev",
  "level" : 2
}

查询 Sub App 对象

通过 sub_app 对象的 id 查询一个已创建的 sub_app 对象。

请求参数
APP_ID required string 对应 app 对象的 id ,expandable 可展开,查看 如何获取App ID
SUB_APP_ID required string sub_app 对象的 id

返回

返回一个 sub_app 对象,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/sub_apps/{SUB_APP_ID}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
  "id": "app_GaDuf99evvfTi5Wb",
  "object": "sub_app",
  "created": 1488332846,
  "display_name": "sub_app_display_name",
  "account": "acct_14yPiHyrb1GGub1m",
  "description": "Your description",
  "metadata": {
    "a": "b",
    "c": "d"
  },
  "available_methods": {},
  "user": "test_user_031",
  "parent_app": "app_rDyHSCy14aL8m9ev",
  "level" : 2
}

更新 Sub App 对象

通过 sub_app 对象的 id 更新一个已创建的 sub_app 对象的信息。

请求参数
APP_ID required string 对应 app 对象的 id ,expandable 可展开,查看 如何获取App ID
SUB_APP_ID required string sub_app 对象的 id
display_name optional string 应用名称,2~50 位。
metadata optional hash 详见 元数据
description optional string 附加说明,2~50 位。
parent_app optional string 父级商户的 sub_app 对象的 id ,必须为平台或者平台下其他的子商户。

返回

返回一个更新后的 sub_app 对象,或者返回一个错误,详见 错误

定义

PUT https://api.pingxx.com/v1/apps/{APP_ID}/sub_apps/{SUB_APP_ID}

请求示例

curl https://api.pingxx.com/v1/apps/app_4OOi9SGuD88GGqbL/sub_apps/app_q5eff1jHKqXP9qvr \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Content-Type: application/json" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "display_name": "sub_app_name2",
    "metadata": {
        "key": "value"
    },
    "description": "Your description"
}'

返回示例

{
    "id": "app_q5eff1jHKqXP9qvr",
    "object": "sub_app",
    "created": 1488332846,
    "display_name": "sub_app_name2",
    "account": "acct_14yPiHyrb1GGub1m",
    "description": "Your description",
    "metadata": {
        "key": "value"
    },
    "available_methods": {},
    "user": "test_user_031",
    "parent_app": "app_rDyHSCy14aL8m9ev",
    "level" : 2
}

删除 Sub App 对象

调用该接口删除一个 sub_app 对象。删除后,该应用关联平台下的 user 对象 id 会被禁用。

请求参数
APP_ID required string 对应 app 对象的 id ,expandable 可展开,查看 如何获取App ID
SUB_APP_ID required string sub_app 对象的 id

返回

返回一个 JSON 格式的删除信息,或者返回一个错误,详见 错误

定义

DELETE https://api.pingxx.com/v1/apps/{APP_ID}/sub_apps/{SUB_APP_ID}

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/sub_apps/app_q5eff1jHKqXP9qvr \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Content-Type: application/json" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "deleted": true,
    "id": "SUB_APP_ID"
}

查询 Sub App 对象列表

调用该接口查询 sub_app 对象列表。

请求参数
app required string 对应 app 对象的 id ,查看 如何获取App ID
level optional int 当前层级,值为 1~5。
parent_app optional string 父级商户的 sub_app 对象的 id ,必须为平台或者平台下其他的子商户。
page optional int 页码,默认值为 "1",取值范围(1~100000000)。
per_page optional int 每页数量,默认值为"20",取值范围(1~100)。
created [ gt ] optional timestamp 大于对象的创建时间,用 Unix 时间戳表示。
created [ gte ] optional timestamp 大于或等于对象的创建时间,用 Unix 时间戳表示。
created [ lt ] optional timestamp 小于对象的创建时间,用 Unix 时间戳表示。
created [ lte ] optional timestamp 小于或等于对象的创建时间,用 Unix 时间戳表示。

返回

返回一个 sub_app 对象列表,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/sub_apps

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
  "object": "list",
  "url": "/v1/apps/app_4OOi9SGuD88GGqbL/sub_apps",
  "has_more": false,
  "data": [
    {
      "id": "app_q5eff1jHKqXP9qvr",
      "object": "sub_app",
      "created": 1488332846,
      "display_name": "sub_app_name2",
      "account": "acct_14yPiHyrb1GGub1m",
      "description": "Your description",
      "metadata": {
        "key": "value"
      },
      "available_methods": {},
      "user": "test_user_031",
      "parent_app": "app_rDyHSCy14aL8m9ev",
      "level": 2
    },
    {...},
    {...}
  ]
}

Channels 子商户渠道参数

属性
object string 值为 "channel"。
created timestamp 创建时的 Unix 时间戳。
channel string 第三方支付渠道属性。支付使用的渠道名称请参考 支付渠道属性值 ;企业付款使用的渠道名称: wx_pub (微信公众号)、 wx_lite (微信小程序)、 alipay (支付宝)、 unionpay (银联电子代付)、 unionpay_gz (贵州银联代付)、 allinpay (通联代付)和 jdpay (京东代付)。
params hash 子商户应用渠道参数列表,参见 子商户应用渠道参数说明
banned bool 是否禁用,禁用后该渠道不会出现在可用支付渠道列表中。
banned_msg string 禁用信息。
description string 描述。

对象示例

{
    "object": "channel",
    "created": 1486198795,
    "channel": "alipay",
    "params": [
        {
          "channel": "alipay",
          "fee_rate": "1",
          "alipay_app_auth_token": "201510BBaabdb44d8fd04607abf8d5931ec75D84",
          "alipay_user_id": "2088011177545623",
          "alipay_auth_app_id": "2013111800001989",
          "alipay_expires_in": "31536000",
          "alipay_re_expires_in": "32140800",
          "alipay_app_refresh_token": "201510BB09dece3ea7654531b66bf9f97cdceE67",
          "auth_type": "alipay_token"
        }
    ],
    "banned": false,
    "ban_msg": "werwerwer",
    "description": ""
}

创建子商户 Channel 对象

请求参数
APP_ID required string 平台应用 id 。查看 如何获取App ID
SUB_APP_ID required string 子商户应用 id
channel required string 第三方支付渠道属性。支付使用的渠道名称请参考 支付渠道属性值 ;企业付款使用的渠道名称: wx_pub (微信公众号)、 wx_lite (微信小程序)、 alipay (支付宝)、 unionpay (银联电子代付)、 unionpay_gz (贵州银联代付)、 allinpay (通联代付)和 jdpay (京东代付)。
params required hash 子商户应用渠道参数列表,见 子商户应用渠道参数说明
banned optional boolean 禁用信息。当 banned 为 true 时必填;为 false 时选填,可传空字符串将该字段置为空。
banned_msg optional string 禁用信息。
description optional string 描述。

返回

返回一个 channel 对象,或者返回一个错误,详见 错误

定义

POST https://api.pingxx.com/v1/apps/{APP_ID}/sub_apps/{SUB_APP_ID}/channels

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
  "channel": "alipay",
  "params": {
    "alipay_pid": "2088111111111111",
    "alipay_app_id": "2016666666666666",
    "alipay_account": "example@example.com",
    "alipay_security_key": "a5srakrbci3nf1pracb52xcs9xlhu8gu",
    "alipay_mer_app_private_key": "-----BEGIN PRIVATE KEY-----
    your private key
    -----END PRIVATE KEY-----",
    "alipay_app_public_key": "-----BEGIN PUBLIC KEY-----
    your public key
    -----END PUBLIC KEY-----",
    "alipay_mer_app_private_key_rsa2": null,
    "alipay_app_public_key_rsa2": null,
    "alipay_version": 1,
    "alipay_refund_nopwd": true
  },
  "banned": false,
  "banned_msg": "your banned_msg",
  "description": "Your alipay description"
}'

返回示例

{
  "object": "channel",
  "channel": "alipay",
  "banned": false,
  "banned_msg": "your banned_msg",
  "created": 1494854723,
  "description": "Your alipay description",
  "params": {
    "alipay_pid": "2088111111111111",
    "alipay_app_id": "2016666666666666",
    "alipay_account": "example@example.com",
    "alipay_security_key": "a5srakrbci3nf1pracb52xcs9xlhu8gu",
    "alipay_mer_app_private_key": "-----BEGIN PRIVATE KEY-----
    your private key
    -----END PRIVATE KEY-----",
    "alipay_app_public_key": "-----BEGIN PUBLIC KEY-----
    your public key
    -----END PUBLIC KEY-----",
    "alipay_mer_app_private_key_rsa2": null,
    "alipay_app_public_key_rsa2": null,
    "alipay_version": 1,
    "alipay_refund_nopwd": true
  }
}

查询子商户 Channel 对象

请求参数
APP_ID required string 平台应用 id
SUB_APP_ID required string 子商户应用 id
CHANNEL required string 支付渠道名称。

返回

返回一个 channel 对象,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/sub_apps/{SUB_APP_ID}/channels/{CHANNEL}

请求示例

curl https://api.pingxx.com/v1/apps/{APP_ID}/sub_apps/{SUB_APP_ID}/channels/{CHANNEL} \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Content-Type: application/json" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "object": "channel",
    "created": 1486198795,
    "channel": "alipay",
    "params": {
        "fee_rate": 60,
        "alipay_app_auth_token": "201510BBaabdb44d8fd04607abf8d5931ec75D84",
        "alipay_user_id": "2088011177545623",
        "alipay_auth_app_id": "2013111800001989",
        "alipay_expires_in": "31536000",
        "alipay_re_expires_in": "32140800",
        "alipay_app_refresh_token": "201510BB09dece3ea7654531b66bf9f97cdceE67",
        "auth_type": "alipay_token"
    },
    "banned": false,
    "banned_msg": null,
    "description": "description"
}

更新子商户 Channel 对象

请求参数
APP_ID required string 平台应用 id
SUB_APP_ID required string 子商户应用 id
CHANNEL required string 支付渠道名称。
params optional hash 子商户应用渠道参数列表,见 子商户应用渠道参数说明
banned optional boolean 是否禁用,禁用后该渠道不会出现在可用支付渠道列表中。
banned_msg optional string 1-255 位,禁用信息,当 bannedtrue 时可以填写。
description optional string 1-255 位,描述。

返回

返回一个 channel 对象,或者返回一个错误,详见 错误

定义

PUT https://api.pingxx.com/v1/apps/{APP_ID}/sub_apps/{SUB_APP_ID}/channels/{CHANNEL}

请求示例

curl https://api.pingxx.com/v1/apps/{APP_ID}/sub_apps/{SUB_APP_ID}/channels/{CHANNEL} \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Content-Type: application/json" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:\
-d'{
    "params": {
        "fee_rate": 60,
        "alipay_app_auth_token": "201510BBaabdb44d8fd04607abf8d5931ec75D84",
        "alipay_user_id": "2088011177545623",
        "alipay_auth_app_id": "2013111800001989",
        "alipay_expires_in": "31536000",
        "alipay_re_expires_in": "32140800",
        "alipay_app_refresh_token": "201510BB09dece3ea7654531b66bf9f97cdceE67"
    },
    "banned": false,
    "banned_msg": null,
    "description": "description"
}'

返回示例

{
    "object": "channel",
    "created": 1486198795,
    "channel": "alipay",
    "params": {
        "fee_rate": 60,
        "alipay_app_auth_token": "201510BBaabdb44d8fd04607abf8d5931ec75D84",
        "alipay_user_id": "2088011177545623",
        "alipay_auth_app_id": "2013111800001989",
        "alipay_expires_in": "31536000",
        "alipay_re_expires_in": "32140800",
        "alipay_app_refresh_token": "201510BB09dece3ea7654531b66bf9f97cdceE67"
    },
    "banned": false,
    "banned_msg": null,
    "description": "description"
}

删除子商户 Channel 对象

请求参数
APP_ID required string 平台应用 id
SUB_APP_ID required string 子商户应用 id
CHANNEL required string 支付渠道名称。

返回

返回一个 JSON 格式的删除信息,或者返回一个错误,详见 错误

定义

DELETE https://api.pingxx.com/v1/apps/{APP_ID}/sub_apps/{SUB_APP_ID}/channels/{CHANNEL}

请求示例

curl https://api.pingxx.com/v1/apps/{APP_ID}/sub_apps/{SUB_APP_ID}/channels/{CHANNEL} \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Content-Type: application/json" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "deleted": true,
    "channel": "CHANNEL"
}

Recharges 充值

通过创建 recharge 对象,为用户的余额进行充值。充值完成后可以调用 user 对象查询接口,查询用户的余额。

属性
id string 充值对象 ID,由 Ping++ 生成。
object string 值为 "Recharge"。
app string 对应 app 对象的 id ,查看 如何获取App ID
created timestamp 创建时间,用 Unix 时间戳表示。
livemode boolean 是否是 live 模式。
amount int 用户实际到账余额,单位为分(包含赠送金额和扣除用户手续费,例如充 100 送 20,则该值是 120;充 100 收 5 元用户手续费,则该值是 95)。
succeeded boolean 是否已充值成功。
time_succeeded timestamp 充值成功时间,用 Unix 时间戳表示。
refunded boolean 是否存在退款(跟是否退款成功没有关系)。
user string 充值目标 user 对象的 id ,64 位以内。
from_user string 充值来源 user 对象的 id ,64 位以内。
user_fee int 收取的用户手续费,单位为分,取值范围 0~1000000000。
charge object 支付使用的 charge 对象。
balance_bonus object 包含的 balance_bonus 对象。
refunds list 包含的 refund 对象列表。
balance_transaction string 关联的 balance_transaction 对象的 id
description string 附加说明,最多 255 个 Unicode 字符。
metadata hash 详见 元数据

示例对象

{
  "id": "2001706060000002372",
  "object": "recharge",
  "app": "app_1Gqj58ynP0mHeX1q",
  "created": "1496740128",
  "livemode": false,
  "amount": 1000,
  "succeeded": false,
  "time_succeeded": null,
  "refunded": false,
  "user": "test_user_02",
  "from_user": "test_user_01",
  "user_fee": 100,
  "charge": {
    "id": "ch_SejbHOrzbjvPunjHmD08SCi9",
    "object": "charge",
    "created": 1496740128,
    "livemode": false,
    "paid": false,
    "refunded": false,
    "reversed": false,
    "app": "app_1Gqj58ynP0mHeX1q",
    "channel": "upacp",
    "order_no": "20161000167",
    "client_ip": "127.0.0.1",
    "amount": 10000,
    "amount_settle": 10000,
    "currency": "cny",
    "subject": "测试订单007测试订单007&",
    "body": "订单内容007",
    "extra": {},
    "time_paid": null,
    "time_expire": 1496826528,
    "time_settle": null,
    "transaction_no": null,
    "refunds": {
      "object": "list",
      "url": "/v1/charges/ch_SejbHOrzbjvPunjHmD08SCi9/refunds",
      "has_more": false,
      "data": []
    },
    "amount_refunded": 0,
    "failure_code": null,
    "failure_msg": null,
    "metadata": {},
    "credential": {
      "object": "credential",
      "upacp": {
        "tn": "201409161028470000000",
        "mode": "01"
      }
    },
    "description": null
  },
  "balance_bonus": {},
  "refunds": {},
  "balance_transaction": "",
  "description": "",
  "metadata": {}
}

创建 Recharge 对象

发起一次充值请求时需要创建一个新的 recharge 对象,获取一个可用的 charge 对象用于客户端向第三方渠道发起支付请求。如果使用测试模式的 API Key,则不会发生真实交易。当充值成功后,Ping++ 会发送 Webhooks 通知。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
user required string 充值目标 user 对象的 id ,64 位以内。
charge [ amount ] required integer 支付金额,单位为分,取值范围 0~1000000000。
charge [ channel ] required string 支付使用的第三方支付渠道,详情参考 支付渠道属性值 。除此之外,还支持自定义渠道 custom ,该渠道不需要真实支付,仅对用户 "0" 有效。
charge [ order_no ] required string 商户订单号,适配每个渠道对此参数的要求,必须在商户系统内唯一。长度限制在 8~20 位。
charge [ subject ] required string 标题,该参数最长为 32 个 Unicode 字符,银联全渠道( upacpupacp_wap )限制在 32 个字节。
charge [ body ] required string 描述信息,该参数最长为 128 个 Unicode 字符, yeepay_wap 对于该参数长度限制为 100 个 Unicode 字符。
charge [ time_expire ] optional timestamp 支付失效时间,用 Unix 时间戳表示。时间范围在支付创建后的 5 分钟到 1 天,默认为 1 天,创建时间以 Ping++ 服务器时间为准。 微信对该参数的有效值限制为 2 小时内;银联对该参数的有效值限制为 1 小时内。
charge [ client_ip ] optional string 客户端的 IP,IPV4,默认 127.0.0.1。
charge [ extra ] optional hash 特定渠道发起交易时需要的额外参数,以及部分渠道支付成功返回的额外参数。
user_fee optional integer 充值收取的用户手续费,单位为分,不得大于 charge[amount] ,不可和 balance_bonus[amount] 同时使用,默认 0。
balance_bonus [ amount ] optional integer 充值赠送的余额,单位为分,不可和 user_fee 同时传,默认 0。
from_user optional string 充值来源 user 对象的 id ,默认和 user 相同,即给自己充值。
description optional string 附加说明,最多 255 个 Unicode 字符。
metadata optional hash 详见 元数据

返回

返回一个 recharge 对象,或者返回一个错误,详见 错误

定义

POST https://api.pingxx.com/v1/apps/{APP_ID}/recharges

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/recharges \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1496728534" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
  "user": "test_user_02",
  "user_fee": 100,
  "from_user": "test_user_01",
  "charge": {
    "amount":1000,
    "time_expire": 1496826528,
    "order_no":"20161000167",
    "client_ip":"127.0.0.1",
    "extra":{}
  },
  "client_ip": "127.0.0.1",
  "description": "Your description"
}'

返回示例

{
  "id": "2001706060000002372",
  "object": "recharge",
  "app": "app_1Gqj58ynP0mHeX1q",
  "created": "1496740128",
  "livemode": false,
  "amount": 1000,
  "succeeded": false,
  "time_succeeded": null,
  "refunded": false,
  "user": "test_user_02",
  "from_user": "test_user_01",
  "user_fee": 100,
  "charge": {
    "id": "ch_SejbHOrzbjvPunjHmD08SCi9",
    "object": "charge",
    "created": 1496740128,
    "livemode": false,
    "paid": false,
    "refunded": false,
    "reversed": false,
    "app": "app_1Gqj58ynP0mHeX1q",
    "channel": "upacp",
    "order_no": "20161000167",
    "client_ip": "127.0.0.1",
    "amount": 10000,
    "amount_settle": 10000,
    "currency": "cny",
    "subject": "测试订单007测试订单007&",
    "body": "订单内容007",
    "extra": {},
    "time_paid": null,
    "time_expire": 1496826528,
    "time_settle": null,
    "transaction_no": null,
    "refunds": {
      "object": "list",
      "url": "/v1/charges/ch_SejbHOrzbjvPunjHmD08SCi9/refunds",
      "has_more": false,
      "data": []
    },
    "amount_refunded": 0,
    "failure_code": null,
    "failure_msg": null,
    "metadata": {},
    "credential": {
      "object": "credential",
      "upacp": {
        "tn": "201409161028470000000",
        "mode": "01"
      }
    },
    "description": null
  },
  "balance_bonus": {},
  "refunds": {},
  "balance_transaction": "",
  "description": "",
  "metadata": {}
}

查询 Recharge 对象

通过 recharge 对象的 id 查询一个已创建的 recharge 对象。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
RECHARGE_ID required string recharge 对象的 id

返回

返回一个 recharge 对象,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/recharges/{RECHARGE_ID}

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/recharges/2001706060000002372 \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1496728534" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
  "id": "2001706060000002372",
  "object": "recharge",
  "app": "app_1Gqj58ynP0mHeX1q",
  "created": "1496740128",
  "livemode": false,
  "amount": 1000,
  "succeeded": false,
  "time_succeeded": null,
  "refunded": false,
  "user": "test_user_02",
  "from_user": "test_user_01",
  "user_fee": 100,
  "charge": {
    "id": "ch_SejbHOrzbjvPunjHmD08SCi9",
    "object": "charge",
    "created": 1496740128,
    "livemode": false,
    "paid": false,
    "refunded": false,
    "reversed": false,
    "app": "app_1Gqj58ynP0mHeX1q",
    "channel": "upacp",
    "order_no": "20161000167",
    "client_ip": "127.0.0.1",
    "amount": 10000,
    "amount_settle": 10000,
    "currency": "cny",
    "subject": "测试订单007测试订单007&",
    "body": "订单内容007",
    "extra": {},
    "time_paid": null,
    "time_expire": 1496826528,
    "time_settle": null,
    "transaction_no": null,
    "refunds": {
      "object": "list",
      "url": "/v1/charges/ch_SejbHOrzbjvPunjHmD08SCi9/refunds",
      "has_more": false,
      "data": []
    },
    "amount_refunded": 0,
    "failure_code": null,
    "failure_msg": null,
    "metadata": {},
    "credential": {
      "object": "credential",
      "upacp": {
        "tn": "201409161028470000000",
        "mode": "01"
      }
    },
    "description": null
  },
  "balance_bonus": {},
  "refunds": {},
  "balance_transaction": "",
  "description": "",
  "metadata": {}
}

查询 Recharge 对象列表

返回之前创建过 recharge 对象的一个列表。列表是按创建时间进行排序,总是将最新的 recharge 对象显示在最前。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
user optional string 充值目标 user 对象的 id
from_user optional string 充值来源 user 对象的 id
succeeded boolean string 是否已充值成功。
refunded boolean string 是否存在退款(跟是否退款成功没有关系)。
charge [ channel ] optional string 充值使用的支付渠道。
charge [ order_no ] optional string 充值使用的商户订单号。
page optional integer 页码,默认值为 "1",取值范围 1~100000000。
per_page optional integer 每页数量,默认值为 "20",取值范围 1~100。
created [ gt ] optional integer 创建时间大于该值,用 Unix 时间戳表示。
created [ gte ] optional integer 创建时间大于或等于该值,用 Unix 时间戳表示。
created [ lt ] optional integer 创建时间小于该值,用 Unix 时间戳表示。
created [ lte ] optional integer 创建时间小于或等于该值,用 Unix 时间戳表示。

返回

返回一个 recharge 对象列表,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/recharges

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/recharges \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1496728534" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
  "object": "list",
  "url": "/v1/apps/app_1Gqj58ynP0mHeX1q/recharges",
  "has_more": true,
  "data": [
    {
		  "id": "2001706060000002372",
		  "object": "recharge",
		  "app": "app_1Gqj58ynP0mHeX1q",
		  "created": "1496740128",
		  "livemode": false,
		  "amount": 1000,
		  "succeeded": false,
		  "time_succeeded": null,
		  "refunded": false,
		  "user": "test_user_02",
		  "from_user": "test_user_01",
		  "user_fee": 100,
		  "charge": {
		    "id": "ch_SejbHOrzbjvPunjHmD08SCi9",
		    "object": "charge",
		    "created": 1496740128,
		    "livemode": false,
		    "paid": false,
		    "refunded": false,
		    "reversed": false,
		    "app": "app_1Gqj58ynP0mHeX1q",
		    "channel": "upacp",
		    "order_no": "20161000167",
		    "client_ip": "127.0.0.1",
		    "amount": 10000,
		    "amount_settle": 10000,
		    "currency": "cny",
		    "subject": "测试订单007测试订单007&",
		    "body": "订单内容007",
		    "extra": {},
		    "time_paid": null,
		    "time_expire": 1496826528,
		    "time_settle": null,
		    "transaction_no": null,
		    "refunds": {
		      "object": "list",
		      "url": "/v1/charges/ch_SejbHOrzbjvPunjHmD08SCi9/refunds",
		      "has_more": false,
		      "data": []
		    },
		    "amount_refunded": 0,
		    "failure_code": null,
		    "failure_msg": null,
		    "metadata": {},
		    "credential": {
		      "object": "credential",
		      "upacp": {
		        "tn": "201409161028470000000",
		        "mode": "01"
		      }
		    },
		    "description": null
		  },
		  "balance_bonus": {},
		  "refunds": {},
		  "balance_transaction": "",
		  "description": "",
		  "metadata": {}
		},
    {...},
    {...}
  ]
}

Recharge 相关的 Event 类型

该类型的 Event 对象会在 recharge 对象充值成功后触发,以 Webhooks 形式发送至客户配置的 Webhooks URL 。详情请参考 Events 事件

事件类型
recharge.succeeded 充值成功后触发。
charge.succeeded 充值成功后触发。

充值 Refunds 退款

属性参考 Refund 退款

对象示例

{
  "id": "re_y1u944PmfnrTHyvnL0nD0iD1",
  "object": "refund",
  "order_no": "y1u944PmfnrTHyvnL0nD0iD1",
  "amount": 9,
  "created": 1409634160,
  "succeed": true,
  "status": "succeeded",
  "time_succeed": 1409634192,
  "description": "Refund Description",
  "failure_code": null,
  "failure_msg": null,
  "metadata": {},
  "charge": "ch_L8qn10mLmr1GS8e5OODmHaL4",
  "charge_order_no": "123456789",
  "transaction_no": "2004450349201512090096425284"
}

创建充值 Refund 对象

通过发起一次充值退款请求创建一个新的 refund 对象,只能对已经充值成功的 recharge 对象发起全额退款。当退款成功后,会发送 Webhooks 通知。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
RECHARGE_ID required string recharge 对象的 id
description required string 附加说明,最多 255 个 Unicode 字符。
funding_source optional string 微信退款资金来源。取值范围: unsettled_funds :使用未结算资金退款; recharge_funds :使用可用余额退款。注:默认值 unsettled_funds ,该参数仅适用于所有微信渠道,包括 wxwx_pubwx_pub_qrwx_litewx_wap 五个渠道;该参数仅在请求退款,传入该字段时返回。
metadata optional hash 详见 元数据

返回

返回一个 refund 对象,或者返回一个错误,详见 错误

定义

POST https://api.pingxx.com/v1/apps/{APP_ID}/recharges/{RECHARGE_ID}/refunds

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/recharges/2001706060000002372/refunds \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1496728534" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d {
    "description": "reharge refunds"
}

返回示例

{
  "id": "re_vXr14Se1GOGKyjzj5KPKizv9",
  "object": "refund",
  "order_no": "20161000167",
  "amount": 10000,
  "created": 1496743652,
  "succeed": false,
  "status": "pending",
  "time_succeed": null,
  "description": "reharge refunds",
  "failure_code": null,
  "failure_msg": null,
  "metadata": {},
  "charge": "ch_SejbHOrzbjvPunjHmD08SCi9",
  "charge_order_no": "20161000167",
  "transaction_no": null,
  "extra": {}
}

查询充值 Refund 对象

通过充值 refund 对象的 id 查询一个已创建的充值 refund 对象。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
RECHARGE_ID required string recharge 对象的 id
REFUND_ID required string refund 对象的 id

返回

返回一个 refund 对象,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/recharges/{RECHARGE_ID}/refunds/{REFUND_ID}

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/recharges/2001706060000002372/refunds/re_vXr14Se1GOGKyjzj5KPKizv9 \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1496728534" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
  "id": "re_vXr14Se1GOGKyjzj5KPKizv9",
  "object": "refund",
  "order_no": "20161000167",
  "amount": 10000,
  "created": 1496743652,
  "succeed": false,
  "status": "pending",
  "time_succeed": null,
  "description": "reharge refunds",
  "failure_code": null,
  "failure_msg": null,
  "metadata": {},
  "charge": "ch_SejbHOrzbjvPunjHmD08SCi9",
  "charge_order_no": "20161000167",
  "transaction_no": null,
  "extra": {}
}

查询充值 Refund 对象列表

返回之前创建 recharge 对象的一个 refund 对象列表。列表是按创建时间进行排序,总是将最新的 refund 对象显示在最前。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
RECHARGE_ID required string recharge 对象的 id
page optional int 页码,默认值为 "1",取值范围(1~100000000)。
per_page optional int 每页数量,默认值为 "10",取值范围(1~100)。
created [ gt ] optional timestamp 创建时间大于该值,用 Unix 时间戳表示。
created [ gte ] optional timestamp 创建时间大于或等于该值,用 Unix 时间戳表示。
created [ lt ] optional timestamp 创建时间小于该值,用 Unix 时间戳表示。
created [ lte ] optional timestamp 创建时间小于或等于该值,用 Unix 时间戳表示。

返回

返回一个 refund 对象列表,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/recharges/{RECHARGE_ID}/refunds

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/recharges/2001706060000002372/refunds \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1496728534" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
  "object": "list",
  "url": "/v1/apps/app_1Gqj58ynP0mHeX1q/recharges/2001706060000002372/refunds",
  "has_more": false,
  "data": [
    {
      "id": "re_vXr14Se1GOGKyjzj5KPKizv9",
      "object": "refund",
      "order_no": "20161000167",
      "amount": 10000,
      "created": 1496743652,
      "succeed": false,
      "status": "pending",
      "time_succeed": null,
      "description": "reharge refunds",
      "failure_code": null,
      "failure_msg": null,
      "metadata": {},
      "charge": "ch_SejbHOrzbjvPunjHmD08SCi9",
      "charge_order_no": "20161000167",
      "transaction_no": null,
      "extra": {}
    }
  ]
}

充值 Refund 相关的 Event 类型

该类型的 Event 对象会在 refund 对象充值退款成功后触发,以 Webhooks 形式发送至客户配置的 Webhooks URL 。详情请参考 Events 事件

事件类型
recharge.refund.succeeded 退款成功后触发。
refund.succeeded 退款成功后触发。

Withdrawals 提现

用户发起提现申请时,你可以请求一个 withdrawal 对象,之后你可以对该笔提现进行审核,发起提现确认或提现取消。注:微信服务商模式商户暂不支持提现。

参数
id string 提现对象 ID,由 Ping++ 生成。
object string 值为 "withdrawal"。
app string 对应 app 对象的 id ,查看 如何获取App ID
amount int 提现扣除的余额,单位为分。
asset_transaction string 关联的 asset_transaction 对象的 id
balance_transaction string 关联的 balance_transaction 对象的 id
channel string 提现使用的付款渠道: wx_pub (微信公众号)、 wx_lite (微信小程序)、 alipay (支付宝)、 unionpay (银联)、 unionpay_gz (贵州银联)、 allinpay (通联)和 jdpay (京东)。
created timestamp 创建时间,用 Unix 时间戳表示。
description string 附加说明,最多 60 个 Unicode 字符。
extra hash 附加参数,提现付款的相关信息。
failure_msg string 错误消息的描述。
fee int 手续费,可能是渠道/银行收取。
livemode boolean 是否处于 live 模式。
operation_url string 支付宝批量付款 URL。
order_no string 提现的商户订单号, 1~16 位纯数字。
source string 关联的 transfer 对象的 id
status string 提现状态,已申请: created ,处理中: pending ,完成: succeeded ,失败: failed ,取消: canceled
time_canceled timestamp 提现取消时间,用 Unix 时间戳表示。
time_succeeded timestamp 提现成功时间,用 Unix 时间戳表示。
user string 提现关联 user 对象的 id
user_fee int 需要承担的用户手续费,单位为分。
settle_account string 提现使用的 settle_account 对象的 id
metadata hash 详见 元数据
extra 参数(unionpay)
account string 1~32位,收款人银行卡号或者存折号。
name string 1~100位,收款人姓名。
open_bank_code string 4位,开户银行编号,详情请参考 银联电子代付银行编号说明
open_bank string 1~50位,开户银行。
prov string 1~20位,省份。
city string 1~40位,城市。
sub_bank string 1~80位,开户支行名称。

注:open_bank_codeopen_bank 两个参数必传一个,建议使用 open_bank_code ,若都传参则优先使用 open_bank_code 读取规则;provcity 均为可选参数,如果不传参,则使用默认值 "上海" 给渠道接口。

extra 参数(unionpay_gz)
account string 1~32位,收款人银行卡号。
name string 1~100位,收款人姓名。
extra 参数(alipay)
account string 接收者支付宝账号。
name string 收款人姓名。
account_type string 收款方账户类型。默认值:"ALIPAY_LOGONID"。ALIPAY_USERID:支付宝账号对应的支付宝唯一用户号,以 2088 开头的 16 位纯数字组成;ALIPAY_LOGONID:支付宝登录号,支持邮箱和手机号格式。
extra 参数(wx_pub、wx_lite)
open_id string 微信公众平台下对应获取的用户 open_id。
name string 收款人姓名。
force_check boolean 是否强制校验收款人姓名。仅当 name 参数不为空时该参数生效。
extra 参数(allinpay)
account string 收款人银行卡号或者存折号。
name string 收款人姓名。
open_bank_code string 开户银行编号。
business_code string 业务代码,根据通联业务人员提供,不填则使用通联提供默认值为 "09900"。
card_type int 银行卡号类型,0:银行卡;1:存折,默认值为 "0"。
extra 参数(jdpay)
account string 收款人银行卡号或者存折号。
name string 收款人姓名。
open_bank_code string 开户银行编号。

示例对象

{
    "id": "1701611150302360654",
    "object": "withdrawal",
    "app": "app_1Gqj58ynP0mHeX1q",
    "amount": 20000,
    "asset_transaction": "",
    "balance_transaction": "",
    "channel": "unionpay",
    "created": 1472648887,
    "description": "test232description",
    "extra": {
        "account": "6225210207073918",
        "name": "姓名",
        "open_bank_code": "0102",
        "prov": "上海",
        "city": "上海"
    },
    "fee": 200,
    "livemode": true,
    "metadata":{},
    "order_no": "20160829133002",
    "source": null,
    "status": "created",
    "time_canceled": null,
    "time_succeeded": null,
    "user": "user_001",
    "user_fee": 50
}

创建 Withdrawal 对象

通过调用该接口发起一笔用户提现申请,提现申请表示用户提现意图,不会真实发起付款行为,需要后续确认。注:微信服务商模式商户暂不支持提现。

请求参数
app required string 对应 app 对象的 id ,查看 如何获取App ID
user required string user 对象的 id
amount required int 提现扣除的余额,单位为分,取值范围 1~1000000000。
channel required string 提现使用的付款渠道: wx_pub (微信公众号)、 wx_lite (微信小程序)、 alipay (支付宝)、 unionpay (银联)、 unionpay_gz (贵州银联)、 allinpay (通联)和 jdpay (京东)。
user_fee required int 需要承担的用户手续费,单位为分。
description optional string 附加说明,最多 60 个 Unicode 字符。
extra optional hash 相关的附加参数,详情参考下表的 extra 参数说明。
metadata optional hash 详见 元数据
order_no optional string 提现使用的商户订单号, 1~16 位纯数字。
settle_account optional string 使用 settle_account 提现,该用户结算账户必须属于 user ,使用用户结算账户提现时不需要填写 extra 参数。
extra 参数(unionpay)
account required string 1~32位,收款人银行卡号或者存折号。
name required string 1~100位,收款人姓名。
open_bank_code optional string 4位,开户银行编号,详情请参考 银联电子代付银行编号说明
open_bank optional string 1~50位,开户银行。
prov optional string 1~20位,省份。
city optional string 1~40位,城市。
sub_bank optional string 1~80位,开户支行名称。

注:open_bank_codeopen_bank 两个参数必传一个,建议使用 open_bank_code ,若都传参则优先使用 open_bank_code 读取规则;provcity 均为可选参数,如果不传参,则使用默认值 "上海" 给渠道接口。

extra 参数(unionpay_gz)
account required string 1~32位,收款人银行卡号。
name required string 1~100位,收款人姓名。
extra 参数(alipay)
account required string 接收者支付宝账号。
name required string 收款人姓名。
account_type optional string 收款方账户类型。默认值:"ALIPAY_LOGONID"。ALIPAY_USERID:支付宝账号对应的支付宝唯一用户号,以 2088 开头的 16 位纯数字组成;ALIPAY_LOGONID:支付宝登录号,支持邮箱和手机号格式。
extra 参数(wx_pub、wx_lite)
open_id required string 微信公众平台下对应获取的用户 open_id。
name optional string 收款人姓名。
force_check optional boolean 是否强制校验收款人姓名。仅当 name 参数不为空时该参数生效。
extra 参数(allinpay)
account required string 收款人银行卡号或者存折号。
name required string 收款人姓名。
open_bank_code required string 开户银行编号。
business_code optional string 业务代码,根据通联业务人员提供,不填则使用通联提供默认值为 "09900"。
card_type optional int 银行卡号类型,0:银行卡;1:存折,默认值为 "0"。
extra 参数(jdpay)
account required string 收款人银行卡号或者存折号。
name required string 收款人姓名。
open_bank_code required string 开户银行编号。

返回

返回一个 withdrawal 提现对象,或者返回一个错误,详见 错误

定义

POST https://api.pingxx.com/v1/apps/{APP_ID}/withdrawals

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/withdrawals \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1478833871" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "amount": 20000,
    "user": "user_001",
    "user_fee": 50,
    "description": "test232description",
    "channel": "unionpay",
    "extra": {
        "account": "6225210207073918",
        "name": "姓名",
        "open_bank_code": "0102",
        "prov": "上海",
        "city": "上海"
    }
}'

返回示例

{
    "id": "1701611150302360654",
    "object": "withdrawal",
    "app": "app_LibTW1n1SOq9Pin1",
    "amount": 20000,
    "asset_transaction": "",
    "balance_transaction": "",
    "channel": "unionpay",
    "created": 1472648887,
    "description": "test232description",
    "extra": {
        "account": "6225210207073918",
        "name": "姓名",
        "open_bank_code": "0102",
        "prov": "上海",
        "city": "上海"
    },
    "fee": 200,
    "livemode": true,
    "metadata":{},
    "order_no": "20160829133002",
    "source": null,
    "status": "created",
    "time_canceled": null,
    "time_succeeded": null,
    "user_fee": 50
}

更新 Withdrawal 对象

审核一笔用户提现申请,如果确认提现,则会发起真实提现打款。若提现成功,则 withdrawal 对象的 status 值变为 succeeded,Ping++ 会发送提现成功的 Webhooks 通知;若提现因用户原因失败(如提现账户有误),则 withdrawal 对象的 status 值变为 failed,Ping++ 会发送提现失败的 Webhooks 通知;若提现因非用户原因失败(如商户付款金额不足),则 withdrawal 对象的 status 值变为 created。如果使用测试模式的 API Key,则不会发生真实交易。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
WITHDRAWAL_ID required string 提现对象的 id
status required string 取值范围:确认为 pending ,取消为 canceled
  • withdrawal 对象会根据渠道的返回置为 "succeeded" 、 "failed"、"created" 状态。

返回

返回一个 withdrawal 提现对象,或者返回一个错误,详见 错误

定义

PUT https://api.pingxx.com/v1/apps/{APP_ID}/withdrawals/{WITHDRAWAL_ID}

请求示例

curl https://api.pingxx.com/v1/apps/{app_id}/withdrawals/{WITHDRAWAL_ID} \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:
-d '{
   "status": "pending"
}'

返回示例

{
    "id": "1701611150302360654",
    "object": "withdrawal",
    "app": "app_1Gqj58ynP0mHeX1q",
    "amount": 20000,
    "asset_transaction": "",
    "balance_transaction": "",
    "channel": "unionpay",
    "created": 1472648887,
    "description": "test232description",
    "extra": {
        "account": "6225210207073918",
        "name": "姓名",
        "open_bank_code": "0102",
        "prov": "上海",
        "city": "上海"
    },
    "fee": 200,
    "livemode": true,
    "metadata":{},
    "order_no": "20160829133002",
    "source": null,
    "status": "pending",
    "time_canceled": null,
    "time_succeeded": null,
    "user": "user_001",
    "user_fee": 50
}

查询 Withdrawal 对象

通过 withdrawal 对象的 id 查询一个已创建的 withdrawal 对象。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
WITHDRAWAL_ID required string 提现对象的 id

返回

返回一个 withdrawal 提现对象,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/withdrawals/{WITHDRAWAL_ID}

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/withdrawals/1701611150302360654 \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1478833871" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "id": "1701611150302360654",
    "object": "withdrawal",
    "app": "app_LibTW1n1SOq9Pin1",
    "amount": 20000,
    "asset_transaction": "",
    "balance_transaction": "",
    "channel": "unionpay",
    "created": 1472648887,
    "description": "test232description",
    "extra": {
        "account": "6225210207073918",
        "name": "姓名",
        "open_bank_code": "0102",
        "prov": "上海",
        "city": "上海"
    },
    "fee": 200,
    "livemode": true,
    "metadata":{},
    "order_no": "20160829133002",
    "source": null,
    "status": "created",
    "time_canceled": null,
    "time_succeeded": null,
    "user_fee": 50
}

查询 Withdrawal 对象列表

返回之前创建过 withdrawal 对象的一个列表。列表是按创建时间进行排序,总是将最新的 withdrawal 对象显示在最前。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
user optional string user 对象的 id
page optional int 页码,默认值为 "1",取值范围:1~100000000。
per_page optional int 每页数量,默认值为 "10"。
created [ gt ] optional timestamp 创建时间大于该值,用 Unix 时间戳表示。
created [ gte ] optional timestamp 创建时间大于或等于该值,用 Unix 时间戳表示。
created [ lt ] optional timestamp 创建时间小于该值,用 Unix 时间戳表示。
created [ lte ] optional timestamp 创建时间小于或等于该值,用 Unix 时间戳表示。
status optional string 提现状态。已申请: created ,处理中: pending ,成功: succeeded ,失败: failed ,取消: canceled ,部分成功: partially_succeeded
channel optional string 提现使用的付款渠道: wx_pub (微信公众号)、 wx_lite (微信小程序)、 alipay (支付宝)、 unionpay (银联)、 unionpay_gz (贵州银联)、 allinpay (通联)和 jdpay (京东)。

返回

返回一个 withdrawal 对象列表,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/withdrawals

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/withdrawals/1701611150302360654?user=user_001 \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1478833871" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "object": "list",
    "url": "/v1/apps/app_1Gqj58ynP0mHeX1q/withdrawals",
    "has_more": true,
    "total_withdrawals_amount": 100000,
    "data": [
        {
            "id": "1701611150302360654",
            "object": "withdrawal",
            "app": "app_1Gqj58ynP0mHeX1q",
            "amount": 20000,
            "asset_transaction": "",
            "balance_transaction": "",
            "channel": "unionpay",
            "created": 1472648887,
            "description": "test232description",
            "extra": {
                "account": "6225210207073918",
                "name": "姓名",
                "open_bank_code": "0102",
                "prov": "上海",
                "city": "上海"
            },
            "fee": 200,
            "livemode": true,
            "metadata":{},
            "order_no": "20160829133002",
            "source": null,
            "status": "created",
            "time_canceled": null,
            "time_succeeded": null,
            "user": "user_001",
            "user_fee": 50
        },
        {...},
        {...}
    ] *
}

Withdrawal 相关的 Event 类型

该类型的 Event 对象会在包含的 withdrawal 对象提现完成后触发,包括:提现成功、提现失败,以 Webhooks 形式发送至客户配置的 Webhooks URL 。详情请参考 Events 事件

事件类型
balance.withdrawal.succeeded 提现成功触发。
balance.withdrawal.failed 提现失败触发。

Batch Withdrawals 批量提现

你可以使用批量提现接口,批量对用户的提现申请做确认动作。

属性
id string 批量提现 id
object string 值为 "batch_withdrawal"。
app string 对应 app 对象的 id ,查看 如何获取App ID
created timestamp 创建时间,用 Unix 时间戳表示。
livemode boolean 是否处于 live 模式。
amount int 提现扣除的总金额,单位为分。
amount_succeeded int 提现成功金额。
amount_failed int 提现失败金额。
amount_canceled int 提现取消金额。
count int 总提现笔数。
count_succeeded int 提现成功笔数。
count_failed int 提现失败笔数。
count_canceled int 提现取消笔数。
fee int 渠道收取的手续费总额。
operation_url string 支付宝批量付款 URL。
source string 关联 batch_transfer 对象的 id
status string 批量提现状态。处理中: pending ,全部成功: succeeded ,全部失败: failed ,取消: canceled ,部分成功: partially_succeeded
user_fee int 承担的用户手续费总额。
withdrawals list 包含的 withdrawal 对象列表。
time_finished int 完成时间,用 Unix 时间戳表示。
metadata hash 详见 元数据

创建 Batch Withdrawal 对象

你可以通过创建 batch_withdrawal 对象对多个提现申请状态的 withdrawal 对象做批量确认或取消。在批量动作完成后,所以包含的 withdrawal 对象的状态都会进行相应的改变。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
withdrawals required array withdrawal 对象的 id 列表,不能超过 200 个元素。
metadata optional hash 详见 元数据
status optional string 提现操作。提现确认: pending ,提现取消: canceled ,默认值: pending

返回

返回一个 batch_withdrawal 对象,或者返回一个错误,详见 错误

定义

POST https://api.pingxx.com/v1/apps/{APP_ID}/batch_withdrawals

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/batch_withdrawals \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1478833871" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "withdrawals": [
        "1701611150302360654",
        "1701611151015078981"
    ]
}'

返回示例

{
    "id": "1901611151015122025",
    "object": "batch_withdrawal",
    "app": "app_1Gqj58ynP0mHeX1q",
    "created": 1478833871,
    "livemode": false,
    "amount": 80000,
    "amount_succeeded": 0,
    "amount_failed": 0,
    "amount_canceled": 0,
    "count_succeeded": 0,
    "count_failed": 0,
    "count_canceled": 0,
    "fee": 0,
    "metadata": {},
    "status": "pending",
    "user_fee": 0,
    "withdrawals": {
        "object": "list",
        "url": null,
        "has_more": false,
        "data": [
            {
                "id": "1701611150302360654",
                "object": "withdrawal",
                "app": "app_1Gqj58ynP0mHeX1q",
                "amount": 20000,
                "asset_transaction": "",
                "balance_transaction": "",
                "channel": "alipay",
                "created": 1472648887,
                "description": "test232description",
                "extra": {
                    "account": "username@gmail.com",
                    "name": "姓名"
                },
                "fee": 200,
                "livemode": false,
                "metadata":{},
                "order_no": "20160829133002",
                "source": null,
                "status": "pending",
                "time_canceled": null,
                "time_succeeded": null,
                "user": "user_001",
                "user_fee": 50
            },
            {...},
            {...}
        ]
    }
}

查询 Batch Withdrawal 对象

通过 batch_withdrawal 对象的 id 查询一个已创建的 batch_withdrawal 对象。

请求参数
APP_ID string required 对应 app 对象的 id ,查看 如何获取App ID
BATCH_WITHDRAWAL_ID string required batch_withdrawal 对象的 id

返回

返回一个 batch_withdrawal 对象,或者一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/batch_withdrawals/{BATCH_WITHDRAWAL_ID}

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/batch_withdrawals/1901611151015122025 \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1478833871" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "id": "1901611151015122025",
    "object": "batch_withdrawal",
    "app": "app_1Gqj58ynP0mHeX1q",
    "created": 1478833871,
    "livemode": false,
    "amount": 80000,
    "amount_succeeded": 0,
    "amount_failed": 0,
    "amount_canceled": 0,
    "count": 3,
    "count_succeeded": 0,
    "count_failed": 0,
    "count_canceled": 0,
    "fee": 0,
    "metadata": {},
    "operation_url": "https://mapi.alipay.com/gateway.do?",
    "status": "pending",
    "source": "1801701051435464631",
    "time_finished": null,
    "user_fee": 0,
    "withdrawals": {
        "object": "list",
        "url": null,
        "has_more": false,
        "data": [
            {
                "id": "1701611150302360654",
                "object": "withdrawal",
                "app": "app_1Gqj58ynP0mHeX1q",
                "amount": 20000,
                "asset_transaction": "",
                "balance_transaction": "",
                "channel": "alipay",
                "created": 1472648887,
                "description": "test232description",
                "extra": {
                    "account": "username@gmail.com",
                    "name": "姓名"
                },
                "failure_msg": null,
                "fee": 200,
                "livemode": false,
                "metadata":{},
                "operation_url": null,
                "order_no": "20160829133002",
                "source": null,
                "status": "pending",
                "time_canceled": null,
                "time_succeeded": null,
                "user": "user_001",
                "user_fee": 50
            },
            {...},
            {...}
        ]
    }
}

查询 Batch Withdrawal 对象列表

返回之前创建过 batch_withdrawal 对象的一个列表。列表是按创建时间进行排序,总是将最新的 batch_withdrawal 对象显示在最前。

请求参数
app required string 对应 app 对象的 id ,查看 如何获取App ID
page optional int 页码,默认值为 "1",取值范围:1~100000000。
per_page optional int 每页数量,默认值为 "10"。
created [ gt ] optional timestamp 创建时间大于该值,用 Unix 时间戳表示。
created [ gte ] optional timestamp 创建时间大于或等于该值,用 Unix 时间戳表示。
created [ lt ] optional timestamp 创建时间小于该值,用 Unix 时间戳表示。
created [ lte ] optional timestamp 创建时间小于或等于该值,用 Unix 时间戳表示。
status optional string 提现状态,已申请: created ,处理中: pending ,全部成功: succeeded ,全部失败: failed ,全部取消: canceled ,部分成功: partially_succeeded

返回

返回一个 batch_withdrawal 对象列表,或者一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/batch_withdrawals

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/batch_withdrawals \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1478833871" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "object": "list",
    "has_more": false,
    "url": "/v1/apps/app_1Gqj58ynP0mHeX1q/batch_withdrawals",
    "data": [
        {
            "id": "1901611151015122025",
            "object": "batch_withdrawal",
            "app": "app_1Gqj58ynP0mHeX1q",
            "created": 1478833871,
            "livemode": false,
            "amount": 80000,
            "amount_succeeded": 0,
            "amount_failed": 0,
            "amount_canceled": 0,
            "count": 3,
            "count_succeeded": 0,
            "count_failed": 0,
            "count_canceled": 0,
            "fee": 0,
            "metadata": {},
            "operation_url": "https://mapi.alipay.com/gateway.do?",
            "status": "pending",
            "source": "1801701051435464631",
            "time_finished": null,
            "user_fee": 0,
            "withdrawals": {
                "object": "list",
                "url": null,
                "has_more": false,
                "data": [
                    {
                        "id": "1701611150302360654",
                        "object": "withdrawal",
                        "app": "app_1Gqj58ynP0mHeX1q",
                        "amount": 20000,
                        "asset_transaction": "",
                        "balance_transaction": "",
                        "channel": "alipay",
                        "created": 1472648887,
                        "description": "test232description",
                        "extra": {
                            "account": "username@gmail.com",
                            "name": "姓名"
                        },
                        "failure_msg": null,
                        "fee": 200,
                        "livemode": false,
                        "metadata":{},
                        "operation_url": null,
                        "order_no": "20160829133002",
                        "source": null,
                        "status": "pending",
                        "time_canceled": null,
                        "time_succeeded": null,
                        "user": "user_001",
                        "user_fee": 50
                    },
                    {...},
                    {...}
                ]
            }
        },
        {...},
        {...}
    ]
}

Batch Withdrawal 对象相关的 Event 类型

该类型的 Event 对象会在所有包含的 withdrawal 对象提现完成后触发,包括:批量提现成功、批量提现失败、批量提现撤销以及批量提现部分成功,以 Webhooks 形式发送至客户配置的 Webhooks URL 。详情请参考 Events 事件

事件类型
batch_withdrawal.succeeded 在包含的所有的提现对象全部成功时触发。
batch_withdrawal.partially_succeeded 在包含的提现对象部分成功、部分失败时触发。
batch_withdrawal.canceled 在包含的所有的提现对象全部取消时触发。
batch_withdrawal.failed 在包含的所有的提现对象全部失败时触发。

Balance Bonuses 余额赠送

你可以请求一个新的 balance_bonus 对象向用户发起一次余额赠送。赠送成功后,用户的可用余额会增加,赠送的余额不能提现、转账,只能用于消费。

属性
id string 余额赠送对象 ID,由 Ping++ 生成。
object string 值为 "balance_bonus"。
app string 对应 app 对象的 id ,查看 如何获取App ID
created int 创建时间,用 Unix 时间戳表示。
livemode timestamp 是否是 live 模式。
paid boolean 是否已赠送。
refunded boolean 是否存在退款信息,无论退款是否成功。
order_no string 商户订单号,必须在商户系统内唯一。
amount int 赠送金额,单位为分。
amount_refunded int 已退款的赠送金额,单位为分。
time_paid int 支付成功时间,用 Unix 时间戳表示。
user string 受赠的 user 对象的 id
balance_transaction string 关联的 balance_transaction 对象的 id
description string 附加说明,最多 60 个 Unicode 字符。
metadata hash 详见 元数据

创建 Balance Bonus 对象

发起一次赠送请求时需要创建一个新的 balance_bonus 对象。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
amount required int 受赠金额,单位为分。
user required string 受赠的 user 对象的 id
order_no required string 商户订单号,必须在商户系统内唯一,64 位以内。
description optional string 附加说明,最多 60 个 Unicode 字符。
metadata optional hash 详见 元数据

返回

返回一个 balance_bonus 对象,或者一个错误,详见 错误

定义

POST https://api.pingxx.com/v1/apps/{APP_ID}/balance_bonuses

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/balance_bonuses \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1496728534" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d {
	"amount": 1000,
	"user": "test_user_001",
	"order_no": "2017071110258972"
	"description": "余额赠送描述"
}

返回示例

{
  "id": "311317071315160600000100",
  "object": "balance_bonus",
  "app": "app_1Gqj58ynP0mHeX1q",
  "created": 1496728534,
  "livemode": false,
  "paid": true,
  "refunded": false,
  "amount": 100,
  "amount_refunded": 0,
  "time_paid": 1496728594,
  "user": "user_007",
  "order_no": "2017071110258972",
  "balance_transaction": "310317060612081500000501",
  "description": "余额赠送",
  "metadata": {}
}

查询 Balance Bonus 对象

通过 balance_bonus 对象的 id 查询一个已创建的 balance_bonus 对象。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
BALANCE_BONUSES_ID required string balance_bonus 对象的 id

返回

返回一个 balance_bonus 对象,或者一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/balance_bonuses/{BALANCE_BONUSES_ID}

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/balance_bonuses/22170606180021542366 \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1496728534" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
  "id": "311317071315160600000100",
  "object": "balance_bonus",
  "app": "app_1Gqj58ynP0mHeX1q",
  "created": 1496728534,
  "livemode": false,
  "paid": true,
  "refunded": false,
  "amount": 100,
  "amount_refunded": 0,
  "time_paid": 1496728594,
  "user": "user_007",
  "order_no": "2017071110258972",
  "balance_transaction": "310317060612081500000501",
  "description": "余额赠送",
  "metadata": {}
}

查询 Balance Bonus 对象列表

返回之前创建过 balance_bonus 对象的一个列表。列表是按创建时间进行排序,总是将最新的 balance_bonus 对象显示在最前。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
user optional string 受赠的 user 对象的 id
order_no optional string 商户订单号,适配每个渠道对此参数的要求,必须在商户系统内唯一。
page optional int 页码,默认值为 "1",取值范围:1~100000000。
per_page optional int 每页数量,默认值为 "10"。
created [ gt ] optional timestamp 创建时间大于该值,用 Unix 时间戳表示。
created [ gte ] optional timestamp 创建时间大于或等于该值,用 Unix 时间戳表示。
created [ lt ] optional timestamp 创建时间小于该值,用 Unix 时间戳表示。
created [ lte ] optional timestamp 创建时间小于或等于该值,用 Unix 时间戳表示。

返回

返回一个 balance_bonus 对象列表,或者一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/balance_bonuses

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/balance_bonuses \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1496728534" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
  "object": "list",
  "url": "/v1/apps/app_1Gqj58ynP0mHeX1q/balance_bonuses",
  "has_more": true,
  "data": [
    {
      "id": "311317071315160600000100",
      "object": "balance_bonus",
      "app": "app_1Gqj58ynP0mHeX1q",
      "created": 1496728534,
      "livemode": false,
      "paid": true,
      "refunded": false,
      "amount": 100,
      "amount_refunded": 0,
      "time_paid": 1496728594,
      "user": "user_007",
      "order_no": "2017071110258972",
      "balance_transaction": "310317060612081500000501",
      "description": "余额赠送",
      "metadata": {}
    },
    {...},
    {...}
  ]
}

Balance Transfers 余额转账

通过创建 balance_transfer 对象发起用户间的余额转账。转账完成后可以调用 user 对象查询接口,查询用户的余额。转账的余额可以消费、再次转账和提现。

属性
id string 用户余额转账对象 ID,由Ping++ 生成。
object string 值为 "balance_transfer"。
app string 对应 app 对象的 id ,查看 如何获取App ID
created timestamp 创建时间,用 Unix 时间戳表示。
livemode boolean 是否是 live 模式。
status string 目前值为转账成功: succeeded
amount int 接收方收到转账的金额,单位为分。
order_no string 商户订单号,适配每个渠道对此参数的要求,必须在商户系统内唯一。
user_fee int 向发起转账的用户额外收取的手续费,单位为分。
user string 转出方的 user 对象的 id
recipient string 接收方的 user 对象的 id
user_balance_transaction string 转账关联的转出方 balance_transaction 对象的 id
recipient_balance_transaction string 转账关联的接收方 balance_transaction 对象的 id
description string 附加说明,最多 60 个 Unicode 字符。
metadata hash 详见 元数据

创建 Balance Transfer 对象

发起一次余额转账请求时需要创建一个新的 balance_transfer 对象。该接口不支持你向用户转账,如果要发起 B2C 转账,请使用 企业付款 发起,将渠道设置为余额,在企业付款完成后,会自动为你生成 balance_transfer 对象。 如果使用了余额分润,在分润结算发起后,也会自动生成 balance_transfer 对象。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
amount required int 接收方收到转账的金额,单位为分。
user required string 发送方 user 对象的 id ,该值不能为 "0"。
recipient required string 接收方 user 对象的 id
order_no optional string 商户订单号,必须在商户系统内唯一,取值范围 1~64位。
user_fee optional int 向发起转账的用户额外收取的手续费,单位为分,默认值为 "0"。
description optional string 附加说明,最多 60 个 Unicode 字符。
metadata optional hash 详见 元数据

返回

返回 balance_transfers 对象,或者返回一个错误,详见 错误

定义

POST https://api.pingxx.com/v1/apps/{APP_ID}/balance_transfers

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/balance_transfers \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1496728534" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
  "amount": 100,
  "description": "余额转账",
  "user": "user_007",
  "recipient": "user_008",
  "order_no": "2017071110259981"
}'

返回示例

{
  "id": "311117071315154300000100",
  "object": "balance_transfer",
  "app": "app_1Gqj58ynP0mHeX1q",
  "created": 1496728534,
  "livemode": false,
  "status": "succeeded",
  "amount": 1000,
  "order_no": "2017071110259981",
  "user": "user_007",
  "recipient": "user_008",
  "user_fee": 0,
  "user_balance_transaction": "310317060612081500000101",
  "recipient_balance_transaction": "310317060612081500000201",
  "description": "余额转账",
  "metadata": {}
}

查询 Balance Transfer 对象

通过 balance_transfer 对象的 id 查询一个已创建的 balance_transfer 对象。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
BALANCE_TRANSFER_ID required string balance_transfer 对象的 id

返回

返回一个 balance_transfer 对象,或者一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/balance_transfers/{BALANCE_TRANSFER_ID}

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/balance_transfers/19161008180021542366 \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1496728534" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
  "id": "311117071315154300000100",
  "object": "balance_transfer",
  "app": "app_1Gqj58ynP0mHeX1q",
  "created": 1496728534,
  "livemode": false,
  "status": "succeeded",
  "amount": 1000,
  "order_no": "2017071110259981",
  "user": "user_007",
  "recipient": "user_008",
  "user_fee": 0,
  "user_balance_transaction": "310317060612081500000101",
  "recipient_balance_transaction": "310317060612081500000201",
  "description": "余额转账",
  "metadata": {}
}

查询 Balance Transfer 对象列表

返回之前创建过 balance_transfer 对象的一个列表。列表是按创建时间进行排序,总是将最新的 balance_transfer 对象显示在最前。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
user optional string 转出方 user 对象的 id
recipient optional string 接收方 user 对象的 id
order_no optional string 商户订单号,适配每个渠道对此参数的要求,必须在商户系统内唯一。
page optional int 页码,默认值为 "1",取值范围:1~100000000。
per_page optional int 每页数量,默认值为 "10"。
created [ gt ] optional timestamp 创建时间大于该值,用 Unix 时间戳表示。
created [ gte ] optional timestamp 创建时间大于或等于该值,用 Unix 时间戳表示。
created [ lt ] optional timestamp 创建时间小于该值,用 Unix 时间戳表示。

返回

返回一个 balance_transfer 对象列表,或者一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/balance_transfers

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/balance_transfers \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1496728534" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
  "object": "list",
  "url": "/v1/apps/app_1Gqj58ynP0mHeX1q/balance_transfers",
  "has_more": true,
  "data": [
    {
      "id": "311117071315154300000100",
      "object": "balance_transfer",
      "app": "app_1Gqj58ynP0mHeX1q",
      "created": 1496728534,
      "livemode": false,
      "status": "succeeded",
      "amount": 1000,
      "order_no": "2017071110259981",
      "user": "user_007",
      "recipient": "user_008",
      "user_fee": 0,
      "user_balance_transaction": "310317060612081500000101",
      "recipient_balance_transaction": "310317060612081500000201",
      "description": "余额转账",
      "metadata": {}
    },
    {...},
    {...}
  ]
}

Balance Transactions 余额明细对象

当用户的余额账户发生充值、充值退款、提现、收到赠送、支付/收款、退款/收到退款、转账/收到转账、分润/收到分润等行为时,Ping++ 会自动为你生成 balance_transaction 对象记录用户现金账户变化的明细。

属性
id string 余额明细对象 ID,由 Ping++ 生成。
object string 值为 "balance_transaction"。
app 对应 app 对象的 id ,查看 如何获取App ID
amount int 交易金额,单位为分。
available_balance string 该笔交易发生后,用户的可用余额。
created timestamp 创建时间,用 Unix 时间戳表示。
livemode boolean 是否是 live 模式。
description string 附加说明,最多 255 个 Unicode 字符。
source string 关联对象的 ID,充值、充值退款为 recharge 对象,提现为 withdrawal 对象,赠送为 balance_bonus 对象,支付为 charge 对象,退款为 refund 对象,转账、分润结算为 balance_transfer 对象。
type string 交易类型,充值: recharge ,充值退款: recharge_refund ,充值退款失败: recharge_refund_failed ,提现申请: withdrawal ,提现失败: withdrawal_failed ,提现撤销: withdrawal_revoked ,支付/收款: payment ,退款/收到退款: payment_refund ,转账/收到转账: transfer ,赠送: receipts_extra ,分润/收到分润: royalty
user string user 对象的 id

示例对象

{
    "id": "310216111615002600000601",
    "object": "balance_transaction",
    "app": "app_1Gqj58ynP0mHeX1q",
    "amount": 100,
    "available_balance": 1000,
    "created": 1470904889,
    "description": "充值",
    "livemode": false,
    "source": "ch_2duvbLr1ivXre1uc8K9048uT",
    "type": "recharge",
    "user": "user_001"
}

查询 Balance Transaction 对象

通过 balance_transaction 对象的 id 查询一个已创建的 balance_transaction 对象。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
TXN_ID required string balance_transaction 对象的 id

返回

返回一个 balance_transaction 对象,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/balance_transactions/{TXN_ID}

请求示例

curl https://api.pingxx.com/v1/apps/{app_id}/balance_transactions/txn_14697807964587241560000001 \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "id": "310216111615002600000601",
    "object": "balance_transaction",
    "app": "app_1Gqj58ynP0mHeX1q",
    "amount": 100,
    "available_balance": 1000,
    "created": 1470904889,
    "description": "充值",
    "livemode": false,
    "source": "ch_2duvbLr1ivXre1uc8K9048uT",
    "type": "recharge",
    "user": "user_001"
}

查询 Balance Transaction 对象列表

返回之前创建过 balance_transaction 对象的一个列表。列表是按创建时间进行排序,总是将最新的 balance_transaction 对象显示在最前。

请求参数
app required string 对应 app 对象的 id ,查看 如何获取App ID
user optional string user 对象的 id
page optional int 页码,默认值为 "1",取值范围:1~100000000。
per_page optional int 每页数量,默认值为 "10"。
created [ gt ] optional timestamp 创建时间大于该值,用 Unix 时间戳表示。
created [ gte ] optional timestamp 创建时间大于或等于该值,用 Unix 时间戳表示。
created [ lt ] optional timestamp 创建时间小于该值,用 Unix 时间戳表示。
created [ lte ] optional timestamp 创建时间小于或等于该值,用 Unix 时间戳表示。
source optional string 关联对象的 ID,充值、充值退款为 recharge 对象,提现为 withdrawal 对象,赠送为 balance_bonus 对象,支付为 charge 对象,退款为 refund 对象,转账、分润结算为 balance_transfer 对象。
type optional string 交易类型,充值: recharge ,充值退款: recharge_refund ,充值退款失败: recharge_refund_failed ,提现申请: withdrawal ,提现失败: withdrawal_failed ,提现撤销: withdrawal_revoked ,支付/收款: payment ,退款/收到退款: payment_refund ,转账/收到转账: transfer ,额外受赠: receipts_extra ,分润/收到分润: royalty

返回

返回一个 balance_transaction 对象列表,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/balance_transactions

请求示例

curl https://api.pingxx.com/v1/apps/{app_id}/balance_transactions/ \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "object": "list",
    "url": "/v1/apps/{APP_ID}/balance_transactions",
    "has_more": true,
    "data": [
         {
    		"id": "310216111615002600000601",
    		"object": "balance_transaction",
    		"app": "app_1Gqj58ynP0mHeX1q",
    		"amount": 100,
    		"available_balance": 1000,
    		"created": 1470904889,
    		"description": "充值",
    		"livemode": false,
   		   "source": "ch_2duvbLr1ivXre1uc8K9048uT",
    		"type": "recharge",
    		"user": "user_001"
		  },
        {

        }
    ]
}

Orders 订单

你可以通过创建 order 对象完成一笔订单的下单和付款动作。一个 order 对象可能包含多笔(多渠道)的 charge 对象。 order 对象支持优惠券使用子商户收款分润等功能(均为可选),请参考相应的章节获取更多详情。

属性
id string 订单对象 ID,由 Ping++ 生成。
object string 值为 "order"。
created timestamp 创建时间,用 Unix 时间戳表示。
livemode boolean 是否是 live 模式。
app string 订单应用。对应 app 对象的 id ,查看 如何获取App ID
status string 目前订单支持状态。分为待支付: created 、已付款: paid 、存在退款: refunded 、已取消: canceled
paid boolean 是否已付款。当订单的已付金额大于等于应付金额( amount_paidactual_amount )时,该值变为 true
refunded boolean 是否存在退款信息,无论退款是否成功。
uid string 消费者 user 对象的 id
amount int 原始金额,单位为分。
coupon_amount int 优惠券折扣金额,单位为分。
actual_amount int 应付金额,单位为分。值为原始金额减去优惠券折扣金额( amount - coupon_amount )。
merchant_order_no string 商户订单号,适配每个渠道对此参数的要求,必须在商户系统内唯一。长度限制 8~20 位。
amount_paid int 已付金额,值为所有包含已付款的 charge 对象的 amount 总额,单位为分。
amount_refunded int 已退金额(成功退款的金额),值为所有包含有退款的 charge 对象的 amount_refunded 总额,单位为分。
currency string 3 位 ISO 货币代码,人民币为 cny
subject string 商品标题,该参数最长为 32 个 Unicode 字符。银联全渠道( upacp / upacp_wap )限制在 32 个字节;支付宝部分渠道不支持特殊字符。
body string 商品描述信息,该参数最长为 128 个 Unicode 字符。 yeepay_wap 对于该参数长度限制为 100 个 Unicode 字符;支付宝部分渠道不支持特殊字符。
client_ip ip address 发起支付请求客户端的 IP 地址,格式为 IPv4 整型,如 127.0.0.1。
time_paid timestamp 付款完成时间,用 Unix 时间戳表示。
time_expire timestamp 订单过期时间,用 Unix 时间戳表示。时间范围在订单创建后的 5 分钟到 7 天,默认值为 1 天,创建时间以 Ping++ 服务器时间为准。如果订单到达过期时间仍未完成付款,则会自动变为 canceled 状态。
coupon string 使用的 coupon 对象的 id
available_balance int 订单支付前,消费者 user 的可用余额,单位为分。
receipt_app string 收款方 app 对象的 id 。订单使用收款方应用的渠道参数进行支付。
service_app string 服务方 app 对象的 id 。表示承接该交易服务的应用,由服务方和平台确定订单的层级链都能查询到该 order 对象。
available_methods list 可使用支付渠道列表。如果收款方是子商户,会展示该子商户可使用的支付渠道。客户端可以根据此列表展示合适的支付渠道供用户选择。
charge_essentials hash 最近一次请求的支付所需的支付要素,用于客户端打开支付控件、支付页面、显示二维码等。包括 channeltransaction_nocredentialextra 等要素。
charges list 关联的 charge 对象列表,其中 charge 对象不包含 refund 对象。
description string 订单附加说明,最多 255 个 Unicode 字符。
metadata hash 详见 元数据

对象示例

{
    "id": "2001708140000017551",
    "object": "order",
    "created": 1502695388,
    "livemode": false,
    "paid": false,
    "refunded": false,
    "status": "created",
    "app": "app_1Gqj58ynP0mHeX1q",
    "uid": "user_007",
    "available_balance": 0,
    "merchant_order_no": "2017081400000006",
    "type": "purchase",
    "amount": 1000,
    "actual_amount": 800,
    "amount_refunded": 0,
    "amount_paid": 0,
    "extra_amount": 0,
    "coupon_amount": 200,
    "balance_amount": 0,
    "charge_amount": 0,
    "currency": "cny",
    "subject": "Your Subject",
    "body": "Your Body",
    "client_ip": "127.0.0.1",
    "time_paid": null,
    "time_expire": 1502781019,
    "refunds": {
        "object": "list",
        "url": "/v1/orders/2001708140000017551/refunds",
        "has_more": false,
        "data": []
    },
    "charge": null,
    "balance_transaction": null,
    "coupon": "300317081415225500002001",
    "description": null,
    "metadata": {},
    "charge_essentials": {},
    "user_fee": 0,
    "user_from": null,
    "receipt_app": "app_1Gqj58ynP0mHeX1q",
    "service_app": "app_1Gqj58ynP0mHeX1q",
    "available_methods": [
        "balance"
    ],
    "charges": {
        "object": "list",
        "url": "/v1/charges",
        "has_more": false,
        "data": []
    }
}

创建 Order 对象

通过创建 order 对象完成一笔订单的下单动作(确认一笔订单的付款信息),下单时用户可以使用优惠券对订单折扣,下单完成后该订单状态会变成 created 状态。当用户被禁用时,该请求会被拒绝。

请求参数
app required string 订单应用。对应 app 对象的 id ,查看 如何获取App ID
merchant_order_no required string 商户订单号,适配每个渠道对此参数的要求,必须在商户系统内唯一。长度限制 8~20 位。
amount required int 原始金额,单位为分。
currency required string 3 位 ISO 货币代码,人民币为 cny
client_ip required string 发起支付请求客户端的 IP 地址,格式为 IPv4 整型,如 127.0.0.1。
subject required string 商品标题,该参数最长为 32 个 Unicode 字符。银联全渠道( upacp / upacp_wap )限制在 32 个字节;支付宝部分渠道不支持特殊字符。
body required string 商品描述信息,该参数最长为 128 个 Unicode 字符。 yeepay_wap 对于该参数长度限制为 100 个 Unicode 字符;支付宝部分渠道不支持特殊字符。
uid optional string user 对象的 id ,默认值为 "0"。若后续需要使用 balance 渠道进行支付,则此参数必传,且 balance 的 extra 参数 user 值无需传。
coupon optional string 使用的 coupon 对象的 id
actual_amount optional int 应付金额,单位为分。值为原始金额减去优惠券折扣金额( amount - coupon_amount )。传入该值则校验是否和 Ping++ 计算出的应付金额一致,不传则不校验。
time_expire optional timestamp 订单过期时间,用 Unix 时间戳表示。时间范围在订单创建后的 5 分钟到 7 天,默认值为 1 天,创建时间以 Ping++ 服务器时间为准。如果订单到达过期时间仍未完成付款,则会自动变为 canceled 状态。
receipt_app optional string 收款方 app 对象的 id ,默认为订单应用。订单使用收款方应用的渠道参数进行支付。
service_app optional string 服务方 app 对象的 id ,默认为订单应用。表示承接该交易服务的应用,由服务方和平台确定订单的层级链都能查询到该 order 对象。
royalty_users optional list 分润的用户信息列表,默认为[],不分润,具体 hash 如下表。
royalty_template optional string 使用的 royalty_template 对象的 id 。该参数与 royalty_users 同时传时将会被忽略。
description optional string 附加说明,最多 255 个 Unicode 字符。
metadata optional hash 详见 元数据
分润的用户信息列表(royalty_users)参数说明
user required string 分润的 user 对象 id。
amount required int 分润的金额,单位为分。

返回

返回一个 order 对象,或者返回一个错误,详见 错误

定义

POST https://api.pingxx.com/v1/orders

请求示例

curl https://api.pingxx.com/v1/orders \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Content-Type: application/json" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:
-d '{
 "app": "app_1Gqj58ynP0mHeX1q",
  "uid": "user_007",
  "merchant_order_no": "2017081400000006",
  "coupon": "300317081415225500002001",
  "amount": 1000,
  "client_ip": "127.0.0.1",
  "currency": "cny",
  "subject": "Your Subject",
  "body": "Your Body",
  "time_expire": 1502781019
}'

返回示例

{
    "id": "2001708140000017551",
    "object": "order",
    "created": 1502695388,
    "livemode": false,
    "paid": false,
    "refunded": false,
    "status": "created",
    "app": "app_1Gqj58ynP0mHeX1q",
    "uid": "user_007",
    "available_balance": 0,
    "merchant_order_no": "2017081400000006",
    "type": "purchase",
    "amount": 1000,
    "actual_amount": 800,
    "amount_refunded": 0,
    "amount_paid": 0,
    "extra_amount": 0,
    "coupon_amount": 200,
    "balance_amount": 0,
    "charge_amount": 0,
    "currency": "cny",
    "subject": "Your Subject",
    "body": "Your Body",
    "client_ip": "127.0.0.1",
    "time_paid": null,
    "time_expire": 1502781019,
    "refunds": {
        "object": "list",
        "url": "/v1/orders/2001708140000017551/refunds",
        "has_more": false,
        "data": []
    },
    "charge": null,
    "balance_transaction": null,
    "coupon": "300317081415225500002001",
    "description": null,
    "metadata": {},
    "charge_essentials": {},
    "user_fee": 0,
    "user_from": null,
    "receipt_app": "app_1Gqj58ynP0mHeX1q",
    "service_app": "app_1Gqj58ynP0mHeX1q",
    "available_methods": [
        "balance"
    ],
    "charges": {
        "object": "list",
        "url": "/v1/charges",
        "has_more": false,
        "data": []
    }
}

支付 Order 对象

通过该接口对待支付的 order 对象发起一次支付请求,每次请求时需指定用户付款的支付渠道。可以通过多次调用切换付款的渠道,同时生成多个 charge 对象。如果使用测试模式的 API Key,则不会发生真实交易。订单付款完成后,会发送 Webhooks 通知。

请求参数
ORDER_ID required string Ping++ 返回的 order 对象的 id ,用于商品订单查询、退款。
charge_amount required int 支付金额,必须和 order 对象中的 actual_amount 值相同。
channel optional string 支付渠道。参考 支付渠道属性值 。除此之外,还支持使用自定义渠道 custom,该渠道不需要真实付款,并同步返回成功结果。
extra optional hash 特定渠道发起交易时需要的额外参数,以及部分渠道支付成功返回的额外参数,详细参考 支付渠道 extra 参数说明
charge_order_no optional string 支付使用的商户订单号,默认使用订单对象中的商户订单号。当商户订单号在渠道被使用时,需更换新的商户订单号。
time_expire optional timestamp 支付过期时间,用 Unix 时间戳表示。时间范围在支付创建后的 5 分钟到 24 小时,创建时间以 Ping++ 服务器时间为准。默认值为订单过期时间或渠道支持的最大过期时间中较小的那一个,但不会超过 24 小时。

返回

返回一个 order 对象,或者返回一个错误,详见 错误

定义

POST https://api.pingxx.com/v1/orders/{ORDER_ID}/pay

请求示例

curl https://api.pingxx.com/v1/orders/2001608270000004428/pay \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Content-Type: application/json" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:
-d '{
	"channel": "alipay_qr",
  	"charge_amount": 800,
  	"balance_amount":0
  	}'

返回示例

{
    "id": "2001708140000017551",
    "object": "order",
    "created": 1502695388,
    "livemode": false,
    "paid": false,
    "refunded": false,
    "status": "created",
    "app": "app_1Gqj58ynP0mHeX1q",
    "uid": "user_007",
    "available_balance": 0,
    "merchant_order_no": "2017081400000006",
    "type": "purchase",
    "amount": 1000,
    "actual_amount": 800,
    "amount_refunded": 0,
    "amount_paid": 0,
    "extra_amount": 0,
    "coupon_amount": 200,
    "balance_amount": 0,
    "charge_amount": 800,
    "currency": "cny",
    "subject": "Your Subject",
    "body": "Your Body",
    "client_ip": "127.0.0.1",
    "time_paid": null,
    "time_expire": 1502781019,
    "refunds": {
        "object": "list",
        "url": "/v1/orders/2001708140000017551/refunds",
        "has_more": false,
        "data": []
    },
    "charge": "ch_1Kyn50DyjXbHbvnv5SGK4qDK",
    "balance_transaction": null,
    "coupon": "300317081415225500002001",
    "description": "",
    "metadata": {},
    "charge_essentials": {
        "channel": "alipay_qr",
        "transaction_no": null,
        "failure_code": null,
        "failure_msg": null,
        "credential": {
            "object": "credential",
            "alipay_qr": "http://sissi.pingxx.com/mock.php?ch_id=ch_1Kyn50DyjXbHbvnv5SGK4qDK&channel=alipay_qr"
        },
        "extra": {}
    },
    "user_fee": 0,
    "user_from": null,
    "receipt_app": "app_1Gqj58ynP0mHeX1q",
    "service_app": "app_1Gqj58ynP0mHeX1q",
    "available_methods": [
        "balance"
    ],
    "charges": {
        "object": "list",
        "url": "/v1/charges",
        "has_more": false,
        "data": [
            {
                "id": "ch_1Kyn50DyjXbHbvnv5SGK4qDK",
                "object": "charge",
                "created": 1502695440,
                "livemode": false,
                "paid": false,
                "refunded": false,
                "reversed": false,
                "app": "app_1Gqj58ynP0mHeX1q",
                "channel": "alipay_qr",
                "order_no": "2017081400000006",
                "client_ip": "127.0.0.1",
                "amount": 800,
                "amount_settle": 800,
                "currency": "cny",
                "subject": "Your Subject",
                "body": "Your Body",
                "extra": {},
                "time_paid": null,
                "time_expire": 1502781019,
                "time_settle": null,
                "transaction_no": null,
                "refunds": null,
                "amount_refunded": 0,
                "failure_code": null,
                "failure_msg": null,
                "metadata": {},
                "credential": {
                    "object": "credential",
                    "alipay_qr": "http://sissi.pingxx.com/mock.php?ch_id=ch_1Kyn50DyjXbHbvnv5SGK4qDK&channel=alipay_qr"
                },
                "description": null
            }
        ]
    }
}

取消 Order 对象

你可以对待支付状态的 order 对象进行取消动作,订单被取消后不能再次发起支付。订单在到达过期时间时仍未完成付款,Ping++ 会自动改变订单状态为已取消。订单如果使用优惠券,在取消后,会自动退回优惠券。

请求参数
ORDER_ID required string Ping++ 返回的 order 对象的 id ,用于商品订单查询、退款。
status required string 值填 canceled ,表示更新 order 对象的状态。
user optional string user 对象的 id ,传入该参数以检查是否和订单的 user 值一致,默认不检查。

返回

返回一个 order 对象,或者返回一个错误,详见 错误

定义

PUT https://api.pingxx.com/v1/orders/{ORDER_ID}

请求示例

curl https://api.pingxx.com/v1/orders/2001608270000004428 \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:
-d '
	{
	"status": "canceled",
  	"user": "user_007"
  	}'

返回示例

{
    "id": "2001708140000017551",
    "object": "order",
    "created": 1502695388,
    "livemode": false,
    "paid": false,
    "refunded": false,
    "status": "canceled",
    "app": "app_1Gqj58ynP0mHeX1q",
    "uid": "user_007",
    "available_balance": 0,
    "merchant_order_no": "2017081400000006",
    "type": "purchase",
    "amount": 1000,
    "actual_amount": 800,
    "amount_refunded": 0,
    "amount_paid": 0,
    "extra_amount": 0,
    "coupon_amount": 200,
    "balance_amount": 0,
    "charge_amount": 800,
    "currency": "cny",
    "subject": "Your Subject",
    "body": "Your Body",
    "client_ip": "127.0.0.1",
    "time_paid": null,
    "time_expire": 1502781019,
    "refunds": {
        "object": "list",
        "url": "/v1/orders/2001708140000017551/refunds",
        "has_more": false,
        "data": []
    },
    "charge": "ch_1Kyn50DyjXbHbvnv5SGK4qDK",
    "balance_transaction": null,
    "coupon": "300317081415225500002001",
    "description": "",
    "metadata": {},
    "charge_essentials": {},
    "user_fee": 0,
    "user_from": null,
    "receipt_app": "app_1Gqj58ynP0mHeX1q",
    "service_app": "app_1Gqj58ynP0mHeX1q",
    "available_methods": [],
    "charges": {
        "object": "list",
        "url": "/v1/charges",
        "has_more": false,
        "data": [
            {
                "id": "ch_1Kyn50DyjXbHbvnv5SGK4qDK",
                "object": "charge",
                "created": 1502695440,
                "livemode": false,
                "paid": false,
                "refunded": false,
                "reversed": false,
                "app": "app_1Gqj58ynP0mHeX1q",
                "channel": "alipay_qr",
                "order_no": "2017081400000006",
                "client_ip": "127.0.0.1",
                "amount": 800,
                "amount_settle": 800,
                "currency": "cny",
                "subject": "Your Subject",
                "body": "Your Body",
                "extra": {},
                "time_paid": null,
                "time_expire": 1502781019,
                "time_settle": null,
                "transaction_no": null,
                "refunds": null,
                "amount_refunded": 0,
                "failure_code": null,
                "failure_msg": null,
                "metadata": {},
                "credential": {},
                "description": null
            }
        ]
    }
}

查询 Order 对象

通过 order 对象的 id 查询一个已创建的 order 对象。

请求参数
ORDER_ID required string order 对象的 id

返回

返回一个 order 对象,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/orders/{ORDER_ID}/

请求示例

curl https://api.pingxx.com/v1/orders/2001608270000004428/ \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "id": "2001708140000017551",
    "object": "order",
    "created": 1502695388,
    "livemode": false,
    "paid": false,
    "refunded": false,
    "status": "canceled",
    "app": "app_1Gqj58ynP0mHeX1q",
    "uid": "user_007",
    "available_balance": 0,
    "merchant_order_no": "2017081400000006",
    "type": "purchase",
    "amount": 1000,
    "actual_amount": 800,
    "amount_refunded": 0,
    "amount_paid": 0,
    "extra_amount": 0,
    "coupon_amount": 200,
    "balance_amount": 0,
    "charge_amount": 800,
    "currency": "cny",
    "subject": "Your Subject",
    "body": "Your Body",
    "client_ip": "127.0.0.1",
    "time_paid": null,
    "time_expire": 1502781019,
    "refunds": {
        "object": "list",
        "url": "/v1/orders/2001708140000017551/refunds",
        "has_more": false,
        "data": []
    },
    "charge": "ch_1Kyn50DyjXbHbvnv5SGK4qDK",
    "balance_transaction": null,
    "coupon": "300317081415225500002001",
    "description": "",
    "metadata": {},
    "charge_essentials": {},
    "user_fee": 0,
    "user_from": null,
    "receipt_app": "app_1Gqj58ynP0mHeX1q",
    "service_app": "app_1Gqj58ynP0mHeX1q",
    "available_methods": [
        "balance"
    ],
    "charges": {
        "object": "list",
        "url": "/v1/charges",
        "has_more": false,
        "data": [
            {
                "id": "ch_1Kyn50DyjXbHbvnv5SGK4qDK",
                "object": "charge",
                "created": 1502695440,
                "livemode": false,
                "paid": false,
                "refunded": false,
                "reversed": false,
                "app": "app_1Gqj58ynP0mHeX1q",
                "channel": "alipay_qr",
                "order_no": "2017081400000006",
                "client_ip": "127.0.0.1",
                "amount": 800,
                "amount_settle": 800,
                "currency": "cny",
                "subject": "Your Subject",
                "body": "Your Body",
                "extra": {},
                "time_paid": null,
                "time_expire": 1502781019,
                "time_settle": null,
                "transaction_no": null,
                "refunds": null,
                "amount_refunded": 0,
                "failure_code": null,
                "failure_msg": null,
                "metadata": {},
                "credential": {},
                "description": null
            }
        ]
    }
}

查询 Order 对象列表

返回之前创建过 order对象的一个列表。列表是按创建时间进行排序,总是将最新的 order 对象显示在最前。

请求参数
app required string 对应 app 对象的 id ,查看 如何获取App ID
uid optional string user 对象的 id
receipt_app optional string 收款方 app 对象的 id 。订单使用收款方应用的渠道参数进行支付。
service_app optional string 服务方 app 对象的 id 。表示承接该交易服务的应用,由服务方和平台确定订单的层级链都能查询到该 order 对象。
paid optional boolean 是否付款。
refunded optional boolean 是否存在退款信息,无论退款是否成功。
canceled optional int order 对象的 status 是否为 canceled ,"0":未取消,"1":已取消。
page optional int 页码,默认值为 "1",取值范围(1~100000000)。
per_page optional int 每页数量,默认值为 "20",取值范围(1~100)。
created [ gt ] optional timestamp 大于 charge 对象的创建时间,用 Unix 时间戳表示。
created [ gte ] optional timestamp 大于或等于 charge 对象的创建时间,用 Unix 时间戳表示。
created [ lt ] optional timestamp 小于 charge 对象的创建时间,用 Unix 时间戳表示。
created [ lte ] optional timestamp 小于或等于 charge 对象的创建时间,用 Unix 时间戳表示。

返回

返回一个 order 对象列表,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/orders/

请求示例

curl https://api.pingxx.com/v1/orders/ \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "object": "list",
    "url": "/v1/orders",
    "has_more": false,
    "data": [
        {
            "id": "2001708140000017551",
            "object": "order",
            "created": 1502695388,
            "livemode": false,
            "paid": false,
            "refunded": false,
            "status": "canceled",
            "app": "app_1Gqj58ynP0mHeX1q",
            "uid": "user_007",
            "available_balance": 0,
            "merchant_order_no": "2017081400000006",
            "type": "purchase",
            "amount": 1000,
            "actual_amount": 800,
            "amount_refunded": 0,
            "amount_paid": 0,
            "extra_amount": 0,
            "coupon_amount": 200,
            "balance_amount": 0,
            "charge_amount": 800,
            "currency": "cny",
            "subject": "Your Subject",
            "body": "Your Body",
            "client_ip": "127.0.0.1",
            "time_paid": null,
            "time_expire": 1502781019,
            "refunds": {
                "object": "list",
                "url": "/v1/orders/2001708140000017551/refunds",
                "has_more": false,
                "data": []
            },
            "charge": "ch_1Kyn50DyjXbHbvnv5SGK4qDK",
            "balance_transaction": null,
            "coupon": "300317081415225500002001",
            "description": null,
            "metadata": null,
            "charge_essentials": {},
            "user_fee": 0,
            "user_from": null,
            "receipt_app": "app_1Gqj58ynP0mHeX1q",
            "service_app": "app_1Gqj58ynP0mHeX1q",
            "available_methods": [],
            "charges": {
                "object": "list",
                "url": "/v1/charges",
                "has_more": false,
                "data": [
                    {
                        "id": "ch_1Kyn50DyjXbHbvnv5SGK4qDK",
                        "object": "charge",
                        "created": 1502695440,
                        "livemode": false,
                        "paid": false,
                        "refunded": false,
                        "reversed": false,
                        "app": "app_1Gqj58ynP0mHeX1q",
                        "channel": "alipay_qr",
                        "order_no": "2017081400000006",
                        "client_ip": "127.0.0.1",
                        "amount": 800,
                        "amount_settle": 800,
                        "currency": "cny",
                        "subject": "Your Subject",
                        "body": "Your Body",
                        "extra": {},
                        "time_paid": null,
                        "time_expire": 1502781019,
                        "time_settle": null,
                        "transaction_no": null,
                        "refunds": null,
                        "amount_refunded": 0,
                        "failure_code": null,
                        "failure_msg": null,
                        "metadata": {},
                        "credential": {
                            "object": "credential",
                            "alipay_qr": "http://sissi.pingxx.com/mock.php?ch_id=ch_1Kyn50DyjXbHbvnv5SGK4qDK&channel=alipay_qr"
                        },
                        "description": null
                    }
                ]
            }
        },
        {
            "id": "2001708140000016421",
            "object": "order",
            "created": 1502695222,
            "livemode": false,
            "paid": false,
            "refunded": false,
            "status": 0,
            "app": "app_1Gqj58ynP0mHeX1q",
            "uid": "user_007",
            "available_balance": 0,
            "merchant_order_no": "20170814000000006",
            "type": "purchase",
            "amount": 1000,
            "actual_amount": 990,
            "amount_refunded": 0,
            "amount_paid": 0,
            "extra_amount": 0,
            "coupon_amount": 10,
            "balance_amount": 0,
            "charge_amount": 0,
            "currency": "cny",
            "subject": "Your Subject",
            "body": "Your Body",
            "client_ip": "127.0.0.1",
            "time_paid": null,
            "time_expire": 1502781019,
            "refunds": {
                "object": "list",
                "url": "/v1/orders/2001708140000016421/refunds",
                "has_more": false,
                "data": []
            },
            "charge": null,
            "balance_transaction": null,
            "coupon": "300317081415200100001501",
            "description": null,
            "metadata": null,
            "charge_essentials": {},
            "user_fee": 0,
            "user_from": null,
            "receipt_app": "app_1Gqj58ynP0mHeX1q",
            "service_app": "app_1Gqj58ynP0mHeX1q",
            "available_methods": [],
            "charges": {
                "object": "list",
                "url": "/v1/charges",
                "has_more": false,
                "data": []
            }
        },
        {
            "id": "2001708140000015581",
            "object": "order",
            "created": 1502695142,
            "livemode": false,
            "paid": false,
            "refunded": false,
            "status": 0,
            "app": "app_1Gqj58ynP0mHeX1q",
            "uid": "user_007",
            "available_balance": 0,
            "merchant_order_no": "20170814000000001",
            "type": "purchase",
            "amount": 1000,
            "actual_amount": 990,
            "amount_refunded": 0,
            "amount_paid": 0,
            "extra_amount": 0,
            "coupon_amount": 10,
            "balance_amount": 0,
            "charge_amount": 0,
            "currency": "cny",
            "subject": "Your Subject",
            "body": "Your Body",
            "client_ip": "127.0.0.1",
            "time_paid": null,
            "time_expire": 1502781019,
            "refunds": {
                "object": "list",
                "url": "/v1/orders/2001708140000015581/refunds",
                "has_more": false,
                "data": []
            },
            "charge": null,
            "balance_transaction": null,
            "coupon": "300317081415184800001001",
            "description": null,
            "metadata": null,
            "charge_essentials": {},
            "user_fee": 0,
            "user_from": null,
            "receipt_app": "app_1Gqj58ynP0mHeX1q",
            "service_app": "app_1Gqj58ynP0mHeX1q",
            "available_methods": [],
            "charges": {
                "object": "list",
                "url": "/v1/charges",
                "has_more": false,
                "data": []
            }
        },
        {...},
        {...}
    ]
}

查询 Order 中的 Charge 对象

通过 order 中的charge 对象的 id 查询一个已创建的 charge 对象。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
ORDER_ID required string order 对象的 id
CHARGE_ID required string charge 对象的 id

返回

返回一个 charge 对象,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/orders/{ORDER_ID}/charges/{CHARGE_ID}

请求示例

curl https://api.pingxx.com/v1/orders/2001608270000004421/charges/ch_mPGm1KOGG844eLWvDOfHWvvD \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1496728534" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "id": "ch_1Kyn50DyjXbHbvnv5SGK4qDK",
    "object": "charge",
    "created": 1502695440,
    "livemode": false,
    "paid": false,
    "refunded": false,
    "reversed": false,
    "app": "app_1Gqj58ynP0mHeX1q",
    "channel": "alipay_qr",
    "order_no": "2017081400000006",
    "client_ip": "127.0.0.1",
    "amount": 800,
    "amount_settle": 800,
    "currency": "cny",
    "subject": "Your Subject",
    "body": "Your Body",
    "extra": {},
    "time_paid": null,
    "time_expire": 1502781019,
    "time_settle": null,
    "transaction_no": null,
    "refunds": {
        "object": "list",
        "url": "/v1/charges/ch_1Kyn50DyjXbHbvnv5SGK4qDK/refunds",
        "has_more": false,
        "data": []
    },
    "amount_refunded": 0,
    "failure_code": null,
    "failure_msg": null,
    "metadata": {},
    "credential": {
        "object": "credential",
        "alipay_qr": "http://sissi.pingxx.com/mock.php?ch_id=ch_1Kyn50DyjXbHbvnv5SGK4qDK&channel=alipay_qr"
    },
    "description": null
}

查询 Order 中的 Charge 对象列表

返回之前通过 order 对象创建过 charge 对象的一个列表。列表是按创建时间进行排序,总是将最新的 charge 对象显示在最前。

请求参数
ORDER_ID required integer order 对象的 id
channel optional string 支付渠道。参考 支付渠道属性值
paid optional boolean 是否已付款。
refunded optional boolean 是否存在退款信息,无论退款是否成功。
page optional integer 页码,取值范围:1~100000000。默认为 "1"。
per_page optional integer 每页数量,取值范围:1~100,默认为 "10"。

返回

返回一个 charge 对象列表,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/orders/{ORDER_ID}/charges

请求示例

curl https://api.pingxx.com/v1/orders/2001608270000004421/charges \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1496728534" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "object": "list",
    "url": "/v1/charges",
    "has_more": false,
    "data": [
        {
            "id": "ch_1Kyn50DyjXbHbvnv5SGK4qDK",
            "object": "charge",
            "created": 1502695440,
            "livemode": false,
            "paid": false,
            "refunded": false,
            "reversed": false,
            "app": "app_1Gqj58ynP0mHeX1q",
            "channel": "alipay_qr",
            "order_no": "2017081400000006",
            "client_ip": "127.0.0.1",
            "amount": 800,
            "amount_settle": 800,
            "currency": "cny",
            "subject": "Your Subject",
            "body": "Your Body",
            "extra": {},
            "time_paid": null,
            "time_expire": 1502781019,
            "time_settle": null,
            "transaction_no": null,
            "refunds": null,
            "amount_refunded": 0,
            "failure_code": null,
            "failure_msg": null,
            "metadata": {},
            "credential": {
                "object": "credential",
                "alipay_qr": "http://sissi.pingxx.com/mock.php?ch_id=ch_1Kyn50DyjXbHbvnv5SGK4qDK&channel=alipay_qr"
            },
            "description": null
        }
    ]
}

Order 对象相关的事件类型

该类型的 Event 对象会在 order 对象订单付款完成后触发,以 Webhooks 形式发送至客户配置的 Webhooks URL 。详情请参考 Events 事件。

事件类型
order.succeeded 商品订单对象,订单付款完成时触发。

订单 Refund 退款

通过订单退款接口对已经支付的 order 对象进行退款。

注意:用户在使用订单时,可能会出现以下异常情况,你需要根据实际情况进行退款处理:

  • 订单在取消后完成了付款(例如打开支付宝控件后,主动/超时取消订单后,在控件完成付款)。此时 order 对象的 status 值为 canceledpaid 值为 trueamount_paid 等于 actual_amount
  • 用户在多个渠道同时完成了付款(例如:打开支付宝控件后,再打开微信控件,然后在双方同时支付完成)。此时 order 对象中的 amount_paid 大于 actual_amount

属性详见 退款

对象示例

{
  "id": "re_y1u944PmfnrTHyvnL0nD0iD1",
  "object": "refund",
  "order_no": "y1u944PmfnrTHyvnL0nD0iD1",
  "amount": 9,
  "created": 1409634160,
  "succeed": true,
  "status": "succeeded",
  "time_succeed": 1409634192,
  "description": "Refund Description",
  "failure_code": null,
  "failure_msg": null,
  "metadata": {},
  "charge": "ch_L8qn10mLmr1GS8e5OODmHaL4",
  "charge_order_no": "123456789",
  "transaction_no": "2004450349201512090096425284"
}

创建订单 Refund 对象

通过发起一次退款请求创建一个新的 refund 对象,只能对已经发生付款并且没有全额退款的 order 对象发起退款。当进行全额退款之前,可以进行多次退款,直至全额退款。每次退款成功后,会发送 Webhooks 通知。

订单退款支持以下功能:

  • 对包含单个 charge 进行部分或全额退款。
  • 对包含所有的 charge 进行全额退款。
  • 如果订单使用优惠券,且优惠券模板设置全额退款时退回,则全额退款时自动退还优惠券。
  • 如果订单包含分润信息,则可以设置退分润信息(使用分润模板时,不需要设置,按模板规则生效)。
请求参数
ORDER_ID required string 需要退款的 order 对象的 id
charge optional string 需要退款的 charge 对象的 id ,不填表示对所有包含的 charge 对象全额退款。
charge_amount optional int 退款金额,单位分。必须小于等于可退款金额,默认为全额退款。仅当填写 charge 参数时有效,表示对此 charge 对象进行退款的金额。
description required string 附加说明,最多 255 个 Unicode 字符。
refund_mode optional string 退款方式。原路退回: to_source ,退至余额: to_balance 。默认为原路返回。如果对渠道为 balancecharge 对象退款,两者效果相同。
funding_source optional string 微信退款资金来源。取值范围: unsettled_funds :使用未结算资金退款; recharge_funds :使用可用余额退款。注:默认值 unsettled_funds ,该参数仅适用于所有微信渠道,包括 wx , wx_pub , wx_pub_qr , wx_lite , wx_wap 五个渠道;该参数仅在请求退款,传入该字段时返回。
royalty_users optional list 退分润的用户信息列表。不填默认退还所有可退分润,否则需要填写所有分润的用户信息。使用分润模板的订单不需要填写此参数。具体可参考下表。
metadata optional hash 详见 元数据
royalty_users 列表元素参数说明
user required string 退分润的 user 对象的 id
amount optional int 退分润的金额,单位为分;不退分润时填 "0"。 默认退还所有可退分润。

返回

返回一个 order 对象,或者返回一个错误,详见 错误

定义

POST https://api.pingxx.com/v1/orders/{ORDER_ID}/order_refunds

请求示例

curl https://api.pingxx.com/v1/orders/2111608270000005209/order_refunds \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:
-d '{
    "description":"test-refund"
}'

返回示例

{
  "object": "list",
  "url": "/v1/orders/2001608270000004421/order_refunds",
  "has_more": false,
  "data": [
    {
      "id": "re_y1u944PmfnrTHyvnL0nD0iD1",
      "object": "refund",
      "order_no": "y1u944PmfnrTHyvnL0nD0iD1",
      "amount": 800,
      "created": 1499930518,
      "succeed": true,
      "status": "succeeded",
      "time_succeed": 1499930518,
      "description": "Refund Description",
      "failure_code": null,
      "failure_msg": null,
      "metadata": {},
      "charge": "ch_8SCSCCn90ir1bb54m5fjbnX5",
      "charge_order_no": "2017071102122327",
      "transaction_no": "2004450349201512090096425284",
      "extra": {}
    }
  ]
}

查询订单 Refund 对象

通过订单 refund 对象的 id 查询一个已创建的 refund 对象。

请求参数
ORDER_ID required string order 对象的 id
REFUND_ID required string refund 对象的 id

返回

返回一个 refund 退款对象,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/orders/{ORDER_ID}/refunds/{REFUND_ID}

请求示例

curl https://api.pingxx.com/v1/orders/2111608270000005209/refunds/2001608270000004421 \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "id": 2111608270000005209,
    "object": "order_refund",
    "order": "2001608270000004421",
    "app": "app_1Gqj58ynP0mHeX1q",
    "uid": "user_002",
    "merchant_order_no": "88888888888",
    "amount": 10,
    "coupon_amount": 20,
    "balance_amount": 10,
    "charge_amount": 0,
    "coupon": "300316082514255200000900",
    "balance_transaction": "310216082700270000001101",
    "charge_refund": null,
    "status": "succeeded",
    "created": 1472229138,
    "time_succeed": 1472229338,
    "description": "test-refund",
    "metadata": {
    },
    "extra": {
    },
    "refund_mode": "to_source"
}

查询订单 Refund 对象列表

返回之前创建过订单 refund 对象的一个列表。列表是按创建时间进行排序,总是将最新的订单 refund 对象显示在最前。

请求参数
ORDER_ID required string 需要查询的 order 对象的 id
page optional int 页码,默认值为 "1",取值范围(1~100000000)。
per_page optional int 每页数量,默认值为 "10",取值范围(1~100)。
created [ gt ] optional timestamp 创建时间大于该值,用 Unix 时间戳表示。
created [ gte ] optional timestamp 创建时间大于或等于该值,用 Unix 时间戳表示。
created [ lt ] optional timestamp 创建时间小于该值,用 Unix 时间戳表示。
created [ lte ] optional timestamp 创建时间小于或等于该值,用 Unix 时间戳表示。
status optional int 退款状态,处理中: pending ,成功: succeeded ,失败: failed

返回

返回一个 refund 对象列表,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/orders/{ORDER_ID}/refunds

请求示例

curl https://api.pingxx.com/v1/orders/2111608270000005209/refunds \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
  "object": "list",
  "url": "/v1/charges/ch_L8qn10mLmr1GS8e5OODmHaL4/refunds",
  "has_more": false,
  "data": [
    {
      "id": "re_TmbvDKHiXLCSG0mnj9jnDyjA",
      "object": "refund",
      "order_no": "TmbvDKHiXLCSG0mnj9jnDyjA",
      "amount": 100,
      "created": 1410835214,
      "succeed": true,
      "status": "succeeded",
      "time_succeed": 1410835652,
      "description": "Refund Description",
      "failure_code": null,
      "failure_msg": null,
      "metadata": {},
      "charge": "ch_L8qn10mLmr1GS8e5OODmHaL4",
      "charge_order_no": "123456789",
      "transaction_no": "2004450349201512090096425284"
    },
    {...},
    {...}
  ]
}

Coupon Templates 优惠券模板

在向用户发放优惠券之前,需要通过 coupon_template 对象创建优惠券模板(领取中心的"优惠券"),优惠券模板记录了优惠券的折扣规则和有效期等信息。

属性
id string 优惠券模板对象 ID,由 Ping++ 生成。
object string 值为 coupon_template
app string 对应 app 对象的 id ,查看 如何获取App ID
created int 优惠券模板创建时间,用 Unix 时间戳表示。
livemode boolean 是否处于 live 模式。
name string 优惠券模板名称。
type int 优惠券模板的类型。值包括 "1":现金券、"2":折扣券。
amount_off int 折扣金额,现金券类型下生效。
percent_off int 折扣券类型下的折扣百分比, 折扣券类型下生效。例如值为 "20" 表示 8 折,值为 "100" 表示免费。
amount_available int 订单金额大于等于该值时,优惠券有效(用于设置满减券)。"0" 表示无限制。
times_circulated int 优惠券生成数量。
times_redeemed int 优惠券核销数量。
max_circulation int 优惠券最大生成数量,当已生成数量达到最大值时,不能再生成优惠券;默认值为 null ,表示无限制。
expiration hash 通过该优惠券模板创建的优惠券有效期规则,详细请参考下方 expiration 属性说明。
refundable boolean 订单全额退款时是否退还优惠券。
metadata hash 详见 元数据
expiration 属性
time_start string 优惠券可用的开始时间,用 Unix 时间戳表示。
time_end string 优惠券可用的结束时间,用 Unix 时间戳表示。
duration int 优惠券创建后的过期时间,单位为秒。不能和 time_starttime_end 同时使用。

示例对象

{
   "id": "300116082415452100000700",
   "object": "coupon_template",
   "app": "APP_ID",
   "amount_available": 10000,
   "amount_off": 25,
   "created": 1470904889,
   "expiration": null,
   "livemode": false,
   "max_circulation": 1000,
   "metadata": {
   },
   "name": "25OFF",
   "percent_off": null,
   "refundable": true,
   "times_circulated": 0,
   "times_redeemed": 0,
   "type": 1
}

创建 Coupon Template 对象

调用该接口创建一个 coupon_template 对象。优惠券模板不能直接使用,需要根据模板在用户下创建优惠券后在订单中使用。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
type required int 优惠券模板的类型。值包括 "1":现金券、"2":折扣券。
name optional string 优惠券模板名称,1~64 位。
amount_off optional int 折扣金额,现金券类型下必传。取值范围 1~1000000000。
percent_off optional int 折扣券类型下的折扣百分比, 折扣券类型下生效。取值范围 1~100。例如值为 "20" 表示 8 折,值为 "100" 表示免费。
amount_available optional int 订单金额大于等于该值时,优惠券有效(用于设置满减券)。取值范围 0~1000000000。默认值为 "0",表示无限制。
max_circulation optional int 优惠券最大生成数量,当已生成数量达到最大值时,不能再生成优惠券。默认值为 null ,表示无限制。
metadata optional hash 详见 元数据
expiration optional hash 通过该优惠券模板创建的优惠券有效期规则,详细请参考下方 expiration 参数说明。
refundable optional bool 订单全额退款时是否退还优惠券。默认值为 true
expiration 参数说明
time_start optional string 优惠券可用的开始时间,用 Unix 时间戳表示。
time_end optional string 优惠券可用的结束时间,用 Unix 时间戳表示。
duration optional int 优惠券创建后的过期时间,单位为秒。不能和 time_starttime_end 同时使用。

返回

返回一个 coupon_template 对象,或者返回一个错误,详见 错误

定义

POST https://api.pingxx.com/v1/apps/{APP_ID}/coupon_templates

请求示例

curl https://api.pingxx.com/v1/apps/{APP_ID}/coupon_templates \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:
-d '{
    "name": "25OFF",
    "type": 1,
    "percent_off": 25,
    "amount_available": 10000,
    "max_circulation": 1000,
    "metadata": {
    },
    "expiration": null
}'

返回示例

{
    "id": "300116082415452100000700",
    "object": "coupon_template",
    "app": "APP_ID",
    "amount_available": 10000,
    "amount_off": 25,
    "created": 1470904889,
    "expiration": null,
    "livemode": false,
    "max_circulation": 1000,
    "metadata": {
    },
    "name": "25OFF",
    "percent_off": null,
    "refundable": true,
    "times_circulated": 0,
    "times_redeemed": 0,
    "type": 1
}

查询 Coupon Template 对象

通过 coupon_template 对象的 id 查询一个已创建的 coupon_template 对象。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
COUPON_TMPL_ID required string coupon_template 对象的 id

返回

返回一个 coupon_template 对象,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/coupon_templates/{COUPON_TMPL_ID}

请求示例

curl https://api.pingxx.com/v1/apps/{APP_ID}/coupon_templates/300116082415452100000700 \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \

返回示例

{
    "id": "300116082415452100000700",
    "object": "coupon_template",
    "app": "APP_ID",
    "amount_available": 10000,
    "amount_off": 25,
    "created": 1470904889,
    "expiration": null,
    "livemode": false,
    "max_circulation": 1000,
    "metadata": {
    },
    "name": "25OFF",
    "percent_off": null,
    "times_circulated": 0,
    "times_redeemed": 0,
    "type": 1
}

查询 Coupon Template 对象列表

返回之前创建过 coupon_template 对象的一个列表。列表是按创建时间进行排序,总是将最新的 coupon_template 对象显示在最前。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
page optional timestamp 页码,默认值为 "1",取值范围:1-100000000。
per_page optional timestamp 每页数量,默认值为 "20",取值范围:1-100。
created [ gt ] optional timestamp 创建时间大于该值,用 Unix 时间戳表示。
created [ gte ] optional timestamp 创建时间大于或等于该值,用 Unix 时间戳表示。
created [ lt ] optional timestamp 创建时间小于该值,用 Unix 时间戳表示。
created [ lte ] optional timestamp 创建时间小于或等于该值,用 Unix 时间戳表示。

返回

返回一个 coupon_template 对象列表,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/coupon_templates

请求示例

curl https://api.pingxx.com/v1/apps/{APP_ID}/coupon_templates \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "object": "list",
    "url": "/v1/apps/{APP_ID}/coupon_templates",
    "has_more": true,
    "data": [
        {
            "id": "300116082415452100000700",
            "object": "coupon_template",
            "app": "APP_ID",
            "amount_available": 10000,
            "amount_off": 25,
            "created": 1470904889,
            "expiration": null,
            "livemode": false,
            "max_circulation": 1000,
            "metadata": {
            },
            "name": "25 OFF",
            "percent_off": null,
            "refundable": true,
            "times_circulated": 0,
            "times_redeemed": 0,
            "type": 1
        },
        {
            "id": "300116082416033500000800",
            "object": "coupon_template",
            "app": "APP_ID",
            "amount_available": 10000,
            "amount_off": null,
            "created": 1472025815,
            "expiration": null,
            "livemode": false,
            "max_circulation": 2000,
            "metadata": {
            },
            "name": "30% OFF",
            "percent_off": 30,
            "refundable": true,
            "times_circulated": 0,
            "times_redeemed": 0,
            "type": 2
        },
        {...},
        {...}
    ]
}

更新 Coupon Template 对象

使用该接口更新 coupon_template 对象的信息。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
COUPON_TMPL_ID required string coupon_template 对象的 id
metadata optinoal hash 详见 元数据

返回

返回一个 coupon_template 对象,或者返回一个错误,详见 错误

定义

PUT https://api.pingxx.com/v1/apps/{APP_ID}/coupon_templates/{COUPON_TMPL_ID}

请求示例

curl https://api.pingxx.com/v1/apps/{APP_ID}/coupon_templates \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:
-d '{
    "metadata": {
        "key": "value"
    }
}'

返回示例

{
    "id": "300116082415452100000700",
    "object": "coupon_template",
    "app": "APP_ID",
    "amount_available": 10000,
    "amount_off": 25,
    "created": 1470904889,
    "expiration": null,
    "livemode": false,
    "max_circulation": 1000,
    "metadata": {
        "key": "value"
    },
    "name": "25 OFF",
    "percent_off": null,
    "refundable": true,
    "times_circulated": 0,
    "times_redeemed": 0,
    "type": 1
}

删除 Coupon Template 对象

调用此接口实现对 coupon_template 对象的删除。优惠券模板删除后,通过该优惠券模板生成优惠券仍然可以被查询,但不可以被使用(核销)。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
COUPON_TMPL_ID required string coupon_template 对象的 id

返回

返回一个 JSON 格式的删除信息,或者返回一个错误,详见 错误

定义

DELETE https://api.pingxx.com/v1/apps/{APP_ID}/coupon_templates/{COUPON_TMPL_ID}

请求示例

DELETE https://api.pingxx.com/v1/apps/{APP_ID}/coupon_templates/{COUPON_TMPL_ID} \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:
-d '{
    "deleted": true,
    "id": "COUPON_TMPL_ID"
}'

返回示例

{
    "deleted": true,
    "id": "COUPON_TMPL_ID"
}

Coupons 优惠券

通过一个 coupon_template 对象在指定用户下创建一个 coupon 对象用于生成一张优惠券,coupon 对象的有效时间根据关联的 coupon_template 对象由系统自动计算得出,可以在有效时间内在订单创建时使用。

属性
id string 优惠券对象 ID,由 Ping++ 生成。
object string 值为 "coupon"。
app string 对应 app 对象的 id ,查看 如何获取App ID
created int 创建时间,用 Unix 时间戳表示。
livemode boolean 是否处于 live 模式。
valid boolean 是否可用。优惠券过期、优惠券已使用、关联的优惠券模板删除会使该优惠券变为不可用。
redeemed bolean 是否已经使用(核销)。
coupon_template hash 关联的 coupon_template 对象。
user string user 对象的 id
time_start timestamp 可用的开始时间,用 Unix 时间戳表示。
time_end timestamp 可用的结束时间,用 Unix 时间戳表示。
order string 关联 order 对象的 id 。使用后生效。
actual_amount int 关联 order 对象的应付金额,单位为分。使用后生效。
metadata hash 详见 元数据

示例对象

{
   "id": "COUPON_ID",
   "object": "coupon",
   "app": "APP_ID",
   "actual_amount": null,
   "coupon_template": {
       "id": "300116082415452100000700",
       "object": "coupon_template",
       "app": "APP_ID",
       "amount_available": 10000,
       "amount_off": 25,
       "created": 1470904889,
       "expiration": null,
       "livemode": false,
       "max_circulation": 1000,
       "metadata": {
       },
       "name": "25 OFF",
       "percent_off": null,
       "refundable": true,
       "times_circulated": 0,
       "times_redeemed": 0,
       "type": 1
   },
   "created": 1470969003,
   "livemode": false,
   "metadata": {
   },
   "order": null,
   "redeemed": false,
   "time_end": 1472265014,
   "time_start": 1470969010,
   "user": "USER_ID",
   "valid": true
}

创建 Coupon 对象

通过 coupon_template 对象的 id 在一个用户下生成一个 coupon 对象,实现由服务端发放优惠券,或者由用户领取优惠券。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
USER_ID required string user 对象的 id
coupon_template required string coupon_template 对象的 id
metadata optional hash 详见 元数据

返回

返回一个 coupon 对象,或者返回一个错误,详见 错误

定义

POST https://api.pingxx.com/v1/apps/{APP_ID}/users/{USER_ID}/coupons

请求示例

POST https://api.pingxx.com/v1/apps/{APP_ID}/users/{USER_ID}/coupons \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:
-d '{
     "coupon_template": "coupon_template_id"
}'

返回示例

{
    "id": "COUPON_ID",
    "object": "coupon",
    "app": "APP_ID",
    "actual_amount": null,
    "coupon_template": {
        "id": "300116082415452100000700",
        "object": "coupon_template",
        "app": "APP_ID",
        "amount_available": 10000,
        "amount_off": 25,
        "created": 1470904889,
        "expiration": null,
        "livemode": false,
        "max_circulation": 1000,
        "metadata": {
        },
        "name": "25 OFF",
        "percent_off": null,
        "refundable": true,
        "times_circulated": 0,
        "times_redeemed": 0,
        "type": 1
    },
    "created": 1470969003,
    "livemode": false,
    "metadata": {
    },
    "order": null,
    "redeemed": false,
    "time_end": 1472265014,
    "time_start": 1470969010,
    "user": "USER_ID",
    "valid": true
}

批量创建 Coupon 对象

通过 coupon_template 对象的 id 批量在多个用户下各生成一张优惠券。一般由服务端主动触发(批量发放)。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
COUPON_TMPL_ID required string coupon_template 对象的 id
users required list user 对象的 id 列表。
metadata optional hash 详见 元数据

返回

返回一个 coupon 对象列表,或者返回一个错误,详见 错误

定义

POST https://api.pingxx.com/v1/apps/{APP_ID}/coupon_templates/{COUPON_TMPL_ID}/coupons

请求示例

POST https://api.pingxx.com/v1/apps/{APP_ID}/coupon_templates/{COUPON_TMPL_ID}/coupons \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:
-d '{
    "users": [
        "user_id_1",
        "user_id_2",
        "user_id_3"
    ]
}'

返回示例

{
    "object": "list",
    "url": "/v1/apps/APP_ID/coupon_templates/COUPON_TMPL_ID/coupons",
    "has_more": false,
    "data": [
        {

        },
        {

        }
    ]
}

查询 Coupon 对象

通过 coupon 对象的 id 查询一个已创建的 coupon 对象。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
USER_ID required string user 对象的 id
COUPON_ID required string coupon 对象的 id

返回

返回一个 coupon 对象,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/users/{USER_ID}/coupons/{COUPON_ID}

请求示例

curl https://api.pingxx.com/v1/apps/{APP_ID}/users/{USER_ID}/coupons/{COUPON_ID} \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "id": "coupon_id",
    "object": "coupon",
    "app": "APP_ID",
    "actual_amount": null,
    "coupon_template": {
        "id": "300116082415452100000700",
        "object": "coupon_template",
        "app": "APP_ID",
        "amount_available": 10000,
        "amount_off": 25,
        "created": 1470904889,
        "expiration": null,
        "livemode": false,
        "max_circulation": 1000,
        "metadata": {
        },
        "name": "25 OFF",
        "percent_off": null,
        "refundable": true,
        "times_circulated": 0,
        "times_redeemed": 0,
        "type": 1
    },
    "created": 1470969003,
    "livemode": false,
    "metadata": {
        "key": "value"
    },
    "order": null,
    "redeemed": false,
    "time_end": 1472265014,
    "time_start": 1470969003,
    "user": "user_id",
    "valid": true
}

查询用户的 Coupon 对象列表

根据 user 对象的 id 查询该用户下的已创建的 coupon 对象列表。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
USER_ID required string user 对象的 id
amount optional int 订单的原始金额,单位为分。传入该值可以在返回值 actual_amount 得到订单使用优惠券之后的金额。
redeemed optional boolean 优惠券是否已使用(核销)。
expired optional boolean 优惠券是否已过期。
page optional int 页码,默认值为 "1",取值范围:1-100000000。
per_page optional int 每页数量,默认值为 "20",
created [ gt ] optional int 创建时间大于该值,用 Unix 时间戳表示。
created [ gte ] optional int 创建时间大于或等于该值,用 Unix 时间戳表示。
created [ lt ] optional int 创建时间小于该值,用 Unix 时间戳表示。
created [ lte ] optional int 创建时间小于或等于该值,用 Unix 时间戳表示。

返回

返回一个 coupon 对象列表,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/users/{USER_ID}/coupons

请求示例

curl https://api.pingxx.com/v1/apps/{APP_ID}/users/{USER_ID}/coupons \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "object": "list",
    "url": "/v1/apps/APP_ID/users/USER_ID/coupons",
    "has_more": true,
    "data": [
        {

        },
        {

        }
    ]
}

查询 Coupon 对象列表

根据 coupon_template 对象的 id 查询通过该优惠券模板生成的 coupon 对象列表。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
COUPON_TMPL_ID required string coupon_template 对象的 id
amount optional int 订单的原始金额,单位为分。传入该值可以在返回值 actual_amount 得到订单使用优惠券之后的金额。
redeemed optional boolean 优惠券是否已使用(核销)。
page optional int 页码,默认值为 "1"。
per_page optional int 每页数量,默认值为 "20"。
created [ gt ] optional int 创建时间大于该值,用 Unix 时间戳表示。
created [ gte ] optional int 创建时间大于或等于该值,用 Unix 时间戳表示。
created [ lt ] optional int 创建时间小于该值,用 Unix 时间戳表示。
created [ lte ] optional int 创建时间小于或等于该值,用 Unix 时间戳表示。

返回

返回一个 coupon 对象列表,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/apps/{APP_ID}/coupon_templates/{COUPON_TMPL_ID}/coupons

请求示例

curl https://api.pingxx.com/v1/apps/{APP_ID}/coupon_templates/{COUPON_TMPL_ID}/coupons \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "object": "list",
    "url": "/v1/apps/APP_ID/coupon_templates/COUPON_TMPL_ID/coupons",
    "has_more": true,
    "data": [
        {

        },
        {

        }
    ]
}

更新 Coupon 对象

使用该接口更新 coupon 对象的信息。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
USER_ID required string user 对象的 id
COUPON_ID required string coupon 对象的 id
metadata optional hash 详见 元数据

返回

返回一个 coupon 对象,或者返回一个错误,详见 错误

定义

PUT https://api.pingxx.com/v1/apps/{APP_ID}/users/{USER_ID}/coupons/{COUPON_ID}

请求示例

POST https://api.pingxx.com/v1/apps/{APP_ID}/users/{USER_ID}/coupons/{COUPON_ID} \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:
-d '{
    "metadata": {
        "key": "value"
    }
}'

返回示例

{
    "id": "coupon_id",
    "object": "coupon",
    "app": "APP_ID",
    "actual_amount": null,
    "coupon_template": {
        "id": "300116082415452100000700",
        "object": "coupon_template",
        "app": "APP_ID",
        "amount_available": 10000,
        "amount_off": 25,
        "created": 1470904889,
        "expiration": null,
        "livemode": false,
        "max_circulation": 1000,
        "metadata": {
        },
        "name": "25 OFF",
        "percent_off": null,
        "refundable": true,
        "times_circulated": 0,
        "times_redeemed": 0,
        "type": 1
    },
    "created": 1470969003,
    "livemode": false,
    "metadata": {
        "key": "value"
    },
    "order": null,
    "redeemed": false,
    "time_end": 1472265014,
    "time_start": 1470969003,
    "user": "user_id",
    "valid": true
}

删除 Coupon 对象

调用此接口实现对 coupon 对象的删除,一般由用户在客户端触发此行为。可以对未使用、已过期和已使用的优惠券进行删除。

请求参数
APP_ID required string 对应 app 对象的 id ,查看 如何获取App ID
USER_ID required string user 对象的 id
COUPON_ID required string coupon 对象的 id

返回

返回一个 JSON 格式的删除信息,或者返回一个错误,详见 错误

定义

DELETE https://api.pingxx.com/v1/apps/{APP_ID}/users/{USER_ID}/coupons/{COUPON_ID}

请求示例

curl https://api.pingxx.com/v1/apps/{APP_ID}/users/{USER_ID}/coupons/{COUPON_ID} \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:
-d '{
    "deleted": true,
    "id": "COUPON_ID"
}'

返回示例

{
    "deleted": true,
    "id": "COUPON_ID"
}

Royalties 分润

royalty 对象在订单付款完成或退款完成后由 Ping++ 自动生成,根据订单中的分润信息或分润模板生成的清分数据。royalty 对象会在分润发起方和分润接收方关联的 app 下同时生成,且内容一致。

属性
id string 分润对象 ID ,由 Ping++ 生成。
object string 值为 "royalty"。
payer_app string 分润发起方对应的 app 对象的 id
created timestamp 创建时间,用 Unix 时间戳表示。
livemode boolean 是否处于 live 模式。
status string 分润状态。值为 created :入账、 pending :结算发起、 waiting :结算汇总、 succeeded :结算成功。
amount integer 分润金额,单位为分。数值带符号,其中负值表示支出、正值表示收入。
method string 分润方式。目前支持渠道: wx_pub (微信公众号)、 wx_lite (微信小程序)、 alipay (支付宝)、 unionpay (银联)、 unionpay_gz (贵州银联)、 allinpay (通联)和 jdpay (京东)、 balance (余额),以及 manual (手动标记)。
recipient_app string 分润接收方的 app 对象的 id
royalty_transaction string 关联的 royalty_transaction 对象的 id
royalty_settlement string 关联的分润结算 ID。
time_settled string 结算成功时间,用 Unix 时间戳表示。
settle_account string 关联的 settle_account 对象的 id ,表示该分润结算对应用户结算账户。
source_app string 平台的 app 对象的 id
source_url string 关联对象的请求地址,目前支持 order 对象,例如:"/v1/orders/{ORDER_ID}"。
source_no string 关联对象的 order_no
source_user string 分润接收方 user 对象的 id
description string 附加说明,最多 255 个 Unicode 字符。
metadata optional 详见 元数据

对象示例

{
    "object": "list",
    "url": "/v1/royalties",
    "has_more": false,
    "data": [
        {
            "id": "170301124238000111",
            "object": "royalty",
            "payer_app": "app_1Gqj58ynP0mHeX1q",
            "amount": -1,
            "created": 1488343358,
            "description": "Your description",
            "livemode": true,
            "metadata": {},
            "method": "manual",
            "recipient_app": null,
            "royalty_transaction": null,
            "royalty_settlement": null,
            "source_app": "app_1Gqj58ynP0mHeX1q",
            "source_no": "12345678",
            "source_url": "/v1/orders/2011609010000025991",
            "source_user": "user_001",
            "status": "succeeded",
            "settle_account": null,
            "time_settled": 1488465301
        },
        {...},
        {...}
    ]
}

批量更新 Royalty 对象

通过 royalty 对象的 id 列表批量更新多个已创建的 royalty 对象的信息,包括修改描述信息和标记结算功能。

请求参数
ids list required royalty 对象的 id 列表。
method string optional 支持手动标记结算: manual ,或取消手动标记结算: null
description string optional 附加说明,最多 255 个 Unicode 字符。
metadata hash optional 详见 元数据

返回

返回一个 royalty 对象列表,或者返回一个错误,详见 错误

定义

PUT https://api.pingxx.com/v1/royalties/

请求示例

curl https://api.pingxx.com/v1/royalties \
-X PUT \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC: \
-H "Content-Type: application/json" \
-d '{
    "ids": ["170301124238000111"],
    "method": "manual",
    "description": "Your description"
}'

返回示例

{
    "object": "list",
    "url": "/v1/royalties",
    "has_more": false,
    "data": [
        {
            "id": "170301124238000111",
            "object": "royalty",
            "payer_app": "app_1Gqj58ynP0mHeX1q",
            "amount": -1,
            "created": 1488343358,
            "description": "Your description",
            "livemode": true,
            "metadata": {},
            "method": "manual",
            "recipient_app": null,
            "royalty_transaction": null,
            "royalty_settlement": null,
            "source_app": "app_1Gqj58ynP0mHeX1q",
            "source_no": "12345678",
            "source_url": "/v1/orders/2011609010000025991",
            "source_user": "user_001",
            "status": "succeeded",
            "settle_account": null,
            "time_settled": 1488465301
        },
        {...},
        {...}
    ]
}

查询 Royalty 对象

通过 royalty 对象的 id 更新一个已创建的 royalty 对象的信息。

请求参数
ROYALTY_ID string required royalty 对象的 id

返回

返回一个 royalty 对象,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/royalties/{ROYALTY_ID}

请求示例

curl https://api.pingxx.com/v1/royalties/{ROYALTY_ID} \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "id": "170301124238000111",
    "object": "royalty",
    "payer_app": "app_1Gqj58ynP0mHeX1q",
    "amount": -1,
    "created": 1488343358,
    "description": "Your description",
    "livemode": true,
    "metadata": {},
    "method": null,
    "recipient_app": null,
    "royalty_transaction": null,
    "royalty_settlement": null,
    "source_app": "app_1Gqj58ynP0mHeX1q",
    "source_no": "12345678",
    "source_url": "/v1/orders/2011609010000025991",
    "source_user": "user_001",
    "status": "created",
    "settle_account": null,
    "time_settled": null
}

查询 Royalty 对象列表

返回之前创建过 royalty 对象的一个列表。列表是按创建时间进行排序,总是将最新的 royalty 对象显示在最前。

请求参数
payer_app string optional 分润发起方对应的 app 对象的 id
recipient_app string optional 分润接收方 user 关联的 app 对象的 id
source_app string optional 平台的 app 对象的 id
source_no string optional 关联对象的 order_no
source_user string optional 分润接收方 user 对象的 id
status string optional 分润状态。值为 created :入账、 pending :结算发起、 waiting :结算汇总、 succeeded :结算成功。
royalty_settlement string optional 关联的分润结算 ID。
royalty_transaction string optional 关联的分润结算明细 ID。
page integer optional 页码,默认值为 "1",取值范围(1~100000000)。
per_page optional integer 每页数量,默认值为 "10"。
created [ gt ] optional timestamp 创建时间大于该值,用 Unix 时间戳表示。
created [ gte ] optional timestamp 创建时间大于或等于该值,用 Unix 时间戳表示。
created [ lt ] optional timestamp 创建时间小于该值,用 Unix 时间戳表示。
created [ lte ] optional timestamp 创建时间小于或等于该值,用 Unix 时间戳表示。

返回

返回一个 royalty 对象,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/royalties

请求示例

curl https://api.pingxx.com/v1/royalties \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "object": "list",
    "url": "/v1/royalties",
    "has_more": false,
    "data": [
        {
            "id": "170301124238000111",
            "object": "royalty",
            "payer_app": "app_1Gqj58ynP0mHeX1q",
            "amount": -1,
            "created": 1488343358,
            "description": "Your description",
            "livemode": true,
            "metadata": {},
            "method": "manual",
            "recipient_app": null,
            "royalty_transaction": null,
            "royalty_settlement": null,
            "source_app": "app_1Gqj58ynP0mHeX1q",
            "source_no": "12345678",
            "source_url": "/v1/orders/2011609010000025991",
            "source_user": "user_001",
            "status": "succeeded",
            "settle_account": null,
            "time_settled": 1488465301
        },
        {...},
        {...}
    ]
}

Royalty Templates 分润模板

通过创建 royalty_template 对象来设置一个分润模板。分润模板定义了分润的规则,在创建 order 时传入 royalty_template 对象的 id,在订单付款完成和退款完成时,Ping++ 会根据模板的规则计算分润的用户和金额完成清分。 分润模板依赖于订单层级链,只能给层级链上的商户分润。如果分润规则复杂或者需要给个人用户分润,则分润模板不适用。

属性
id string 分润模板对象 ID,由 Ping++ 生成。
object string 值为 royalty_template
app string 对应 app 对象的 id ,expandable 可展开,查看 如何获取App ID
name string 分润模板名称,允许中英文等常用字符,取值范围 2~50 位。
created timestamp 创建时间,用 Unix 时间戳表示。
rule [ royalty_mode ] string 分润模式。值为 rate 表示按订单金额(包含优惠券金额)比例计算;值为 fixed 表示按固定金额收取分润。
rule [ refund_mode ] string 退分润模式。值为 no_refund 表示不退分润;值为 proportional 表示按退款占支付的比例退分润;值为 full_refund 表示一旦退款成功分润全退。
rule [ allocation_mode ] string 分配模式。表示当订单确定的层级如果少于模板配置层级时,模板中计算出的多余分润金额是归属于收款方: receipt_reserved 或服务方: service_reserved
rule [ data ] list 分润数据列表,详见下方 rule[data] 列表属性说明。
description string 附加说明,最多 100 个 Unicode 字符。
rule[data] 列表属性
level integer 商户层级,值为 0~5,其中 "0" 表示平台。
value integer 分润数值。 royalty_moderate 时,取值范围 0~10000,单位为 0.01%; royalty_modefixed 时,取值范围 0~1000000,单位为分。

创建 Royalty Template 对象

通过创建 royalty_template 对象来设置一个分润模板。

请求参数
app required string 对应 app 对象的 id ,expandable 可展开,查看 如何获取App ID
rule [ royalty_mode ] required string 分润模式。值为 rate 表示按订单金额(包含优惠券金额)比例计算;值为 fixed 表示按固定金额收取分润。
rule [ refund_mode ] required string 退分润模式。值为 no_refund 表示不退分润;值为 proportional 表示按退款占支付的比例退分润;值为 full_refund 表示一旦退款成功分润全退。
rule [ allocation_mode ] required string 分配模式。表示当订单确定的层级如果少于模板配置层级时,模板中计算出的多余分润金额是归属于收款方: receipt_reserved 或服务方: service_reserved
rule [ data ] required list 分润数据列表,详见下方 rule[data] 列表参数说明。
name optional string 模板名称,允许中英文等常用字符,取值范围 2~50 位。
description optional string 附加说明,最多 100 个 Unicode 字符。
rule[data] 列表参数
level required integer 商户层级,值为 0~5,其中 "0" 表示平台。
value required integer 分润数值。 royalty_moderate 时,取值范围 0~10000,单位为 0.01%; royalty_modefixed 时,取值范围 0~1000000,单位为分。

返回

返回一个 royalty_template 对象,或者返回一个错误,详见 错误

定义

POST https://api.pingxx.com/v1/royalty_templates

请求示例

curl https://api.pingxx.com/v1/royalty_templates \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1496728534" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
  "app": "app_1Gqj58ynP0mHeX1q",
  "name": "royalty_templates name",
  "rule": {
    "royalty_mode": "rate",
    "refund_mode": "no_refund",
    "allocation_mode": "receipt_reserved",
    "data": [
      {
        "level": 0,
        "value": 11
      },
      {
        "level": 1,
        "value": 12
      }
    ]
  }
}
'

返回示例

{
    "id": "450170814144600001",
    "object": "royalty_template",
    "livemode": false,
    "app": "app_1Gqj58ynP0mHeX1q",
    "name": "royalty_templates name",
    "created": 1502693202,
    "description": null,
    "rule": {
        "royalty_mode": "rate",
        "refund_mode": "no_refund",
        "allocation_mode": "receipt_reserved",
        "data": [
            {
                "level": 0,
                "value": 11
            },
            {
                "level": 1,
                "value": 12
            }
        ]
    }
}

查询 Royalty Template 对象

通过 royalty_template 对象的 id 查询一个已创建的 royalty_template 对象。

请求参数
ROYALTY_TEMPLATE_ID required string royalty_template 对象的 id

返回

返回一个 royalty_template 对象,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/royalty_templates/{ROYALTY_TEMPLATE_ID}

请求示例

curl https://api.pingxx.com/royalty_templates/v1/500307110543000111 \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1496728534" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "id": "450170814144900001",
    "object": "royalty_template",
    "livemode": false,
    "app": "app_1Gqj58ynP0mHeX1q",
    "name": "royalty_templates name2",
    "created": 1502693391,
    "description": null,
    "rule": {
        "royalty_mode": "rate",
        "refund_mode": "no_refund",
        "allocation_mode": "receipt_reserved",
        "data": [
            {
                "level": 0,
                "value": 11
            },
            {
                "level": 1,
                "value": 12
            }
        ]
    }
}

查询 Royalty Template 对象列表

返回之前创建过 royalty_template 对象的一个列表。列表是按创建时间进行排序,总是将最新的 royalty_template 对象显示在最前。

请求参数
app required string 对应 app 对象的 id ,expandable 可展开,查看 如何获取App ID
rule [ royalty_mode ] optional string 分润模式。值为 rate 表示按订单金额(包含优惠券金额)比例计算;值为 fixed 表示按固定金额收取分润。
rule [ refund_mode ] optional string 退分润模式。值为 no_refund 表示不退分润;值为 proportional 表示按退款占支付的比例退分润;值为 full_refund 表示一旦退款成功分润全退。
rule [ allocation_mode ] optional string 分配模式。表示当订单确定的层级如果少于模板配置层级时,模板中多余的分润金额是归属于服务方: service_reserved 或收款方: receipt_reserved
page optional integer 页码,默认值为 "1",取值范围(1~100000000)。
per_page optional integer 每页数量,默认值为 "10",取值范围(1~100)。
created [ gt ] optional timestamp 创建时间大于该值,用 Unix 时间戳表示。
created [ gte ] optional timestamp 创建时间大于或等于该值,用 Unix 时间戳表示。
created [ lt ] optional timestamp 创建时间小于该值,用 Unix 时间戳表示。
created [ lte ] optional timestamp 创建时间小于或等于该值,用 Unix 时间戳表示。

返回

返回一个 royalty_template 对象列表,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/royalty_templates

请求示例

curl https://api.pingxx.com/v1/royalty_templates \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1496728534" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "object": "list",
    "url": "/v1/royalty_templates",
    "has_more": false,
    "data": [
        {
            "id": "450170814144900001",
            "object": "royalty_template",
            "livemode": false,
            "app": "app_1Gqj58ynP0mHeX1q",
            "name": "royalty_templates name2",
            "created": 1502693391,
            "description": null,
            "rule": {
                "royalty_mode": "rate",
                "refund_mode": "no_refund",
                "allocation_mode": "receipt_reserved",
                "data": [
                    {
                        "level": 0,
                        "value": 11
                    },
                    {
                        "level": 1,
                        "value": 12
                    }
                ]
            }
        },
        {...},
        {...}
  ]
}

更新 Royalty Templates 对象

通过 royalty_template 对象的 id 更新一个已创建的 royalty_template 对象的信息。

请求参数
ROYALTY_TEMPLATE_ID required string royalty_template 对象的 id
rule [ royalty_mode ] optional string 分润模式。值为 rate 表示按订单金额(包含优惠券金额)比例计算;值为 fixed 表示按固定金额收取分润。
rule [ refund_mode ] optional string 退分润模式。值为 no_refund 表示不退分润;值为 proportional 表示按退款占支付的比例退分润;值为 full_refund 表示一旦退款成功分润全退。
rule [ allocation_mode ] optional string 分配模式。表示当订单确定的层级如果少于模板配置层级时,模板中计算出的多余分润金额是归属于收款方: receipt_reserved 或服务方: service_reserved
rule [ data ] optional list 分润数据列表,详见下方 rule[data] 参数说明。
name optional string 模板名称,允许中英文等常用字符,取值范围 2~50 位。
description optional string 附加说明,最多 100 个 Unicode 字符。
rule[data] 参数说明
level required integer 商户层级,值为 0~5,其中 "0" 表示平台。
value required integer 分润数值。 royalty_moderate 时,取值范围 0~10000,单位为 0.01%; royalty_modefixed 时,取值范围 0~1000000,单位为分。

返回

返回一个 royalty_template 对象,或者返回一个错误,详见 错误

定义

PUT https://api.pingxx.com/v1/royalty_templates/{ROYALTY_TEMPLATE_ID}

请求示例

curl -X PUT https://api.pingxx.com/v1/royalty_templates/450170814144900001 \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1496728534" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:
-d '{
  "name": "royalty_templates name new",
  "rule": {
    "royalty_mode": "rate",
    "refund_mode": "proportional",
    "allocation_mode": "service_reserved",
    "data": [
      {
        "level": 1,
        "value": 21
      },
      {
        "level": 2,
        "value": 30
      }
    ]
  }
}'

返回示例

{
    "id": "450170814144900001",
    "object": "royalty_template",
    "livemode": false,
    "app": "app_1Gqj58ynP0mHeX1q",
    "name": "royalty_templates name new",
    "created": 1502693673,
    "description": null,
    "rule": {
        "royalty_mode": "rate",
        "refund_mode": "proportional",
        "allocation_mode": "service_reserved",
        "data": [
            {
                "level": 1,
                "value": 21
            },
            {
                "level": 2,
                "value": 30
            }
        ]
    }
}

删除 Royalty Template 对象

通过 royalty_template 对象的 id 删除一个已创建的 royalty_template 对象。

请求参数
ROYALTY_TEMPLATE_ID required string royalty_template 对象的 id

返回

返回一个 JSON 格式的删除信息,或者返回一个错误,详见 错误

定义

DELETE https://api.pingxx.com/v1/royalty_templates/{ROYALTY_TEMPLATE_ID}

请求示例

curl -X DELETE https://api.pingxx.com/v1/royalty_templates/500307110543000111 \
-H "Pingplusplus-Signature: {SIGNATURE}" \
-H "Pingplusplus-Request-Timestamp: 1496728534" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "deleted": true,
    "id": "500307110543000111"
}

Royalty Settlements 分润结算

分润记录产生之后,需要创建 royalty_settlement 对象来将分润结算到接收分润方的账户。royalty_settlement 对象创建后,会根据分润接收方生成一个或多个 royalty_transaction 对象记录每个分润接收方的分润情况,可以根据实际情况进行结算的确认或取消。

注:微信服务商模式商户暂不支持分润结算。

属性
id string 分润结算对象 ID,由 Ping++ 生成。
object string 值为 "royalty_settlement"。
payer_app string 分润发起方关联的 app 对象的 id
created timestamp 创建时间,用 Unix 时间戳表示。
livemode boolean 是否处于 live 模式。
method string 分润方式。目前支持渠道: wx_pub (微信公众号)、 wx_lite (微信小程序)、 alipay (支付宝)、 unionpay (银联)、 unionpay_gz (贵州银联)、 allinpay (通联)和 jdpay (京东)以及 balance (余额)。
amount integer 结算的总金额。
amount_succeeded integer 结算成功的分润金额。
amount_failed integer 结算失败的分润金额。
amount_canceled integer 结算取消的分润金额。
count integer 结算的总笔数。
count_succeeded integer 结算成功的笔数。
count_failed integer 结算失败的笔数。
count_canceled integer 取消的笔数。
time_finished timestamp 完成时间,用 Unix 时间戳表示。
fee integer 渠道收取的手续费,单位为分。
operation_url string 支付宝批量付款 URL。
status string 分润结算状态。值为 created :已创建、 pending :处理中、 succeeded :全部完成、 failed :全部失败、 partially_succeeded :部分成功、 canceled :全部取消。
royalty_transactions list 关联的 royalty_transaction 对象列表,详见 Royalty Transaction
metadata hash 详见 元数据

对象示例

{
    "id": "170302171104000011",
    "object": "royalty_settlement",
    "payer_app": "app_1Gqj58ynP0mHeX1q",
    "amount": 1000,
    "amount_canceled": 0,
    "amount_failed": 0,
    "amount_succeeded": 0,
    "count": 10,
    "count_canceled": 0,
    "count_failed": 0,
    "count_succeeded": 0,
    "created": 1488445864,
    "fee": 0,
    "livemode": true,
    "metadata": {},
    "method": "unionpay",
    "operation_url": null,
    "royalty_transactions": {
        "object": "list",
        "has_more": true,
        "url": "/v1/royalty_transactions",
        "data": [
            {
                "id": "170302171104000011",
                "object": "royalty_transaction",
                "amount": 15,
                "status": "created",
                "settle_account": "320217022818142300000901",
                "source_user": "user_002",
                "recipient_app": null,
                "royalty_settlement": "170302171104000011"
            },
            {...},
            {...}
        ]
    },
    "status": "created",
    "time_finished": null
}

创建 Royalty Settlement 对象

通过设置结算的条件,将一个或多个 royalty 对象进行汇总,生成 royalty_settlement 对象,其中为每个分润接收方生成 royalty_transaction 对象。

注:微信服务商模式商户暂不支持分润结算。

请求参数
payer_app required string 分润发起方关联的 app 对象的 id
method required string 分润方式。目前支持渠道: wx_pub (微信公众号)、 wx_lite (微信小程序)、 alipay (支付宝)、 unionpay (银联)、 unionpay_gz (贵州银联)、 allinpay (通联)和 jdpay (京东)以及 balance (余额)。
recipient_app optional string 分润接收方的 app 对象的 id
source_user optional string 分润接收方 user 对象的 id
source_no optional string 关联对象的商户订单号。
min_amount optional integer 最小分润金额,单位为分。创建分润结算时,如果分润接收方的结算金额小于该值,则不会生成 royalty_transaction 对象(不会进入结算)。
is_preview optional bool 是否预览结算结果,选择预览不会真实创建 royalty_settlement 对象(无法被查询),也不会更新 royalty 对象的状态,默认值为 false
created [ gt ] optional timestamp 创建时间大于该值,用 Unix 时间戳表示。
created [ gte ] optional timestamp 创建时间大于或等于该值,用 Unix 时间戳表示。
created [ lt ] optional timestamp 创建时间小于该值,用 Unix 时间戳表示。
created [ lte ] optional timestamp 创建时间小于或等于该值,用 Unix 时间戳表示。
metadata optional hash 详见 元数据

返回

返回一个 royalty_settlement 对象,或者返回一个错误,详见 错误

定义

POST https://api.pingxx.com/v1/royalty_settlements/

请求示例

curl https://api.pingxx.com/v1/royalty_settlements \
-H "Content-Type: application/json" \
-u sk_live_vjfr90jj1q985KuPO84iP8KO: \
-d '{
  "payer_app":"app_1Gqj58ynP0mHeX1q",
  "method": "unionpay",
  "recipient_app": "app_1Gqj58ynP0mHeX1q",
  "created": {
    "gt": 1488211200,
    "lte": 1488297600
  }
}'

返回示例

{
    "id": "170302171104000011",
    "object": "royalty_settlement",
    "payer_app": "app_1Gqj58ynP0mHeX1q",
    "amount": 1000,
    "amount_canceled": 0,
    "amount_failed": 0,
    "amount_succeeded": 0,
    "count": 10,
    "count_canceled": 0,
    "count_failed": 0,
    "count_succeeded": 0,
    "created": 1488445864,
    "fee": 0,
    "livemode": true,
    "metadata": {},
    "method": "unionpay",
    "operation_url": null,
    "royalty_transactions": {
        "object": "list",
        "has_more": true,
        "url": "/v1/royalty_transactions",
        "data": [
            {
                "id": "170302171104000011",
                "object": "royalty_transaction",
                "amount": 15,
                "status": "created",
                "settle_account": "320217022818142300000901",
                "source_user": "user_002",
                "recipient_app": null,
                "royalty_settlement": "170302171104000011"
            },
            {...},
            {...}
        ]
    },
    "status": "created",
    "time_finished": null
}

查询 Royalty Settlement 对象

通过 royalty_settlement 对象的 id 查询一个已创建的 royalty_settlement 对象。

请求参数
ROYALTY_SETTLEMENT_ID required string royalty_settlement 对象的 id

返回

返回一个 royalty_settlement 对象,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/royalty_settlements/{ROYALTY_SETTLEMENT_ID}

请求示例

curl https://api.pingxx.com/v1/royalty_settlements/170302171104000011 \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "id": "170302171104000011",
    "object": "royalty_settlement",
    "payer_app": "app_1Gqj58ynP0mHeX1q",
    "amount": 1000,
    "amount_canceled": 0,
    "amount_failed": 0,
    "amount_succeeded": 0,
    "count": 10,
    "count_canceled": 0,
    "count_failed": 0,
    "count_succeeded": 0,
    "created": 1488445864,
    "fee": 0,
    "livemode": true,
    "metadata": {},
    "method": "unionpay",
    "operation_url": null,
    "royalty_transactions": {
        "object": "list",
        "has_more": false,
        "url": "/v1/royalty_transactions",
        "data": [
            {
                "id": "170302171104000011",
                "object": "royalty_transaction",
                "amount": 15,
                "status": "created",
                "settle_account": "320217022818142300000901",
                "source_user": "user_002",
                "recipient_app": null,
                "royalty_settlement": "170302171104000011"
            },
            {...},
            {...}
        ]
    },
    "status": "created",
    "time_finished": null
}

更新 Royalty Settlement 对象

通过 royalty_settlement 对象的 id 更新一个已创建的 royalty_settlement 对象。

请求参数
ROYALTY_SETTLEMENT_ID required string royalty_settlement 对象的 id
status required string 状态修改,取值范围为:"pending" 和 "canceled"。如需要进行分润结算确认,请传入:"pending" ; 如需取消分润结算,请传入:"canceled"。

返回

返回一个更新后的 royalty_settlement 对象,或者返回一个错误,详见 错误

定义

PUT https://api.pingxx.com/v1/royalty_settlements/{ROYALTY_SETTLEMENT_ID}

请求示例

curl https://api.pingxx.com/v1/royalty_settlements/{ROYALTY_SETTLEMENT_ID} \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d'{
 "status": "canceled"
}'

返回示例

{
    "id": "170302171104000011",
    "object": "royalty_settlement",
    "payer_app": "app_1Gqj58ynP0mHeX1q",
    "amount": 1,
    "amount_canceled": 1,
    "amount_failed": 0,
    "amount_succeeded": 0,
    "count": 1,
    "count_canceled": 1,
    "count_failed": 0,
    "count_succeeded": 0,
    "created": 1488445864,
    "fee": 0,
    "livemode": true,
    "metadata": {},
    "method": "unionpay",
    "operation_url": null,
    "royalty_transactions": {
        "object": "list",
        "has_more": false,
        "url": "/v1/royalty_transactions",
        "data": [
            {
                "id": "170302171104000011",
                "object": "royalty_transaction",
                "amount": 1,
                "status": "canceled",
                "settle_account": "320217022818142300000901",
                "source_user": "user_002",
                "recipient_app": null,
                "royalty_settlement": "170302171104000011"
            }
        ]
    },
    "status": "canceled",
    "time_finished": null
}

查询 Royalty Settlement 对象列表

返回之前创建过 royalty_settlement 对象的一个列表。列表是按创建时间进行排序,总是将最新的 royalty_settlement 对象显示在最前。

请求参数
payer_app required string 分润发起方关联的 app 对象的 id
method optional string 分润方式。目前支持渠道: wx_pub (微信公众号)、 wx_lite (微信小程序)、 alipay (支付宝)、 unionpay (银联)、 unionpay_gz (贵州银联)、 allinpay (通联)和 jdpay (京东)以及 balance (余额)。
page optional integer 页码,默认值为 "1",取值范围(1~100000000)。
per_page optional integer 每页数量,默认值为 "10",取值范围(1~100)。
created [ gt ] optional timestamp 创建时间大于改值,用 Unix 时间戳表示。
created [ gte ] optional timestamp 创建时间大于或等于该值,用 Unix 时间戳表示。
created [ lt ] optional timestamp 创建时间小于该值,用 Unix 时间戳表示。
created [ lte ] optional timestamp 创建时间小于或等于该值,用 Unix 时间戳表示。

返回

返回一个 royalty_settlement 对象,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/royalty_settlements/

请求示例

curl https://api.pingxx.com/v1/royalty_settlements \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "object": "list",
    "url": "/v1/royalty_settlements",
    "has_more": true,
    "data": [
        {
            "id": "170302171104000011",
            "object": "royalty_settlement",
            "payer_app": "app_1Gqj58ynP0mHeX1q",
            "amount": 1,
            "amount_canceled": 1,
            "amount_failed": 0,
            "amount_succeeded": 0,
            "count": 1,
            "count_canceled": 1,
            "count_failed": 0,
            "count_succeeded": 0,
            "created": 1488445864,
            "fee": 0,
            "livemode": true,
            "metadata": {},
            "method": "unionpay",
            "operation_url": null,
            "royalty_transactions": {
                "object": "list",
                "has_more": false,
                "url": "/v1/royalty_transactions",
                "data": [
                    {
                        "id": "170302171104000011",
                        "object": "royalty_transaction",
                        "amount": 1,
                        "status": "canceled",
                        "settle_account": "320217022818142300000901",
                        "source_user": "user_002",
                        "recipient_app": null,
                        "royalty_settlement": "170302171104000011"
                    }
                ]
            },
            "status": "canceled",
            "time_finished": null
        }
        {...},
        {...}
    ]
}

Royalty Transactions 分润结算明细

royalty_transaction 对象记录一次分润结算中对一个分润接收方的分润详情,包括金额、结算账户和状态等信息,可以在关联的 royalty_settlement 对象中查询,也可以直接查询。royalty_transaction 对象同时也会在分润接收方关联的应用下生成。

属性
id string 分润账号 id。
object string 值为 "royalty_transaction"。
amount integer 分润结算金额。
created timestamp 创建时间,Unix 时间戳。
status string 分润结算状态,已创建:created、处理中:pending,完成:succeeded,失败:failed,取消:canceled。
settle_account string 使用的 settle_account 对象的 idbalancemanual 中的一种。
source_user string 分润接收方 user 对象的 id
recipient_app string 分润接收方关联的 app 对象的 id
royalty_settlement string 分润结算对象 ID

对象示例

 {
    "id": "170220181906000011",
    "object": "royalty_transaction",
    "amount": 4,
    "status": "canceled",
    "settle_account": "balance",
    "source_user": "user_001",
    "recipient_app": null,
    "royalty_settlement": "170220181906000011"
}

查询 Royalty Transaction 对象

通过 royalty_transaction 对象的 id 查询一个已创建的 royalty_transaction 对象。

请求参数
ROYALTY_TRANS_ID required 分润结算明细 ID。

返回

返回一个 royalty_transaction 对象,或者返回一个错误,详见 错误

定义

https://api.pingxx.com/v1/royalty_transactions/{ROYALTY_TRANS_ID} \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

请求示例

curl https://api.pingxx.com/v1/royalty_settlements/{ROYALTY_SETTLEMENT_ID}/transactions/{ROYALTY_TRANS_ID} \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "id": "170220181906000011",
    "object": "royalty_transaction",
    "amount": 4,
    "status": "canceled",
    "settle_account": "balance",
    "source_user": "user_001",
    "recipient_app": null,
    "royalty_settlement": "170220181906000011"
}

查询 Royalty Transaction 对象列表

返回之前创建过 royalty_transaction 对象的一个列表。列表是按创建时间进行排序,总是将最新的 royalty_transaction 对象显示在最前。

请求参数
royalty_settlement optional string royalty_settlement 对象的 id
page optional integer 页码,默认值为 "1",取值范围(1~100000000)。
per_page optional integer 每页数量,默认值为 "10",取值范围(1~100)。
created [ gt ] optional timestamp 创建时间大于改值,用 Unix 时间戳表示。
created [ gte ] optional timestamp 创建时间大于或等于该值,用 Unix 时间戳表示。
created [ lt ] optional timestamp 创建时间小于该值,用 Unix 时间戳表示。
created [ lte ] optional timestamp 创建时间小于或等于该值,用 Unix 时间戳表示。

返回

返回一个 royalty_transaction 对象列表,或者返回一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/royalty_transactions

请求示例

curl https://api.pingxx.com/v1/royalty_transactions \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "object": "list",
    "url": "/v1/royalty_transactions",
    "has_more": true,
    "data": [
        {
            "id": "170220181906000011",
            "object": "royalty_transaction",
            "amount": 4,
            "status": "canceled",
            "settle_account": "balance",
            "source_user": "user_001",
            "recipient_app": null,
            "royalty_settlement": "170220181906000011"
        },
        {...},
        {...}
    ]
}

Royalty Transaction 相关的 Event 类型

该类型的 Event 对象会在 royalty_settlement 对象在分润结算成功、分润结算失败、分润结算部分成功、分润结算部分失败时触发。以 Webhooks 形式发送至客户配置的 Webhooks URL 。详情请参考 Events 事件

事件类型 描述
royalty_settlement.succeeded 在分润结算成功时触发。
royalty_settlement.failed 在分润结算失败时触发。
royalty_settlement.partially_succeeded 在分润结算部分成功时触发。
royalty_settlement.canceled 在分润结算取消时触发。

身份证银行卡信息认证接口

独立的第三方接口,根据用户的姓名、身份证号、银行卡号、手机号,鉴别其身份真伪。此接口按照调用次数累加计费,并且调用成功即产生费用(无论认证成功与否)。使用时请预先进行账户充值注意:此接口强制要求签名(Pingplusplus-Signature),需在管理平台上配置商户公钥,但无须开启。此接口不支持 Test 模式下调用,仅可在 Live 模式下调用。

属性
type string 身份证信息或者银行卡信息串,取值范围:"id_card"(身份证信息串);"bank_card"(银行卡信息串)。
app string 应用 ID, 如何获取App ID
result_code int 返回码,详情请参照API文档附录的 认证接口result_code说明
message string 描述信息,接口调用失败时为错误描述,成功时为 "SUCCESS" 。
paid boolean 是否已扣款,扣款为 true ,未扣款为 false
data map 验证数据,包含参数见下表。
data包含参数
id_name string 身份证姓名(1~16位);
id_number string 身份证号码(15位或18位);
card_number string 银行卡号(12~19位) 仅在 type 参数为 "bank_card" 的时候必需要传此参数;
phone_number string 手机号(11位) 仅在 type 参数为 "bank_card" 的时候可以选择是否传此参数,暂不支持178开头的手机号。

示例对象

{
   "type": "id_card",
   "app": "app_LibTW1n1SOq9Pin1",
   "result_code": 0,
   "message": "SUCCESS",
   "paid":true,
   "data": {
       "id_name": "张三",
       "id_number": "320291198811110000"
   }
}

请求认证接口

独立的第三方接口,请求该接口根据用户的姓名、身份证号、银行卡号、手机号,鉴别其身份真伪。

请求参数
type required 身份证信息或者银行卡信息串,取值范围: "id_card"(身份证信息串);"bank_card"(银行卡信息串)。
app required 应用 ID ,查看 如何获取App ID
data required 验证数据,包含参数见下表。
data包含参数
id_name required string 身份证姓名(1~16位)。
id_number required string 身份证号码(15位或18位)。
card_number required string 银行卡号(12~19位) 仅在 type 参数为 "bank_card" 的时候必须要传此参数。
phone_number optional,string 手机号(11位) 仅在 type 参数为 "bank_card" 的时候可以选择是否传此参数,暂不支持178开头的手机号。

返回

请求成功,返回 result_code 字段为返回码,详情参照API文档附录的认证接口 result_code 说明;message 中是错误描述信息,仅在成功时返回 success ; paid 表示本次调用接口认证是否产生费用, paidtrue 则需要付费,false 不产生费用,或者返回一个错误,详见 错误

定义

POST https://api.pingxx.com/v1/identification

请求示例

curl https://api.pingxx.com/v1/identification \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Content-Type: application/json" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "type": "bank_card",
    "app": "app_1Gqj58ynP0mHeX1q",
    "data": {
        "id_name": "张三",
        "id_number": "320291198811110000",
        "card_number": "6201111122223333"
    }
}'

返回示例

{
   "type": "bank_card",
   "app": "app_1Gqj58ynP0mHeX1q",
   "result_code": 3441,
   "message": "银行卡信息认证失败",
   "paid":true,
   "data": {
       "id_name": "张三",
       "id_number": "320291198811110000",
       "card_number": "6201111122223333"
   }
}

报关接口

目前只针对支付成功的订单进行报关,报关金额为订单金额,customs_code 是海关编号字段说明,trade_no 区别于 charge 中的 order_no ,两者不能相同。注意:此接口不支持 Test 模式下调用,仅可在 Live 模式下调用。

属性
id string 报关对象 id
app string 应用 ID ,查看 如何获取App ID
channel string 支付使用的第三方支付渠道,取值范围:"alipay"(支付宝 APP 支付),"wx"(微信支付),"upacp"(银联),"applepay_upacp"(Apple Pay)。
trade_no string 商户报关订单号,8~20位。
customs_code string 海关编号,详情请参照 海关编号说明
amount int 报关金额,取值范围:1~1000000000。
charge string charge 对象 id
transport_amount int 订单物流金额,默认为0,当 is_splittrue 时,此参数无效。
is_split boolean 是否拆单,默认值为"false"。
sub_order_no string 商户子订单号,1~30位,当 is_splittrue 时此参数必填。
extra map 自定义参数,如果渠道为银联则需要额外参数 extra ,详情请参考下表的 extra 参数说明。
object string 值为 "customs" 。
created timestamp 创建时间,用 Unix 时间戳表示。
time_succeeded int 处理时间,用 Unix 时间戳表示。
status string 报关状态, pending : 处理中; succeeded : 成功; failed : 失败 。
failure_code string 错误码,详见 错误 中的错误码描述。
failure_msg string 错误信息描述。
transaction_no string 渠道报关流水号。
extra 参数
pay_account string 支付ID,1~60位,字母、数字和/或特殊符号字符。
certif_type string 证件类型,取值范围参考:"01":身份证;"02":军官证;"03":护照;"04":回乡证;"05":台胞证;"06":警官证 "07":士兵证; "99":其它证件。
customer_name string 姓名,1~20位,字母、数字和/或特殊符号字符。
certif_id string 证件号,1~30位,字母、数字和/或特殊符号字符。
tax_amount int 税费的金额。

示例对象

{
    "id": "14201607013878045463",
    "object": "customs",
    "app": "app_LibTW1n1SOq9Pin1",
    "charge_id": "ch_L8qn10mLmr1GS8e5OODmHaL4",
    "channel": "upacp",
    "trade_no": "15112496832609",
    "customs_code": "GUANGZHOU",
    "amount": 100,
    "status": "pending",
    "created": 1410834527,
    "time_succeeded": 1410838127,
    "failure_code": null,
    "failure_msg": null,
    "transaction_no": "xxxxxxxx",
    "extra":{}
}

请求报关接口

请求报关接口,目前只针对支付成功的订单 charge id 进行报关请求,报关金额为订单金额,目前渠道限于 alipay, wx ,upacpapplepay_upacp注意:此接口强制要求签名(Pingplusplus-Signature),需在管理平台上配置商户公钥,但无须开启。

请求参数
app [ id ] required 应用 ID ,查看 如何获取App ID
channel required 支付使用的第三方支付渠道,取值范围:"alipay"(支付宝 APP 支付);"wx"(微信支付)和"upacp"(银联),"applepay_upacp"(Apple Pay)。
trade_no required 商户报关订单号,8 ~ 20 位,且不能与 charge 中的 order_no 相同。
customs_code required 海关编号,详情请参照 海关编号说明
amount required 报关金额,取值范围:1~1000000000。
charge required charge 对象 id
transport_amount optional 订单物流金额,默认为0,当 is_splittrue 时,此参数无效。
is_split optional 是否拆单,默认值为"false"。
sub_order_no optional 商户子订单号,1~30位,当 is_splittrue 时此参数必填。
extra optional 自定义参数,如果渠道为银联或者 Apple Pay 则需要额外参数 extra ,详情请参考下表的 extra 参数说明。
extra 参数
pay_account required 支付ID,1~60位,字母、数字和/或特殊符号字符。
certif_type required 证件类型,取值范围参考:"01":身份证;"02":军官证;"03":护照;"04":回乡证;"05":台胞证;"06":警官证 "07":士兵证; "99":其它证件。
customer_name required 姓名,1~20位,字母、数字和/或特殊符号字符。
certif_id required 证件号,1~30位,字母、数字和/或特殊符号字符。
tax_amount optional 税费的金额。

返回

返回一个 customs 报关对象,或者返回一个错误,详见 错误

定义

POST https://api.pingxx.com/v1/customs

请求示例

curl https://api.pingxx.com/v1/customs \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Content-Type: application/json" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "app":"App ID",
    "charge":"Charge ID",
    "channel": "upacp",
    "trade_no": "15112496832609",
    "customs_code":"GUANGZHOU",
    "amount":100,
    "transport_amount": 10,
    "is_split": true,
    "sub_order_no": "123456",
    "extra":{
        "pay_account": "1234567890",
        "certif_type": "02",
        "customer_name": "A Name",
        "certif_id": "ID Card No",
        "tax_amount":"10"
    }
}'

返回示例

{
    "id": "14201607013878045463",
    "object": "customs",
    "app": "app_LibTW1n1SOq9Pin1",
    "charge_id": "ch_L8qn10mLmr1GS8e5OODmHaL4",
    "channel": "alipay",
    "trade_no": "15112496832609",
    "customs_code": "GUANGZHOU",
    "amount": 100,
    "status": "succeeded",
    "created": 1410834527,
    "time_succeeded": 1410838127,
    "failure_code": null,
    "failure_msg": null,
    "transaction_no": "201609061456194799218",
    "extra":{}
}

查询报关接口

通过 customs 对象的 id 查询一个已创建的 customs 对象。通过查询接口确认报关的状态。

请求参数
id required 报关对象 id

返回

返回一个已存在的 customs 对象或者一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/customs/{CUSTOMS_ID}

请求示例

curl https://api.pingxx.com/v1/customs/14201607013878045463 \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \

返回示例

报关成功:
{
    "id": "14201607013878045463",
    "object": "customs",
    "app": "app_LibTW1n1SOq9Pin1",
    "charge_id": "ch_L8qn10mLmr1GS8e5OODmHaL4",
    "channel": "alipay",
    "trade_no": "15112496832609",
    "customs_code": "GUANGZHOU",
    "amount": 100,
    "status": "succeeded",
    "created": 1410834527,
    "time_succeeded": 1410838127,
    "failure_code": null,
    "failure_msg": null,
    "transaction_no": "201609061456194799218",
    "extra":{}
}
报关失败:
{
    "id": "14201607013878045463",
    "object": "customs",
    "app": "app_LibTW1n1SOq9Pin1",
    "charge_id": "ch_L8qn10mLmr1GS8e5OODmHaL4",
    "channel": "alipay",
    "trade_no": "15112496832609",
    "customs_code": "GUANGZHOU",
    "amount": 100,
    "status": "failed",
    "created": 1410834527,
    "failure_msg": "报关失败",
    "transaction_no": null,
    "extra":{}
}

Customs 相关的 Event 类型

该类型的 Event 对象会在 Customs 付款成功后触发,以 Webhooks 形式发送至客户配置的 Webhooks URL 。详情请参考 Events 事件

事件类型
customs.succeeded 报关对象,报关成功时触发。

示例对象

 {
    "id": "evt_14201611031154010770",
    "created": 1478145460,
    "livemode": true,
    "type": "customs.succeeded",
    "data": {
        "object": {
        "amount": 999999,
        "app_id": "app_LibTW1n1xxxxxxxx",
        "channel": "upacp",
        "charge_id": "ch_XLGWTCnn5iPCWz0LK4yjfbv1",
        "created": 1478145241,
        "customs_code": "GUANGZHOU",
            "extra": {
                "certif_id": "41282119910910xxxx",
                "certif_type": "01",
                "customer_name": "张小明",
                "pay_account": "张小明",
                "tax_amount": "101"
              },
        "id": "14201611031154019772",
        "is_split": true,
        "object": "customs",
        "status": "succeeded",
        "sub_order_no": "P327932738",
        "time_succeeded": 1478145460,
        "trade_no": "37878347380",
        "transaction_no": "12345678",
        "transport_amount": 0
        }
    },
        "object": "event",
        "request": "",
        "pending_webhooks": 0
}

Events 事件

为了便于客户系统或者第三方系统处理客户的交易信息,Ping++ 系统支持 Webhooks 功能,可以按照客户要求把特定的事件结果推送到指定的地址以便于客户做后续处理。目前支持的事件包括周期性交易汇总信息、支付结果、红包结果、企业转账结果和退款结果。 以下是关于接收 Webhooks 通知的说明:

  • Webhooks 是 Ping++ 和你服务器间的交互,相比页面跳转同步通知可以在页面上显示出来,这种交互方式是不可见的。
  • Webhooks 通知是以 POST 形式发送的 JSON ,放在请求的 body 里,内容是 Event 对象。
  • 你需要监听并接收 Webhooks 通知,接收到 Webhooks 后需要返回服务器状态码 2xx 表示接收成功,否则请返回状态码 500。
  • 若返回的服务器状态码不是 2xx,Ping++ 服务器会在 25 小时内向你的服务器不断重发通知,最多 10 次。Webhooks 首次是即时推送,重试通知时间间隔为 5s、10s、2min、5min、10min、30min、1h、2h、6h、15h,直到你正确回复状态 2xx 或者超过最大重发次数,Ping++ 将不再发送。

其中 Event 对象属性定义如下。

属性
id string 事件对象 id ,由 Ping++ 生成,28 位长度字符串。
object string 值为 "event"。
livemode boolean 事件是否发生在生产环境。
created timestamp 事件发生的时间。
pending_webhooks int 推送未成功的 webhooks 数量。
type string 事件类型,详见 事件类型
request string API Request ID。值 "null" 表示该事件不是由 API 请求触发的。
data hash 绑定在事件上的数据对象,具体参考下表 data 参数说明。
data 参数
object hash
previous_attributes hash 绑定对象属性变化之前的值。只有 *.updated 事件有这个属性。

示例对象

{
   "id": "evt_la06CoQAiPojSgJKe5gt3nwq",
   "created": 1427555016,
   "livemode": false,
   "type": "summary.weekly.available",
   "data": {
       "object": {
           "app_id": "app_b94eHsO1avrDyL8S",
           "object": "app_weekly_summary",
           "app_display_name": "App Name",
           "created": 1425830460,
           "summary_from": 1425225600,
           "summary_to": 1425830399,
           "charges_amount": 2000,
           "charges_count" : 200
       }
   },
   "object": "event",
   "pending_webhooks": 0,
   "request": null
}

Event 事件类型

每个事件类型的作用域都是单个应用,目前支持的事件包括:

事件类型
summary.daily.available 上一天 0 点到 23 点 59 分 59 秒的交易金额和交易量统计,在每日 04:00 点左右触发。
summary.weekly.available 上周一 0 点至上周日 23 点 59 分 59 秒的交易金额和交易量统计,在每周一 04:00 点左右触发。
summary.monthly.available 上月一日 0 点至上月末 23 点 59 分 59 秒的交易金额和交易量统计,在每月一日 04:00 点左右触发。
charge.succeeded 支付对象,支付成功时触发。
refund.succeeded 退款对象,退款成功时触发。
transfer.succeeded 企业付款对象,支付成功时触发。
transfer.failed 企业付款对象,支付失败时触发。
red_envelope.sent 红包对象,红包发送成功时触发。
red_envelope.received 红包对象,红包接收成功时触发。
batch_transfer.succeeded 批量企业付款对象,批量企业付款成功时触发。
customs.succeeded 报关对象,报关成功时触发。
batch_refund.succeeded 批量退款对象,批量退款成功时触发。
order.succeeded 订单对象,订单支付成功时触发。
order.refund.succeeded 订单退款对象,订单退款成功时触发。
balance.withdrawal.succeeded 提现对象,提现成功时触发。
balance.withdrawal.failed 提现对象,提现失败时触发。
batch_withdrawal.succeeded 批量提现对象,批量提现成功时触发。
batch_withdrawal.failed 批量提现对象,批量提现全部或部分失败时触发。
batch_withdrawal.partially_succeeded 批量提现对象,批量提现部分成功时触发。
batch_withdrawal.canceled 批量提现对象,批量提现取消时触发。
royalty_settlement.succeeded 分润结算对象,分润结算全部成功时触发。
royalty_settlement.partially_succeeded 分润结算对象,分润结算部分成功时触发。
royalty_settlement.failed 分润结算对象,分润结算全部失败时触发。
royalty_settlement.canceled 分润结算对象,分润结算全部取消时触发。
recharge.succeeded 充值对象,充值成功时触发。
recharge.refund.succeeded 充值对象,充值退款成功时触发。

右边是具体的 json 字符串展示针对 App 对象的各交易汇总事件类型的数据格式。 当事件类型为 summary.daily.availablesummary.weekly.availablesummary.monthly.available 的时候, data 中的 objectApp 对象。

App 日/周/月统计对象主要字段定义如下:
app_id 应用 ID
object 对象类型。
app_display_name 应用名称。
created 创建时间(timestamp)。
summary_from 统计起始时间(timestamp)。
summary_to 统计终止时间(timestamp)。
charges_amount 交易金额(单位:分)。
charges_count 交易量(笔)。

当事件类型为 charge.succeededrefund.succeededtransfer.succeededtransfer.failedcustoms.succeededbatch_transfer.succeededbatch_refund.succeededred_envelope.sentred_envelope.received 的时候,data 中的 object 分别为 chargerefundtransfercustomsbatch_transferbatch_refundred_envelope 对象。

示例对象

事件类型为 summary.daily.available :
{
    "id": "evt_ugB6x3K43D16wXCcqbplWAJo",
    "created": 1427555016,
    "livemode": false,
    "type": "summary.daily.available",
    "data": {
        "object": {
            "app_id": "app_b94eHsO1avrDyL8S",
            "object": "app_daily_summary",
            "app_display_name": "App Name",
            "created": 1425139260,
            "summary_from": 1425052800,
            "summary_to": 1425139199,
            "charges_amount": 1000,
            "charges_count" : 100
        }
    },
    "object": "event",
    "pending_webhooks": 0,
    "request": null
}
事件类型为 summary.weekly.available :
{
    "id": "evt_la06CoQAiPojSgJKe5gt3nwq",
    "created": 1427555016,
    "livemode": false,
    "type": "summary.weekly.available",
    "data": {
        "object": {
            "app_id": "app_b94eHsO1avrDyL8S",
            "object": "app_weekly_summary",
            "app_display_name": "App Name",
            "created": 1425830460,
            "summary_from": 1425225600,
            "summary_to": 1425830399,
            "charges_amount": 2000,
            "charges_count" : 200
        }
    },
    "object": "event",
    "pending_webhooks": 0,
    "request": null
}
事件类型为 summary.monthly.available :
{
    "id": "evt_hpyVxo7LNvTqS93kpJgfWAFR",
    "created": 1427555016,
    "livemode": false,
    "type": "summary.monthly.available",
    "data": {
        "object": {
            "app_id": "app_b94eHsO1avrDyL8S",
            "object": "app_monthly_summary",
            "app_display_name": "App Name",
            "created": 1425139260,
            "summary_from": 1422720000,
            "summary_to": 1425139199,
            "charges_amount": 3000,
            "charges_count" : 300
        }
    },
    "object": "event",
    "pending_webhooks": 0,
    "request": null
}
事件类型为 charge.succeeded :
{
    "id": "evt_ugB6x3K43D16wXCcqbplWAJo",
    "created": 1427555101,
    "livemode": true,
    "type": "charge.succeeded",
    "data": {
        "object": {
            "id": "ch_Xsr7u35O3m1Gw4ed2ODmi4Lw",
            "object": "charge",
            "created": 1427555076,
            "livemode": true,
            "paid": true,
            "refunded": false,
            "reversed": false,
            "app": "app_1Gqj58ynP0mHeX1q",
            "channel": "upacp",
            "order_no": "123456789",
            "client_ip": "127.0.0.1",
            "amount": 100,
            "amount_settle": 100,
            "currency": "cny",
            "subject": "Your Subject",
            "body": "Your Body",
            "extra": {},
            "time_paid": 1427555101,
            "time_expire": 1427641476,
            "time_settle": null,
            "transaction_no": "1224524301201505066067849274",
            "refunds": {
                "object": "list",
                "url": "/v1/charges/ch_L8qn10mLmr1GS8e5OODmHaL4/refunds",
                "has_more": false,
                "data": []
            },
            "amount_refunded": 0,
            "failure_code": null,
            "failure_msg": null,
            "metadata": {},
            "credential": {},
            "description": null
        }
    },
    "object": "event",
    "pending_webhooks": 0,
    "request": "iar_qH4y1KbTy5eLGm1uHSTS00s"
}
事件类型为 refund.succeeded :
{
    "id": "evt_gJKelawq06CiPojS5gt3noQA",
    "created": 1427555348,
    "livemode": true,
    "type": "refund.succeeded",
    "data": {
        "object": {
            "id": "re_SG0mnjTD3jAHimbvDKjnXLC9",
            "object": "refund",
            "order_no": "SG0mnjTD3jAHimbvDKjnXLC9",
            "amount": 100,
            "created": 1427555346,
            "succeed": true,
            "status": "succeeded",
            "time_succeed": 1427555348,
            "description": "Refund Description",
            "failure_code": null,
            "failure_msg": null,
            "metadata": {},
            "charge": "ch_Xsr7u35O3m1Gw4ed2ODmi4Lw"
        }
    },
    "object": "event",
    "pending_webhooks": 0,
    "request": "iar_Ca1Oe10OqTSOPOmzX9Hi1a5"
}
事件类型为 transfer.succeeded :
{
    "id": "evt_NMO13SJt1jrOaxRMhXC4wj0k",
    "created": 1435752329,
    "type": "transfer.succeeded",
    "livemode": true,
    "object": "event",
    "data": {
        "object": {
            "id": "tr_fXTq1OHufjHOvbDiPG0qTSiP",
            "object": "transfer",
            "type": "b2c",
            "created": 1435752318,
            "time_transferred": 1435752318,
            "livemode": true,
            "status": "paid",
            "app": "app_1234567890abcDEF",
            "channel": "wx_pub",
            "order_no": "123456789",
            "amount": 1,
            "amount_settle": 1,
            "currency": "cny",
            "recipient": "Openid",
            "description": "Your Description",
            "transaction_no": "1010018301201507010307923793",
            "extra": {
                "user_name": "User Name",
                "force_check": true
            }
        }
    },
    "pending_webhooks": 0,
    "request": "iar_TqvPiDH8SGeHm5GaTKbLuDWL"
}
事件类型为 transfer.failed :
{
    "id": "evt_NMO13SJt1jrOaxRMhXC4wjkk",
    "created": 1435752329,
    "type": "transfer.failed”,
    "livemode": true,
    "object": "event",
    "data": {
        "object": {
            "id": "tr_fXTq1OHufjHOvbDiPG0qTSiP",
            "object": "transfer",
            "type": "b2c",
            "created": 1435752318,
            "time_transferred": 1435752318,
            "livemode": true,
            "status": "failed",
            "app": "app_1234567890abcDEF",
            "channel": "wx_pub",
            "order_no": "123456789",
            "amount": 1,
            "amount_settle": 1,
            "currency": "cny",
            "recipient": "Openid",
            "description": "Your Description",
            "transaction_no": "1010018301201507010307923793",
            "extra": {
                "user_name": "User Name",
                "force_check": true
            }
        }
    },
    "pending_webhooks": 0,
    "request": "iar_TqvPiDH8SGeHm5GaTKbLuDkk"
}
事件类型为 red_envelope.sent :
{
    "id": "evt_5BpbV0tYK4ySvodDG2RT6XRq",
    "created": 1436855491,
    "type": "red_envelope.sent",
    "livemode": true,
    "object": "event",
    "data": {
        "object": {
            "id": "red_z1O8iLmXXXX5uPqLiDzLCavP",
            "object": "red_envelope",
            "created": 1436855474,
            "received": null,
            "refunded": null,
            "livemode": true,
            "status": "sent",
            "app": "app_1234567890abcDEF",
            "channel": "wx_pub",
            "order_no": "123456789",
            "transaction_no": "0010037269201507140154722852",
            "amount": 100,
            "amount_settle": 100,
            "currency": "cny",
            "recipient": "Openid",
            "subject": "Your Subject",
            "body": "Your Body",
            "description": "Your Description",
            "extra": {
                "nick_name": "Nick Name",
                "send_name": "Send Name"
            }
        }
    },
    "pending_webhooks": 0,
    "request": "iar_zjLGC8zfLOS8WPS0WLi14ynD"
}
事件类型为 red_envelope.received :
{
    "id": "evt_hMGV2eR15fMupHUdDYibhLxe",
    "object": "event",
    "type": "red_envelope.received",
    "livemode": true,
    "created": 1436753800,
    "data": {
        "object": {
            "id": "red_4qLGO84GaXHOWTSO80mLO8i9",
            "object": "red_envelope",
            "created": 1436753573,
            "received": null,
            "refunded": null,
            "livemode": true,
            "status": "received",
            "app": "app_1234567890abcDEF",
            "channel": "wx_pub",
            "order_no": "123456789",
            "transaction_no": "0010037269201507130153706663",
            "amount": 100,
            "amount_settle": 100,
            "currency": "cny",
            "recipient": "Openid",
            "subject": "Your Subject",
            "body": "Your Body",
            "description": "Your Description",
            "extra": {
                "nick_name": "Nick Name",
                "send_name": "Send Name"
            }
        }
    },
    "pending_webhooks": 0,
    "request": "iar_jf1iT0fT0a18v1u5qDvb1uDS"
}
 事件类型为 batch_transfer.succeeded :
{
    "id": "evt_ca16CoQsiP2ja1JKs5gx3j4q",
    "object": "event",
    "created": 1475924802,
    "livemode": false,
    "data": {
        "object": {
            "id": "181610101014367590",
            "object": "batch_transfer",
            "app": "app_ribgW1n2SOqcPxn1",
            "amount": 8000,
            "batch_no": "2016101010380007",
            "channel": "alipay",
            "currency": "cny",
            "created": 1476067087,
            "description": "付款说明",
            "extra": {},
            "failure_msg": null,
            "fee": 200,
            "livemode": true,
            "metadata": {},
            "recipients": [
                {
                    "account": "account01@alipay.com",
                    "amount": 5000,
                    "name": "张三",
                    "transfer": "tr_jHWfvDnTKG0SiPmbfPbHW1eH",
                    "status": "paid"
                },
                {
                    "account": "account02@alipay.com",
                    "amount": 3000,
                    "name": "李四",
                    "transfer": "tr_8u1yPK1eHWv9D08OePzDe1CK",
                    "status": "paid"
                }
            ],
            "status": "succeeded",
            "time_succeeded": 1476067147,
            "type": "b2c"
        }
    },
    "pending_webhooks": 0,
    "request": "iar_1KeD0GHi58yLfDyHK4HCOyDS",
    "type": "batch_transfer.succeeded"
}
 事件类型为 customs.succeeded :
 {
    "id": "evt_14201611031154010770",
    "created": 1478145460,
    "livemode": true,
    "type": "customs.succeeded",
    "data": {
        "object": {
        "amount": 999999,
        "app_id": "app_LibTW1n1xxxxxxxx",
        "channel": "upacp",
        "charge_id": "ch_XLGWTCnn5iPCWz0LK4yjfbv1",
        "created": 1478145241,
        "customs_code": "GUANGZHOU",
            "extra": {
                "certif_id": "41282119910910xxxx",
                "certif_type": "01",
                "customer_name": "张小明",
                "pay_account": "张小明",
                "tax_amount": "101"
              },
        "id": "14201611031154019772",
        "is_split": true,
        "object": "customs",
        "status": "succeeded",
        "sub_order_no": "P327932738",
        "time_succeeded": 1478145460,
        "trade_no": "37878347380",
        "transaction_no": "12345678",
        "transport_amount": 0
        }
    },
        "object": "event",
        "request": "",
        "pending_webhooks": 0
}
 事件类型为 batch_refund.succeeded :
 {
  "id": "evt_401170207171021000437700",
  "created": 1486458621,
  "livemode": true,
  "type": "batch_refund.succeeded",
  "data": {
      "object": {
      "app": "app_LibTW1n1SOq9Pin1",
      "batch_no": "467223445889520",
      "charges": [
        {
          "charge": "ch_Pi504CajrLyHLSCOOKpyXnX5",
          "status": "succeeded"
        },
        {
          "charge": "ch_CWDKSKbvHq981TSOO8uk0Se5",
          "status": "succeeded"
        },
        {
          "charge": "ch_9ejPy94qj519bTejT8u1X9GC",
          "status": "succeeded"
        }
      ],
      "created": 1486458591,
      "description": "Batch refund description.",
      "id": "1511702071709512304",
      "livemode": true,
      "metadata": {},
      "object": "batch_refund",
      "refund_url": null,
      "refunds": {
        "data": [
          {
            "amount": 5,
            "charge": "ch_CWDKSKbvHq983TSOO8u00Se5",
            "charge_order_no": "T170207050849Sh",
            "created": 1486458594,
            "description": "Batch refund description.",
            "failure_code": null,
            "failure_msg": null,
            "id": "re_rLWHWHKajPu9urPqvPmnrbrP",
            "metadata": {},
            "object": "refund",
            "order_no": "rLWHWHKajPu9urPqvPmnrbrP",
            "status": "succeeded",
            "succeed": true,
            "time_succeed": 1486458602,
            "transaction_no": "2000000001001702070816030296"
          },
          {
            "amount": 5,
            "charge": "ch_9ejPy94qj5u9bTej08uzX9GC",
            "charge_order_no": "T170207050840eA",
            "created": 1486458595,
            "description": "Batch refund description.",
            "failure_code": null,
            "failure_msg": null,
            "id": "re_rbTGi11yDKqP0ujnL4mnPinP",
            "metadata": {},
            "object": "refund",
            "order_no": "rbTGi11yDKqP0ujnL4mnPinP",
            "status": "succeeded",
            "succeed": true,
            "time_succeed": 1486458604,
            "transaction_no": "2700002001201700370816029893"
          },
          {
            "amount": 5,
            "charge": "ch_Pi504CajrLyHLSCOO0DyXnX5",
            "charge_order_no": "T170207050857df",
            "created": 1486458596,
            "description": "Batch refund description.",
            "failure_code": null,
            "failure_msg": null,
            "id": "re_n9SCCCy9WL00inz5WPazX94S",
            "metadata": {},
            "object": "refund",
            "order_no": "n9SCCCy9WL00inz5WPazX94S",
            "status": "succeeded",
            "succeed": true,
            "time_succeed": 1486458604,
            "transaction_no": "2000002001201702071815736474"
          }
        ],
        "has_more": false,
        "object": "list",
        "url": null
      },
      "status": "succeeded",
      "time_succeeded": 1486458621
    }
  },
  "object": "event",
  "request": "iar_rDmfnTyb5ab1z61SOO9qPSKS",
  "pending_webhooks": 0
}

事件类型为 order.succeeded:
{
    "id": "evt_hMGV2eR15fMupHUdDYibhLop",
    "object": "event",
    "type": "order.succeeded",
    "livemode": true,
    "created": 1472228975,
    "data": {
        "object": {
    "id": "2001608270000004421",
    "object": "order",
    "created": 1472228865,
    "livemode": false,
    "paid": true,
    "refunded": false,
    "status": "paid",
    "app": "app_rzj58S80W9GCCiX9",
    "uid": "15800973612",
    "merchant_order_no": "88888888888",
    "type": "purchase",
    "amount": 30,
    "coupon_amount": 20,
    "balance_amount": 10,
    "charge_amount": 0,
    "amount_refunded": 0,
    "currency": "cny",
    "subject": "test1",
    "body": "test1body1",
    "client_ip": "127.0.0.1",
    "time_paid": 1472228975,
    "time_expire": 1472282548,
    "refunds": {
        "object": "list",
        "url": "/v1/orders/2001608270000004428/refunds",
        "has_more": false,
        "data": [
        ]
    },
    "charge": null,
    "balance_transaction": "310216082700270000001101",
    "coupon": "300316082514255200000900",
    "description": "test1-description",
    "metadata": {
    },
    "charge_essentials": {
    }
    }
},
    "pending_webhooks": 0,
    "request": "iar_jf1iT0fT0a00v1u5qDvb1u00"
}
事件类型为 order_refund.succeeded:
{
    "id": "evt_hMGV2e895fMupHUdDJRJLYU00",
    "object": "event",
    "type": "order_refund.succeeded",
    "livemode": true,
    "created": 1472229338,
    "data": {
        "object": {
            "id": 2111608270000005209,
            "object": "order_refund",
            "order": "2001608270000004421",
            "app": "app_rzj58S80W9GCCiX9",
            "uid": "15800973612",
            "merchant_order_no": "88888888888",
            "amount": 10,
            "coupon_amount": 20,
            "balance_amount": 0,
            "charge_amount": 10,
            "coupon": "300316082514255200000900",
            "balance_transaction": "310216082700270000001101",
            "charge_rfd_id": null,//Ping++ charge 退款 ID
            "status": "succeeded",//退款状态
            "created": 1472229138,
            "time_succeed": 1472229338,
            "description": "test-refund",
            "metadata": {
             },
         "extra": {
                "failure_code":null,
                "failure_msg":null,
                "channel_transaction":"25134179971810968744"
         }
        }
    },
     "pending_webhooks": 0,
     "request": "iar_jf1iT0fT0a18v1u5qDvb1uDS"
}

事件类型为 balance.withdrawal.succeeded:
{
    "id": "evt_LOGV2e895fMupHUdDJRJLYU00",
    "object": "event",
    "type": "balance.withdrawal.succeeded",
    "livemode": true,
    "created": 1472649887,
    "data": {
        "object": {
            "id": "310216083121080700006701",
            "object": "withdrawal",
            "app": "app_LibTW1n1SOq9Pin1",
            "amount": 20000,
            "asset_transaction": "",
            "balance_transaction": "",
            "created": 1472648887,
            "description": "test232description",
                "extra": {
                    "account": "6225210207073918",
                    "name": "姓名",
                    "open_bank_code": "0102",
                    "prov": "上海",
                    "city": "上海"
            },
        "fee": 200,
        "livemode": true,
        "metadata":{},
        "source": null,
        "status": "succeeded",
        "time_canceled": null,
        "time_succeeded": 1472649887,
        "user_fee": 50
    }
},
        "pending_webhooks": 0,
        "request": "iar_op4iT0fT0a18v1u5qDvb1uP0"
}

事件类型为 balance.withdrawal.failed:
{
    "id": "evt_400171904244335723330503",
    "created": 1504507460,
    "livemode": true,
    "type": "balance.withdrawal.failed",
    "data": {
        "object": {
            "id": "1711709041444240785",
            "object": "withdrawal",
            "app": "app_1Gqj58ynP0mHeX1q",
            "amount": 1000,
            "asset_transaction": null,
            "balance_transaction": "601170904500051873400001",
            "channel": "wx_pub",
            "created": 1504507460,
            "description": "账户提现",
            "extra": {
                "open_id": "oYzqS4Wr5OKm9SyPWDOeb5qnzHC8"
            },
            "failure_msg": "对渠道的请求未能成功。来自渠道的错误信息:SEND_FAILED|发送失败,请更换单号重试",
            "fee": 0,
            "livemode": true,
            "metadata": {},
            "operation_url": null,
            "order_no": "3Gz64j6XYbH3ZNgEWYNL",
            "source": null,
            "status": "failed",
            "time_canceled": null,
            "time_succeeded": null,
            "user": "user_007",
            "user_fee": 0,
            "settle_account": null
        }
    },
    "object": "event",
    "pending_webhooks": 0,
    "request": "iar_GSqTeP0404KSmPmfT8in5SO4"
}

事件类型为 batch_withdrawal.succeeded:
{
    "id": "evt_400171908233490343433257",
    "created": 1504507460,
    "livemode": true,
    "type": "batch_withdrawal.succeeded",
    "data": {
        "object": {
            "id": "1911709051015122025",
            "object": "batch_withdrawal",
            "app": "app_1Gqj58ynP0mHeX1q",
            "created": 1478833871,
            "livemode": true,
            "amount": 80000,
            "amount_succeeded": 80000,
            "amount_failed": 0,
            "amount_canceled": 0,
            "count": 3,
            "count_succeeded": 3,
            "count_failed": 0,
            "count_canceled": 0,
            "fee": 600,
            "metadata": {},
            "operation_url": null,
            "status": "succeeded",
            "source": "1811709051435464631",
            "time_finished": 1504507460,
            "user_fee": 0,
            "withdrawals": {
                "object": "list",
                "url": null,
                "has_more": false,
                "data": [
                    {
                        "id": "1711711150302360654",
                        "object": "withdrawal",
                        "app": "app_1Gqj58ynP0mHeX1q",
                        "amount": 20000,
                        "asset_transaction": null,
                        "balance_transaction": "601170904500052575400001",
                        "channel": "alipay",
                        "created": 1504507360,
                        "description": "提现",
                        "extra": {
                            "account": "username@gmail.com",
                            "user_name": "姓名"
                        },
                        "failure_msg": null,
                        "fee": 200,
                        "livemode": true,
                        "metadata": {},
                        "operation_url": null,
                        "order_no": "hpZTzweXQAA1emNES2vB",
                        "source": "tr_TGS4GKTGGWb5KaHSW1fXjfzT",
                        "status": "succeeded",
                        "time_canceled": null,
                        "time_succeeded": 1504507460,
                        "user": "user_001",
                        "user_fee": 0,
                        "settle_account": null
                    },
                    { ... },
                    { ... }
                ]
            }
        }
    },
    "object": "event",
    "pending_webhooks": 0,
    "request": "iar_zvXDaT4mTWT4X50ej9K8KWz1"
}

事件类型为 batch_withdrawal.failed:
{
    "id": "evt_400171908233490343433258",
    "created": 1504507460,
    "livemode": true,
    "type": "batch_withdrawal.failed",
    "data": {
        "object": {
            "id": "1911709051015122025",
            "object": "batch_withdrawal",
            "app": "app_1Gqj58ynP0mHeX1q",
            "created": 1478833871,
            "livemode": true,
            "amount": 80000,
            "amount_succeeded": 0,
            "amount_failed": 80000,
            "amount_canceled": 0,
            "count": 3,
            "count_succeeded": 0,
            "count_failed": 3,
            "count_canceled": 0,
            "fee": 0,
            "metadata": {},
            "operation_url": null,
            "status": "failed",
            "source": "1811709051435464631",
            "time_finished": 1504507460,
            "user_fee": 0,
            "withdrawals": {
                "object": "list",
                "url": null,
                "has_more": false,
                "data": [
                    {
                        "id": "1711711150302360654",
                        "object": "withdrawal",
                        "app": "app_1Gqj58ynP0mHeX1q",
                        "amount": 20000,
                        "asset_transaction": null,
                        "balance_transaction": "601170904500052575400001",
                        "channel": "alipay",
                        "created": 1504507360,
                        "description": "提现",
                        "extra": {
                            "account": "username@gmail.com",
                            "user_name": "姓名"
                        },
                        "failure_msg": "对渠道的请求未能成功。来自渠道的错误信息:SEND_FAILED|发送失败,请更换单号重试",
                        "fee": 200,
                        "livemode": true,
                        "metadata": {},
                        "operation_url": null,
                        "order_no": "hpZTzweXQAA1emNES2vB",
                        "source": null,
                        "status": "failed",
                        "time_canceled": null,
                        "time_succeeded": null,
                        "user": "user_001",
                        "user_fee": 0,
                        "settle_account": null
                    },
                    { ... },
                    { ... }
                ]
            }
        }
    },
    "object": "event",
    "pending_webhooks": 0,
    "request": "iar_zbrbnHzz1eP4Pyr10O584eD4"
}

事件类型为 batch_withdrawal.partially_succeeded:
{
    "id": "evt_400171908233490343433357",
    "created": 1504507460,
    "livemode": true,
    "type": "batch_withdrawal.partially_succeeded",
    "data": {
        "object": {
            "id": "1911709051015122025",
            "object": "batch_withdrawal",
            "app": "app_1Gqj58ynP0mHeX1q",
            "created": 1478833871,
            "livemode": true,
            "amount": 80000,
            "amount_succeeded": 60000,
            "amount_failed": 20000,
            "amount_canceled": 0,
            "count": 3,
            "count_succeeded": 2,
            "count_failed": 1,
            "count_canceled": 0,
            "fee": 600,
            "metadata": {},
            "operation_url": null,
            "status": "partially_succeeded",
            "source": "1811709051435464631",
            "time_finished": 1504507460,
            "user_fee": 0,
            "withdrawals": {
                "object": "list",
                "url": null,
                "has_more": false,
                "data": [
                    {
                        "id": "1711711150302360654",
                        "object": "withdrawal",
                        "app": "app_1Gqj58ynP0mHeX1q",
                        "amount": 20000,
                        "asset_transaction": null,
                        "balance_transaction": "601170904500052575400001",
                        "channel": "alipay",
                        "created": 1504507360,
                        "description": "提现",
                        "extra": {
                            "account": "username@gmail.com",
                            "user_name": "姓名"
                        },
                        "failure_msg": null,
                        "fee": 200,
                        "livemode": true,
                        "metadata": {},
                        "operation_url": null,
                        "order_no": "hpZTzweXQAA1emNES2vB",
                        "source": "tr_SeDmnHHmDG4KivzDK44aXTW1",
                        "status": "succeeded",
                        "time_canceled": null,
                        "time_succeeded": 1504507460,
                        "user": "user_001",
                        "user_fee": 0,
                        "settle_account": null
                    },
                    { ... },
                    { ... }
                ]
            }
        }
    },
    "object": "event",
    "pending_webhooks": 0,
    "request": "iar_rvrHqHS4u9WLrPaDGKXzfbbL"
}

事件类型为 batch_withdrawal.canceled:
{
    "id": "evt_400171908233490343433259",
    "created": 1504507460,
    "livemode": true,
    "type": "batch_withdrawal.canceled",
    "data": {
        "object": {
            "id": "1911709051015122025",
            "object": "batch_withdrawal",
            "app": "app_1Gqj58ynP0mHeX1q",
            "created": 1478833871,
            "livemode": true,
            "amount": 80000,
            "amount_succeeded": 0,
            "amount_failed": 0,
            "amount_canceled": 80000,
            "count": 3,
            "count_succeeded": 0,
            "count_failed": 0,
            "count_canceled": 3,
            "fee": 0,
            "metadata": {},
            "operation_url": null,
            "status": "canceled",
            "source": null,
            "time_finished": 1504507460,
            "user_fee": 0,
            "withdrawals": {
                "object": "list",
                "url": null,
                "has_more": false,
                "data": [
                    {
                        "id": "1711711150302360654",
                        "object": "withdrawal",
                        "app": "app_1Gqj58ynP0mHeX1q",
                        "amount": 20000,
                        "asset_transaction": null,
                        "balance_transaction": "601170904500052575400001",
                        "channel": "alipay",
                        "created": 1504507360,
                        "description": "提现",
                        "extra": {
                            "account": "username@gmail.com",
                            "user_name": "姓名"
                        },
                        "failure_msg": null,
                        "fee": 200,
                        "livemode": true,
                        "metadata": {},
                        "operation_url": null,
                        "order_no": "hpZTzweXQAA1emNES2vB",
                        "source": null,
                        "status": "succeeded",
                        "time_canceled": 1504507460,
                        "time_succeeded": null,
                        "user": "user_001",
                        "user_fee": 0,
                        "settle_account": null
                    },
                    { ... },
                    { ... }
                ]
            }
        }
    },
    "object": "event",
    "pending_webhooks": 0,
    "request": "iar_rDujP4ePSinHXbDqXH5KSO0O"
}

事件类型为 royalty_settlement.succeeded:
{
    "id": "evt_lqVSy5gbL0A68pS8YKvJzdWA",
    "created": 1430915345,
    "livemode": true,
    "object": "event",
    "data": {
        "object": {
            "id": "170302171104000011",
            "object": "royalty_settlement",
            "payer_app": "app_1Gqj58ynP0mHeX1q",
            "amount": 1,
            "amount_canceled": 0,
            "amount_failed": 0,
            "amount_succeeded": 1,
            "count": 1,
            "count_canceled": 0,
            "count_failed": 0,
            "count_succeeded": 1,
            "created": 1488445864,
            "fee": 0,
            "livemode": true,
            "metadata": {},
            "method": "unionpay",
            "operation_url": null,
            "royalty_transactions": {
                "object": "list",
                "page_number": 1,
                "total_page": 1,
                "url": "/v1/royalty_transactions",
                "data": [
                    {
                        "id": "170302171104000011",
                        "object": "royalty_transaction",
                        "amount": 1,
                        "created": 1430915345,
                        "status": "succeeded",
                        "settle_account": "320217022818142300000901",
                        "source_user": "user_002",
                        "recipient_app": null,
                        "royalty_settlement": "170302171104000011"
                    }
                ]
            },
            "status": "succeeded",
            "time_finished": null
        }
    },
    "pending_webhooks": 0,
    "type": "royalty_settlement.succeeded",
    "request": "iar_0K8m90CCeDK8PabXD00yfTq"
}

事件类型为 royalty_settlement.failed:
{
    "id": "evt_lqVSy5gbL0A68pS8YKvJzdWA",
    "created": 1430915345,
    "livemode": true,
    "object": "event",
    "data": {
        "object": {
            "id": "170302171104000011",
            "object": "royalty_settlement",
            "payer_app": "app_1Gqj58ynP0mHeX1q",
            "amount": 1,
            "amount_canceled": 0,
            "amount_failed": 1,
            "amount_succeeded": 0,
            "count": 1,
            "count_canceled": 0,
            "count_failed": 1,
            "count_succeeded": 0,
            "created": 1488445864,
            "fee": 0,
            "livemode": true,
            "metadata": {},
            "method": "unionpay",
            "operation_url": null,
            "royalty_transactions": {
                "object": "list",
                "page_number": 1,
                "total_page": 1,
                "url": "/v1/royalty_transactions",
                "data": [
                    {
                        "id": "170302171104000011",
                        "object": "royalty_transaction",
                        "amount": 1,
                        "created": 1430915345,
                        "status": "failed",
                        "settle_account": "320217022818142300000901",
                        "source_user": "user_002",
                        "recipient_app": null,
                        "royalty_settlement": "170302171104000011"
                    }
                ]
            },
            "status": "failed",
            "time_finished": null
        }
    },
    "pending_webhooks": 0,
    "type": "royalty_settlement.failed",
    "request": "iar_0K8m90CCeDK8PabXD00yfTq"
}

事件类型为 royalty_settlement.partially_succeeded:
{
  "id": "evt_401170321172440000291102",
  "created": 1490088123,
  "livemode": true,
  "type": "royalty_settlement.partially_succeeded",
  "data": {
    "object": {
      "id": "431170321171500001",
      "object": "royalty_settlement",
      "payer_app": "app_LibTW1n1SOq9Pin1",
      "created": 1490087747,
      "livemode": true,
      "method": "alipay",
      "amount": 4,
      "amount_succeeded": 1,
      "amount_failed": 3,
      "amount_canceled": 0,
      "count": 2,
      "count_succeeded": 1,
      "count_failed": 1,
      "count_canceled": 0,
      "time_finished": 1490088123,
      "fee": 100,
      "metadata": {
        "userStr": "KTs/YDg3ZFUFONZUC10SuA=="
      },
      "description": null,
      "operation_url": null,
      "status": "partially_succeeded",
      "royalty_transactions": {
        "object": "list",
        "url": "/v1/royalty_transactions",
        "data": [
          {
            "id": "441170321171500001",
            "object": "royalty_transaction",
            "amount": 3,
            "status": "failed",
            "settle_account": "333333032117170500001234",
            "source_user": "uid@pinpula.com",
            "recipient_app": null,
            "royalty_settlement": "431170321171500001",
            "created": 1490087905
          },
          {
            "id": "441170321171500002",
            "object": "royalty_transaction",
            "amount": 1,
            "status": "succeeded",
            "settle_account": "333333032117170500001234",
            "source_user": "uid@pinpula.com",
            "recipient_app": null,
            "royalty_settlement": "431170321171500001",
            "created": 1490087905
          }
        ],
        "has_more": false
      }
    }
  },
  "object": "event",
  "request": "iar_uPynnTSmDiT4rPqn9CP8OKCS",
  "pending_webhooks": 0
}

事件类型为 royalty_settlement.canceled:
{
    "id": "evt_lqVSy5gbL0A68pS8YKvJzdWZ",
    "created": 1430915345,
    "livemode": true,
    "object": "event",
    "data": {
        "object": {
            "id": "170302171104000011",
            "object": "royalty_settlement",
            "payer_app": "app_1Gqj58ynP0mHeX1q",
            "amount": 1,
            "amount_canceled": 1,
            "amount_failed": 0,
            "amount_succeeded": 0,
            "count": 1,
            "count_canceled": 1,
            "count_failed": 0,
            "count_succeeded": 0,
            "created": 1488445864,
            "fee": 0,
            "livemode": true,
            "metadata": {},
            "method": "unionpay",
            "operation_url": null,
            "royalty_transactions": {
                "object": "list",
                "page_number": 1,
                "total_page": 1,
                "url": "/v1/royalty_transactions",
                "data": [
                    {
                        "id": "170302171104000011",
                        "object": "royalty_transaction",
                        "amount": 1,
                        "created": 1430915345,
                        "status": "canceled",
                        "settle_account": "320217022818142300000901",
                        "source_user": "user_002",
                        "recipient_app": null,
                        "royalty_settlement": "170302171104000011"
                    }
                ]
            },
            "status": "canceled",
            "time_finished": null
        }
    },
    "pending_webhooks": 0,
    "type": "royalty_settlement.canceled",
    "request": "iar_0K8m90CCeDK8PabXD00yfTq"
}

事件类型为 recharge.succeeded:
{
    "id": "evt_400171904343603445333057",
    "created": 1504507460,
    "livemode": true,
    "type": "recharge.succeeded",
    "data": {
        "object": {
            "id": "221170903625155317880001",
            "object": "recharge",
            "app": "app_1Gqj58ynP0mHeX1q",
            "created": 1504408953,
            "livemode": true,
            "amount": 4950,
            "succeeded": true,
            "time_succeeded": 1504408993,
            "refunded": false,
            "user": "user_007",
            "from": "user_007",
            "user_fee": 50,
            "charge": {
                "id": "ch_XfbnHGLGi5i9Su9qXLu90488",
                "object": "charge",
                "created": 1504408953,
                "livemode": false,
                "paid": true,
                "refunded": true,
                "reversed": false,
                "app": "app_1Gqj58ynP0mHeX1q",
                "channel": "upacp",
                "order_no": "201709031102300167",
                "client_ip": "127.0.0.1",
                "amount": 5000,
                "amount_settle": 4970,
                "currency": "cny",
                "subject": "Your Subject",
                "body": "Your Body",
                "extra": {},
                "time_paid": 1504408993,
                "time_expire": 1504409953,
                "time_settle": null,
                "transaction_no": "201709031102300167211",
                "refunds": {
                    "object": "list",
                    "url": "/v1/charges/ch_XfbnHGLGi5i9Su9qXLu90488/refunds",
                    "has_more": false,
                    "data": []
                },
                "amount_refunded": 0,
                "failure_code": null,
                "failure_msg": null,
                "metadata": {},
                "credential": {},
                "description": "Your Description"
            },
            "balance_bonus": null,
            "balance_transaction": "601170903591811719520000",
            "description": "Your Description",
            "metadata": {}
        }
    },
    "object": "event",
    "pending_webhooks": 0,
    "request": "iar_Hm5SyPH8GGmPT80mfL4CWvj9"
}

事件类型为 recharge.refund.succeeded:
{
    "id": "evt_400171904345603445333057",
    "created": 1504507460,
    "livemode": true,
    "type": "recharge.refund.succeeded",
    "data": {
        "object": {
            "id": "221170903625155317880001",
            "object": "recharge",
            "app": "app_1Gqj58ynP0mHeX1q",
            "created": 1504408953,
            "livemode": true,
            "amount": 4950,
            "succeeded": true,
            "time_succeeded": 1504408993,
            "refunded": true,
            "user": "user_007",
            "from": "user_007",
            "user_fee": 50,
            "charge": {
                "id": "ch_XfbnHGLGi5i9Su9qXLu90488",
                "object": "charge",
                "created": 1504408953,
                "livemode": true,
                "paid": true,
                "refunded": true,
                "reversed": false,
                "app": "app_1Gqj58ynP0mHeX1q",
                "channel": "upacp",
                "order_no": "201709031102300167",
                "client_ip": "127.0.0.1",
                "amount": 5000,
                "amount_settle": 4970,
                "currency": "cny",
                "subject": "Your Subject",
                "body": "Your Body",
                "extra": {},
                "time_paid": 1504408993,
                "time_expire": 1504409953,
                "time_settle": null,
                "transaction_no": "201709031102300167211",
                "refunds": {
                    "object": "list",
                    "url": "/v1/charges/ch_XfbnHGLGi5i9Su9qXLu90488/refunds",
                    "has_more": false,
                    "data": [
                        {
                            "id": "re_rHuXb9nD0qvHG4ifnHHmzvX1",
                            "object": "refund",
                            "order_no": "rHuXb9nD0qvHG4ifnHHmzvX1",
                            "amount": 5000,
                            "created": 1504410993,
                            "succeed": true,
                            "status": "succeeded",
                            "time_succeed": 1504410993,
                            "description": "充值退款",
                            "failure_code": null,
                            "failure_msg": null,
                            "metadata": {},
                            "charge": "ch_XfbnHGLGi5i9Su9qXLu90488",
                            "charge_order_no": "201709031102300167",
                            "transaction_no": "2017090421001004670247373863",
                            "extra": {}
                        }
                    ]
                },
                "amount_refunded": 5000,
                "failure_code": null,
                "failure_msg": null,
                "metadata": {},
                "credential": {},
                "description": "Your Description"
            },
            "balance_bonus": null,
            "balance_transaction": "601170903591811719520000",
            "description": "Your Description",
            "metadata": {}
        }
    },
    "object": "event",
    "pending_webhooks": 0,
    "request": "iar_zHq9GCaTGGSOOGePOKjfnjPO"
}

查询 Event 对象

通过 event 对象的 id 查询一个已创建的 event 对象。

请求参数
id required 事件 id

返回

返回一个已存在的 event 对象或者一个错误,详见 错误

定义

GET https://api.pingxx.com/v1/events/{EVENT_ID}

请求示例

curl https://api.pingxx.com/v1/events/evt_lqVSy5gbL0A68pS8YKvJzdWZ \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC:

返回示例

{
    "id": "evt_lqVSy5gbL0A68pS8YKvJzdWZ",
    "created": 1430915345,
    "livemode": true,
    "object": "event",
    "data": {
        "object": {
            "id": "ch_ebT0y9iPGCKCL0aPy9X1WLmT",
            "object": "charge",
            "created": 1430915284,
            "livemode": true,
            "paid": true,
            "refunded": false,
            "reversed": false,
            "app": "app_Xz9iXLn9ebX1SOe1",
            "channel": "wx",
            "order_no": "as223af2ds",
            "client_ip": "127.0.0.1",
            "amount": 100,
            "amount_settle": 100,
            "currency": "cny",
            "subject": "Your Subject",
            "body": "Your Body",
            "extra": [],
            "time_paid": 1430915344,
            "time_expire": 1431001684,
            "time_settle": null,
            "transaction_no": "1001680021201505060112980000",
            "refunds": {
                "object": "list",
                "url": "/v1/charges/ch_ebT0y9iPGCKCL0aPy9X1WLmT/refunds",
                "has_more": false,
                "data": []
            },
            "amount_refunded": 0,
            "failure_code": null,
            "failure_msg": null,
            "metadata": [],
            "credential": [],
            "description": null
        }
    },
    "pending_webhooks": 0,
    "type": "charge.succeeded",
    "request": "iar_0K8m90CCeDK8PabXD00yfTq"
}

支付渠道属性值

下面为支付渠道 channel 属性值和其对应的支付渠道名称。

channel属性值 支付渠道名称
alipay 支付宝 APP 支付
alipay_wap 支付宝手机网页支付
alipay_qr 支付宝当面付,即支付宝扫码支付
alipay_scan 支付宝条码支付
alipay_pc_direct 支付宝电脑网站支付
bfb 百度钱包移动快捷支付,即百度钱包 APP 支付
bfb_wap 百度钱包手机网页支付
cp_b2b 银联企业网银支付,即 B2B 银联 PC 网页支付
upacp 银联支付,即银联 APP 支付(2015 年 1 月 1 日后的银联新商户使用。若有疑问,请与 Ping++ 或者相关的收单行联系)
upacp_wap 银联手机网页支付(2015 年 1 月 1 日后的银联新商户使用。若有疑问,请与 Ping++ 或者相关的收单行联系)
upacp_pc 银联网关支付,即银联 PC 网页支付
wx 微信 APP 支付
wx_pub 微信公众号支付
wx_wap 微信 H5 支付
wx_lite 微信小程序支付
wx_pub_qr 微信公众号扫码支付
wx_pub_scan 微信公众号刷卡支付
yeepay_wap 易宝手机网页支付
jdpay_wap 京东手机网页支付
fqlpay_wap 分期乐支付
qgbc_wap 量化派支付
cmb_wallet 招行一网通
applepay_upacp Apple Pay
mmdpay_wap 么么贷
qpay QQ 钱包支付
qpay_pub QQ 钱包公众号支付
balance 余额

支付渠道 extra 参数说明

特定渠道发起交易时需要的额外参数,以及部分渠道支付成功返回的额外参数。bfbcp_b2b 渠道不需要 extra 参数。

alipay 支付宝 APP 支付

extra 参数 说明
extern_token optional, string 仅适用于支付宝 1.0 接口。开放平台返回的包含账户信息的 token(授权令牌,商户在一定时间内对支付宝某些服务的访问权限)。通过授权登录后获取的 alipay_open_id ,作为该参数的 value ,登录授权账户即会为支付账户,32 位字符串。
hb_fq_num optional,int 仅适用于支付宝 2.0 接口,使用花呗分期要进行的分期数,必须根据支付宝签约的分期数填写,可选值 3、6、12 (支付宝 2.0 参数传入有效,hb_fq_num 和 hb_fq_seller_percent 必须同时传入有效)。
hb_fq_seller_percent optional,int 仅适用于支付宝 2.0 接口,使用花呗分期需要卖家承担的手续费比例的百分值,传入100代表100%,可选值0、100(支付宝2.0参数传入有效,hb_fq_num和hb_fq_seller_percent必须同时传入有效)。
disable_pay_channels optional,string 仅适用于支付宝 2.0 接口,禁用支付渠道,用户不可用指定渠道支付,当有多个付款渠道时用,分隔(如moneyFund,credit_group),支付渠道相关值参考下方 disable_pay_channels 参数说明。
sys_service_provider_id optional,string 仅适用于支付宝 2.0 接口,系统商编号,该参数作为系统商返佣数据提取的依据,请填写系统商签约协议的 PID。
rn_check optional,string 适用于支付宝 1.0,是否发起实名校验,T 代表发起实名校验;F 代表不发起实名校验。
need_buyer_real_named optional,string 适用于支付宝 2.0 接口,是否发起实名校验,T 代表发起实名校验;F 代表不发起实名校验。
buyer_account response-only,string 适用于支付宝 2.0 接口,支付完成将额外返回付款用户的支付宝账号。
fund_bill_list response-only,array 适用于支付宝 2.0 接口,交易支付使用的资金渠道,详见下方的 fund_bill_list 渠道透传返回。
buyer_user_id response-only,string 适用于支付宝 2.0 接口,买家在支付宝的用户 id 。
voucher_detail_list response-only,array 适用于支付宝 2.0 接口,本交易支付时使用的所有优惠券信息,详见下方的 voucher_detail_list 渠道透传返回。

alipay_wap 支付宝手机网页支付

extra 参数 说明
success_url required string 支付成功的回调地址。
cancel_url optional, string 支付取消的回调地址, app_pay 为 true 时,该字段无效。
new_version optional,boolean 2016 年 6 月 16 日之前登录 Ping++ 管理平台填写支付宝手机网站的渠道参数的旧接口商户,需要更新接口时设置此参数值为true,6月16号后接入的新接口商户不需要设置该参数。
app_pay optional,boolean 是否使用支付宝客户端支付,该参数为 true 时,调用客户端支付。
need_buyer_real_named optional,string 适用于支付宝 2.0 接口,是否发起实名校验,T 代表发起实名校验;F 代表不发起实名校验。
extern_token optional, string 仅适用于支付宝 1.0 接口。开放平台返回的包含账户信息的 token(授权令牌,商户在一定时间内对支付宝某些服务的访问权限)。通过授权登录后获取的 alipay_open_id ,作为该参数的 value ,登录授权账户即会为支付账户,32 位字符串。
hb_fq_num optional,int 仅适用于支付宝 2.0 接口,使用花呗分期要进行的分期数,必须根据支付宝签约的分期数填写,可选值 3、6、12 (支付宝 .0 参数传入有效,hb_fq_num 和hb_fq_seller_percent 必须同时传入有效)。
hb_fq_seller_percent optional,int 仅适用于支付宝 2.0 接口,使用花呗分期需要卖家承担的手续费比例的百分值,传入100代表100%,可选值0、100(支付宝2.0参数传入有效,hb_fq_num 和 hb_fq_seller_percent必须同时传入有效)。
disable_pay_channels optional,string 仅适用于支付宝 2.0 接口,禁用支付渠道,用户不可用指定渠道支付,当有多个付款渠道时用,分隔(如 moneyFund,credit_group),支付渠道相关值参考下方disable_pay_channels 参数说明。
sys_service_provider_id optional,string 仅适用于支付宝 2.0 接口,系统商编号,该参数作为系统商返佣数据提取的依据,请填写系统商签约协议的 PID。
buyer_account response-only, string 适用于支付宝 2.0 接口,支付完成将额外返回付款用户的支付宝账号。
fund_bill_list response-only,array 适用于支付宝 2.0 接口,交易支付使用的资金渠道,详见下方的 fund_bill_list 渠道透传返回。
buyer_user_id response-only,string 适用于支付宝 2.0 接口,买家在支付宝的用户 id 。
voucher_detail_list response-only,array 适用于支付宝 2.0 接口,本交易支付时使用的所有优惠券信息,详见下方的 voucher_detail_list 渠道透传返回。

alipay_qr 支付宝当面付(扫码支付)

extra 参数 说明
hb_fq_num optional,int 使用花呗分期要进行的分期数,必须根据支付宝签约的分期数填写,可选值3、6、12 (支付宝 2.0 参数传入有效,hb_fq_num 和 hb_fq_seller_percent 必须同时传入有效)。
hb_fq_seller_percent optional,int 使用花呗分期需要卖家承担的手续费比例的百分值,传入100代表100%,可选值0、100(支付宝 2.0 参数传入有效,hb_fq_num 和 hb_fq_seller_percent必须同时传入有效)。
sys_service_provider_id optional,string 系统商编号,该参数作为系统商返佣数据提取的依据,请填写系统商签约协议的 PID。
disable_pay_channels optional,string 禁用支付渠道,用户不可用指定渠道支付,当有多个付款渠道时用 , 分隔(如moneyFund,credit_group),支付渠道相关值参考下方 disable_pay_channels 参数说明。
trade_create boolean,string 是否使用口碑支付,true 则使用口碑支付。
buyer_account optional,string 支付宝账号。当 trade_create 为 true 时,buyer_account 和 buyer_user_id 必填一个;当 trade_create 为 false 时,此参数无需填写,会在支付完成后额外返回。
buyer_user_id optional,string 买家的支付宝唯一用户 id,2088 开头的 16 位纯数字。当 trade_create 为 true 时,buyer_account 和 buyer_user_id 必填一个;当 trade_create 为 false 时,此参数无需填写,会在支付完成后额外返回。
fund_bill_list response-only,array 交易支付使用的资金渠道,详见下方的 fund_bill_list 渠道透传返回。
voucher_detail_list response-only,array 本交易支付时使用的所有优惠券信息,详见下方的 voucher_detail_list 渠道透传返回。

alipay_scan 支付宝条码支付

extra 参数 说明
scan_code required string 客户端软件中展示的条码值,1-32位。
terminal_id required string 终端号(可包含字母、数字、下划线、中划线),1-32位。
goods_list optional,list 订单包含的商品列表信息(json 字符串的长度为1~8000)。
operator_id optional,string 商户操作员编号(可包含字母、数字、下划线、中划线),1-28位。
store_id optional,string 商户门店编号(可包含字母、数字、下划线、中划线),1-32位。
sys_service_provider_id optional,string 系统商编号,1-64位。

goods_list 参数说明

参数 说明
goods_id required string 商品的编号,1-32位。
goods_name required string 商品名称,1-256位。
quantity required int 商品数量,1-10位。
price required string 商品单价,单位为元,1-9位。
goods_category optional,string 商品类目,1-24位。
body optional,string 商品描述信息,1-1000位。
show_url optional,string 商品的展示地址,1-400位。

alipay_pc_direct 支付宝电脑网站支付

extra 参数 说明
success_url required string 支付成功的回调地址。
enable_anti_phishing_key optional,boolean 是否开启防钓鱼网站的验证参数(如果已申请开通防钓鱼时间戳验证,则此字段必填)
hb_fq_num optional,int 仅适用于支付宝 2.0 接口,使用花呗分期要进行的分期数,必须根据支付宝签约的分期数填写,可选值 3、6、12 (支付宝 2.0 参数传入有效,hb_fq_num 和 hb_fq_seller_percent 必须同时传入有效)。
hb_fq_seller_percent optional,int 仅适用于支付宝 2.0 接口,使用花呗分期需要卖家承担的手续费比例的百分值,传入100代表100%,可选值0、100(支付宝2.0参数传入有效,hb_fq_num和hb_fq_seller_percent必须同时传入有效)。
disable_pay_channels optional,string 仅适用于支付宝 2.0 接口,禁用支付渠道,用户不可用指定渠道支付,当有多个付款渠道时用,分隔(如moneyFund,credit_group),支付渠道相关值参考下方 disable_pay_channels 参数说明。
sys_service_provider_id optional,string 仅适用于支付宝 2.0 接口,系统商编号,该参数作为系统商返佣数据提取的依据,请填写系统商签约协议的 PID。
exter_invoke_ip optional, string 客户端 IP ,用户在创建交易时,该用户当前所使用机器的IP(如果商户申请后台开通防钓鱼IP地址检查选项,此字段必填,校验用)。
buyer_account response-only,string 适用于支付宝 2.0 接口,支付完成将额外返回付款用户的支付宝账号。
fund_bill_list response-only,array 适用于支付宝 2.0 接口,交易支付使用的资金渠道,详见下方的 fund_bill_list 渠道透传返回。
buyer_user_id response-only,string 适用于支付宝 2.0 接口,买家在支付宝的用户 id 。
voucher_detail_list response-only,array 适用于支付宝 2.0 接口,本交易支付时使用的所有优惠券信息,详见下方的 voucher_detail_list 渠道透传返回。

fund_bill_list 渠道返回参数

extra 参数 说明
fund_channel response-only,string 仅适用于支付宝 2.0 接口,交易使用的资金渠道,详见 alipay 支付渠道列表。
amount response-only,string 仅适用于支付宝 2.0 接口,该支付工具类型所使用的金额。
real_amount response-only,string 仅适用于支付宝 2.0 接口,渠道实际付款金额。

alipay 支付渠道列表

extra 参数 说明
COUPON 支付宝红包
ALIPAYACCOUNT 支付宝账户
POINT 集分宝
DISCOUNT 折扣券
PCARD 预付卡
MCARD 商家储值卡
MDISCOUNT 商户优惠券
MCOUPON 商户红包
PCREDIT 蚂蚁花呗

disable_pay_channels 参数说明

extra 参数 说明
balance 余额
moneyFund 余额宝
coupon 红包
pcredit 花呗
pcreditpayInstallment 花呗分期
creditCard 信用卡
creditCardExpress 信用卡快捷
creditCardCartoon 信用卡卡通
credit_group 信用支付类型(包含信用卡卡通、信用卡快捷、花呗、花呗分期)
debitCardExpress 借记卡快捷
mcard 商户预存卡
pcard 个人预存卡
promotion 优惠(包含实时优惠+商户优惠)
voucher 营销券
point 积分
mdiscount 商户优惠
bankPay 网银

voucher_detail_list 渠道返回参数

extra 参数 说明
id response-only,string 仅适用于支付宝 2.0 接口,券 id。
name response-only,string 仅适用于支付宝 2.0 接口,券名称。
type response-only,string 仅适用于支付宝 2.0 接口,当前有三种类型: ALIPAY_FIX_VOUCHER - 全场代金券、ALIPAY_DISCOUNT_VOUCHER - 折扣券、ALIPAY_ITEM_VOUCHER - 单品优惠。注:不排除将来新增其他类型的可能,商家接入时注意兼容性避免硬编码。
amount response-only,string 仅适用于支付宝 2.0 接口,优惠券面额,它应该会等于商家出资加上其他出资方出资。
merchant_contribute response-only,string 仅适用于支付宝 2.0 接口,商家出资(特指发起交易的商家出资金额)。
other_contribute response-only,string 仅适用于支付宝 2.0 接口,其他出资方出资金额,可能是支付宝,可能是品牌商,或者其他方,也可能是他们的一起出资。
memo response-only,string 仅适用于支付宝 2.0 接口,优惠券备注信息。

bfb_wap 百度钱包手机网页支付

extra 参数 说明
result_url required string 支付完成的回调地址。
bfb_login required boolean 是否需要登录百度钱包来进行支付。

upacp 银联 APP 支付

extra 参数 说明
pay_type response-only, string 0001:认证支付 0002:快捷支付 0004:储值卡支付 0005:IC卡支付 0201:网银支付 1001:牡丹畅通卡支付 1002:中铁银通卡支付 0401:信用卡支付 0402:小额临时支付 0403:认证支付 2.0 0404:互联网订单手机支付 9000:其他无卡支付(如手机客户端支付)。
acc_no response-only, string 银行卡号(如需对返回卡号打码,可联系银联入网所在收单行提交开通申请,具体开通资料以所在收单行为准)。
pay_card_type response-only, string 00:未知 01:借记账户 02:贷记账户 03:准贷记账户 04:借贷合一账户 05:预付费账户 06:半开放预付费账户。

upacp_wap 银联全渠道手机网页支付

extra 参数 说明
result_url required string 支付完成的回调地址。
pay_type response-only, string 0001:认证支付 0002:快捷支付 0004:储值卡支付 0005:IC卡支付 0201:网银支付 1001:牡丹畅通卡支付 1002:中铁银通卡支付 0401:信用卡支付 0402:小额临时支付 0403:认证支付 2.0 0404:互联网订单手机支付 9000:其他无卡支付(如手机客户端支付)。
acc_no response-only, string 银行卡号(如需对返回卡号打码,可联系银联入网所在收单行提交开通申请,具体开通资料以所在收单行为准。)。
pay_card_type response-only, string 00:未知 01:借记账户 02:贷记账户 03:准贷记账户 04:借贷合一账户 05:预付费账户 06:半开放预付费账户。

upacp_pc 银联 PC 网页支付

extra 参数 说明
result_url required string 支付完成的回调地址。
iss_ins_code optional,string 直接跳转到银行网银,商户界面点击银行网银图标直接跳转到银行网银支付,详见下方的 iss_ins_code 字段说明。
pay_type response-only, string 0001:认证支付 0002:快捷支付 0004:储值卡支付 0005:IC卡支付 0201:网银支付 1001:牡丹畅通卡支付 1002:中铁银通卡支付 0401:信用卡支付 0402:小额临时支付 0403:认证支付 2.0 0404:互联网订单手机支付 9000:其他无卡支付(如手机客户端支付)。
acc_no response-only, string 银行卡号(如需对返回卡号打码,可联系银联入网所在收单行提交开通申请,具体开通资料以所在收单行为准。)。
pay_card_type response-only, string 00:未知 01:借记账户 02:贷记账户 03:准贷记账户 04:借贷合一账户 05:预付费账户 06:半开放预付费账户。

iss_ins_code 字段说明

支持标准网关银行列表

代码 描述
ICBC 工商银行
ABC 农业银行
BOC 中国银行(大额)
BOCSH 中国银行
CCB 建设银行
CMB 招行银行
SPDB 浦发银行
GDB 广发银行
BOCOM 交通银行
CNCB 中信银行
CMBC 民生银行
CIB 兴业银行
CEB 光大银行
HXB 华夏银行
BOS 上海银行
SRCB 上海农商
PSBC 邮政储蓄
BCCB 北京银行
BRCB 北京农商
PAB 平安银行

支持的独立借记卡网关银行列表

代码 描述
ICBCD 工商银行
CCBD 建设银行
CMBD 招行银行
SPDBD 上海浦东发展银行
GDBD 广发银行
PSBCD 邮政储蓄银行
CMBCD 民生银行
CEBD 光大银行
HXB 华夏银行
BOEAD 东亚银行
ABCD 中国农业银行

applepay_upacp Apple Pay支付

extra 参数 说明
pay_type response-only, string 0001:认证支付 0002:快捷支付 0004:储值卡支付 0005:IC卡支付 0201:网银支付 1001:牡丹畅通卡支付 1002:中铁银通卡支付 0401:信用卡支付 0402:小额临时支付 0403:认证支付 2.0 0404:互联网订单手机支付 9000:其他无卡支付(如手机客户端支付)。
acc_no response-only, string 银行卡号(如需对返回卡号打码,可联系银联入网所在收单行提交开通申请,具体开通资料以所在收单行为准。)。
pay_card_type response-only, string 00:未知 01:借记账户 02:贷记账户 03:准贷记账户 04:借贷合一账户 05:预付费账户 06:半开放预付费账户。

wx 微信支付

extra 参数 说明
limit_pay optional,string 指定支付方式,指定不能使用信用卡支付可设置为 no_credit
goods_tag optional,string 商品标记,代金券或立减优惠功能的参数。
open_id response-only, string 支付完成后额外返回付款用户的微信 open_id
bank_type response-only,string 支付完成后额外返回付款用户的付款银行类型 bank_type

wx_pub 微信公众号支付

extra 参数 说明
limit_pay optional,string 指定支付方式,指定不能使用信用卡支付可设置为 no_credit
goods_tag optional,string 商品标记,代金券或立减优惠功能的参数。
open_id required string 用户在商户 appid 下的唯一标识。
bank_type response-only, string 支付完成后额外返回付款用户的付款银行类型 bank_type

wx_pub_qr 微信公众号扫码支付

extra 参数 说明
limit_pay optional,string 指定支付方式,指定不能使用信用卡支付可设置为 no_credit
product_id required string 商品 ID,1-32 位字符串。此 id 为二维码中包含的商品 ID,商户自行维护。
goods_tag optional,string 商品标记,代金券或立减优惠功能的参数。
open_id response-only, string 支付完成后额外返回付款用户的微信 open_id
bank_type response-only, string 支付完成后额外返回付款用户的付款银行类型 bank_type

wx_pub_scan 微信公众号刷卡支付

extra 参数 说明
scan_code required string 客户端软件中展示的条码值,扫码设备扫描获取,1-32位。
terminal_id optional,string 终端号,要求不同终端此号码不一样,会显示在对账单中,如 A01SH008 等,1-8位。
limit_pay optional,string 指定支付方式,指定不能使用信用卡支付可设置为 no_credit
goods_tag optional,string 商品标记,代金券或立减优惠功能的参数,1-32位。
open_id response-only, string 用户在商户下的唯一标识。
is_subscribe response-only, string 用户是否关注公众账号,仅在公众账号类型支付有效。取值范围: Y 或者 NY 表示关注, N 表示未关注。
bank_type response-only, string 银行类型,采用字符串类型的银行标识。
settlement_total_fee response-only, int 应结订单金额,当订单使用了免充值型优惠券后返回该参数。应结订单金额 = 订单金额 - 免充值优惠券金额。
coupon_fee response-only, int 代金券金额。代金券金额 <= 订单金额,订单金额 - 代金券金额 = 现金支付金额。
cash_fee response-only, int 现金支付金额。
promotion_detail response-only, string 营销详情。

wx_wap 微信 H5 支付

extra 参数 说明
result_url optional,string 支付完成的回调地址。
goods_tag optional,string 商品标记,代金券或立减优惠功能的参数。
open_id response-only, string 支付完成后额外返回付款用户的微信 open_id
bank_type response-only, string 支付完成后额外返回付款用户的付款银行类型 bank_type

wx_lite 微信小程序支付

extra 参数 说明
limit_pay optional,string 指定支付方式,指定不能使用信用卡支付可设置为 no_credit
goods_tag optional,string 商品标记,代金券或立减优惠功能的参数。
open_id required string 用户在商户 appid 下的唯一标识。
bank_type response-only, string 支付完成后额外返回付款用户的付款银行类型 bank_type

yeepay_wap 易宝手机网页支付

extra 参数 说明
product_category required string 商品类别码,详见 易宝支付商品类型码
identity_id required string 用户标识,商户生成的用户账号唯一标识,最长 50 位字符串。
identity_type required int 用户标识类型,详见 易宝支付用户标识类型码
terminal_type required int 终端类型,对应取值 0:IMEI, 1:MAC, 2:UUID, 3:other。
terminal_id required string 终端 ID。
user_ua required string 用户使用的移动终端的 UserAgent 信息。
result_url required string 前台通知地址。

jdpay_wap 京东手机网页支付

extra 参数 说明
success_url required string 支付成功页面跳转路径。
fail_url required string 支付失败页面跳转路径。
pay_list response-only,string 支付完成后额外返回给用户的支付方式明细列表,具体参考下方 pay_list 参数说明。
token optional,string 用户交易令牌,用于识别用户信息,支付成功后会调用 success_url 返回给商户。商户可以记录这个 token 值,当用户再次支付的时候传入该 token ,用户无需再次输入银行卡信息,直接输入短信验证码进行支付。32 位字符串。
order_type optional,string 订单类型,值为0表示实物商品订单,值为 1 代表虚拟商品订单,该参数默认值为 0 。
is_mobile optional,boolean 设置是否通过手机端发起支付,值为 true 时调用手机 h5 支付页面,值为 false 时调用 PC 端支付页面,该参数默认值为 true
user_type optional,string 用户账号类型,取值只能为:BIZ。
user_id optional,string 商户的用户账号。
pay_list 参数 说明
payType response-only,int 支付方式。0:银行卡,1:白条,2:余额,3:优惠券,5:小金库,6:钢镚。
amount response-only,int 交易金额,单位为分。
currency response-only,string 交易币种,人民币为 CNY
tradeTime response-only,string 交易时间,格式为 yyyyMMddHHmmss
detail optional,hash 支付明细信息,具体参考下表 detail 参数说明。
detail 参数 说明
cardHolderName optional,string 持卡人姓名,掩码显示。(支付方式为银行卡时返回)
cardHolderMobile optional,string 持卡人手机号,掩码显示。(支付方式为银行卡时返回)
cardHolderType optional,string 证件类型。0:身份证,1:护照,2:军官证,3:士兵证,4:港奥台通行证,5:临时身份证,6:户口本,7:其它类型证件。(支付方式为银行卡时返回)
cardHolderId optional,string 身份证号,掩码显示。(支付方式为银行卡时返回)
cardNo optional,string 卡号,掩码显示。(支付方式为银行卡时返回)
bankCode optional,string 银行编码。(支付方式为银行卡时返回)
cardType optional,string 银行卡类型。1:借记卡,2:信用卡。(支付方式为银行卡时返回)
payMoney optional,string 交易金额,单位为分。

注: 对于 user_type, user_id 参数,传参存在问题请参考 帮助中心

fqlpay_wap 分期乐支付

extra 参数 说明
c_merch_id required string 子商户编号,需要提交该订单商户的所属子商户编号。
return_url optional,string 前端回调地址,交易完成跳转的链接,不能带自定义参数。

qgbc_wap 量化派支付

extra 参数 说明
phone required string 手机号码。
term optional int 分期参数,0 代表不分期,1 代表分 3 期,2 代表分 6 期,3 代表分 9 期,4 代表分 12 期。
return_url optional,string 交易完成跳转的地址。
activate_url optional, string 账户激活中状态跳转链接。
has_header optional,boolean 是否显示量化派页面顶部 header,即是否显示 H5 顶部标题栏,默认为 true 时显示。

cmb_wallet 招行一网通

extra 参数 说明
result_url required string 支付完成的前端回调地址。
p_no required string 客户协议号,不超过 30 位的纯数字字符串。
seq required string 协议开通请求流水号,不超过 20 位的纯数字字符串,请保证系统内唯一。
m_uid required string 协议用户 ID,不超过 20 位的纯数字字符串。
mobile required string 协议手机号,11 位数字。
discount_amount response-only int 立减金额,支付完成的返回参数,单位为分。

注: 对于 p_no, seq , m_uid , mobile 这几个参数: 1. 这几个参数是用户自定义的。 2. 对于同一个终端用户每次请求 charge 务必使用同一套参数(确保每个参数都不变),任意参数变更都会导致用户重新签约,同一个用户和招行重新签约的次数有限制,超限制就会无法签约 ,导致用户无法使用。

mmdpay_wap 么么贷

extra 参数 说明
phone required string 手机号。
id_no required string 身份证号。
name required string 真实姓名。

qpay QQ钱包

extra 参数 说明
device required string 客户端设备类型,取值范围: "ios" ,"android"。

qpay_pub QQ钱包公众号支付

extra 参数 说明
device_info optional,string 调用接口提交的终端设备号。
limit_pay optional,string 支付方式限制,可以针对当前的交易限制用户的支付方式,如:仅允许使用余额,或者是禁止使用信用卡,详情见「支付方式限制说明」。
promotion_tag optional,string 指定本单参与某个 QQ 钱包活动或活动档位的标识,包含两个标识。sale_tag:不同活动的匹配标志;level_tag:同一活动不同优惠档位的标志,可不填。格式如下(本字段参与签名): promotion_tag=urlencode(level_tag=xxx&sale_tag=xxx)
attach optional,string 附加数据,在查询 API 和支付通知中原样返回,该字段主要用于商户携带订单的自定义数据。
openid response-only,string 用户在商户appid下的唯一标识,示例:oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
bank_type response-only,string 银行类型,采用字符串类型的银行卡标识,示例:CCB_DEBIT。值列表详见 支持的付款银行列表

支付方式限制说明

参数 说明
no_balance 不准使用余额
no_credit 不准使用信用卡
no_debit 不准使用借记卡
balance_only 只准使用余额
debit_only 只准使用借记卡
NoBindNoBalan 简化注册用户不允许用余额

balance 余额转账

extra 参数 说明
user required string 使用余额支付所对应的用户 user id 。注:在创建 Order 时,若后续需要使用 balance 渠道进行支付,则创建 Order 时的参数 uid 必传,执行 Order Pay 方法时此处 user 参数无需传;在创建 Charge 时,若后续需要使用 balance 渠道进行支付,此处 user 参数必传。

企业付款 extra 参数说明

wx_pub 微信公众号企业付款

extra参数 说明
user_name optional,string 收款人姓名。当该参数为空,则不校验收款人姓名。
force_check optional,boolean 是否强制校验收款人姓名。仅当 user_name 参数不为空时该参数生效。

wx_lite 微信小程序企业付款

extra参数 说明
user_name optional,string 收款人姓名。当该参数为空,则不校验收款人姓名。
force_check optional,boolean 是否强制校验收款人姓名。仅当 user_name 参数不为空时该参数生效。

alipay 支付宝企业付款

extra参数 说明
recipient_name required string 收款人姓名,1~50位。在 alipay 为 1.0 接口时必填,在 alipay 为 2.0 接口时选填。
recipient_account_type optional,string 收款方账户类型。可取值:1、 ALIPAY_USERID :支付宝账号对应的支付宝唯一用户号。以2088开头的16位纯数字组成。 2、 ALIPAY_LOGONID (默认值):支付宝登录号,支持邮箱和手机号格式。

unionpay 银联电子代付

extra参数 说明
card_number required string 1~32位,收款人银行卡号或者存折号。
user_name required string 1~100位,收款人姓名。
open_bank_code optional,string 4位,开户银行编号,详情请参考 银联电子代付银行编号说明
open_bank optional,string 1~50位,开户银行。
prov optional,string 1~20位,省份。
city optional,string 1~40位,城市。
sub_bank optional,string 1~80位,开户支行名称。

open_bank_codeopen_bank 两个参数必传一个,建议使用 open_bank_code ,若都传参则优先使用 open_bank_code 读取规则;provcity 均为可选参数,如果不传参,则使用默认值 "上海" 给渠道接口。

allinpay 通联代付

extra参数 说明
card_number required string 1~32位,收款人银行卡号或者存折号。
user_name required string 1~100位,收款人姓名。
open_bank_code required string 4位,开户银行编号,详情请参考 通联代付银行编号说明
business_code optional,string 5位,业务代码,根据通联业务人员提供,不填使用通联提供默认值 09900 。详情请参考 通联代付业务代码说明
card_type optional,string 1位,银行卡号类型。0:银行卡、1:存折、2:信用卡。不填默认使用银行卡。

jdpay 京东代付

extra参数 说明
card_number required string 1~32位,收款人银行卡号或者存折号。
user_name required string 1~100位,收款人姓名。
open_bank_code required string 4位,开户银行编号,详情请参考 京东代付银行编号说明
card_type optional,string 1位,银行卡号类型。0:银行卡、2:信用卡。不填默认使用银行卡。

unionpay_gz 贵州银联代付

extra参数 说明
card_number required string 1~32位,收款人银行卡号或者存折号。
user_name required string 1~100位,收款人姓名。
open_bank_code_gz optional,string (B2B场景需要)开户银行编号,详情请 点击下载附件
open_bank_gz optional,string (B2B场景需要)开户银行名称,详情请 点击下载附件

open_bank_code_gzopen_bank_gz 两个参数在 B2B 场景必传一个(B2C 无需传,传了也不生效),建议使用 open_bank_code_gz,若都传参则优先使用 open_bank_code_gz 读取规则。

子商户应用渠道参数说明

一、支付渠道参数说明

alipay 支付宝App支付

参数
fee_rate optional int 渠道签约费率。例如:60代表 0.6% 。
alipay_pid required string 合作者身份(PID),对应商户申请的支付宝的 partnerId。
alipay_app_id optional string 支付宝商户 AppID。在参数 alipay_version 为 2.0 时,需要传入此参数。
alipay_account required string 支付宝账号。
alipay_sign_type optional string 商户生成签名字符串所使用的签名算法类型,传 rsa 或 rsa2 其中一种。
alipay_security_key required string 支付宝安全校验码(Key)。
alipay_mer_app_private_key required string 应用私钥。若 alipay_sign_type 为 rsa,则此字段为必填。
alipay_app_public_key required string 支付宝公钥。若 alipay_sign_type 为 rsa,则此字段为必填。
alipay_mer_app_private_key_rsa2 required string 应用私钥(RSA2)。若 alipay_sign_type 为 rsa2,则此字段为必填。
alipay_app_public_key_rsa2 required string 支付宝公钥(RSA2)。若 alipay_sign_type 为 rsa2,则此字段为必填。
alipay_version optional string 支付宝版本,可选值:1、2。1:支付宝1.0接口(mapi);2:支付宝2.0 接口(openapi)。 如何区分支付宝1.0 和2.0
alipay_refund_nopwd optional bool 是否启用免密接口。支付宝1.0产品:支付宝商家中心 - 我的产品 - 即时到账无密退款V3 若需开通,请访问蚂蚁商家在线服务或拨打支付宝商家服务热线。支付宝2.0产品默认开启此权限。

alipay_wap 支付宝手机网页支付

参数
fee_rate optional int 渠道费率,例如:60代表 0.6% 。
alipay_pid required string 合作者身份(PID),对应商户申请的支付宝的 partnerId。
alipay_app_id optional string 支付宝商户 AppID。在参数 alipay_version 为 2.0 时,需要传入此参数。
alipay_account required string 支付宝企业账户(邮箱)。
alipay_sign_type optional string 商户生成签名字符串所使用的签名算法类型,传 rsa 或 rsa2 其中一种。
alipay_security_key required string 安全校验码(Key)。
alipay_mer_wap_private_key optional string 应用私钥。若 alipay_sign_type 为 rsa,则此字段为必填。
alipay_wap_public_key optional string 支付宝公钥。若 alipay_sign_type 为 rsa,则此字段为必填。
alipay_mer_wap_private_key_rsa2 optional string 应用私钥(RSA2)。若 alipay_sign_type 为 rsa2,则此字段为必填。
alipay_wap_public_key_rsa2 optional string 支付宝公钥(RSA2)。若 alipay_sign_type 为 rsa2,则此字段为必填。
alipay_version optional int 支付宝版本,可选值:1、2。1:支付宝1.0接口(mapi);2:支付宝2.0 接口(openapi)。 如何区分支付宝1.0 和2.0
alipay_refund_nopwd optional bool 是否启用免密接口,支付宝1.0产品:支付宝商家中心 - 我的产品 - 即时到账无密退款V3 若需开通,请访问蚂蚁商家在线服务或拨打支付宝商家服务热线。支付宝2.0产品默认开启此权限。

alipay_pc_direct 支付宝电脑网站支付

参数
fee_rate optional int 渠道费率,例如:60代表 0.6% 。
alipay_pid required string 合作者身份(PID),对应商户申请的支付宝的 partnerId。
alipay_account required string 支付宝企业账户(邮箱)。
alipay_security_key required string 安全校验码(Key)。
alipay_private_key required string 应用私钥(非 PKCS8 编码)。
alipay_public_key required string 支付宝公钥。
alipay_refund_nopwd optional bool 是否启用免密接口。支付宝商家中心 - 我的产品 - 即时到账无密退款 V3 若需开通,请访问蚂蚁商家在线服务或拨打支付宝商家服务热线。
alipay_service_type optional int 接口名称,可选值:0、1。0 : create_direct_pay_by_user , 1 :公益接口 create_donate_trade_p

alipay_qr 支付宝当面付

参数
fee_rate optional int 渠道签约费率,例如:60代表 0.6% 。
alipay_qr_pid required string 对应商户申请的支付宝的 partnerId。
alipay_qr_app_id required string 支付宝商户 AppID。
alipay_sign_type optional string 商户生成签名字符串所使用的签名算法类型,传 rsa 或 rsa2 其中一种。
alipay_qr_mer_private_key required string 应用私钥。若 alipay_sign_type 为 rsa,则此字段为必填。
alipay_qr_public_key required string 支付宝公钥。若 alipay_sign_type 为 rsa,则此字段为必填。
alipay_qr_mer_private_key_rsa2 required string 应用私钥(RSA2)。若 alipay_sign_type 为 rsa2,则此字段为必填。
alipay_qr_public_key_rsa2 required string 支付宝公钥。若 alipay_sign_type 为 rsa2,则此字段为必填。

wx 微信App支付

参数
wx_app_id required string 微信公众号身份的唯一标识。微信开放平台 => 管理中心 => 移动应用 => 查看
wx_mch_id required string 商户ID。微信支付申请完成之后,在微信商户平台的通知邮件中获取,请确保邮件上的 AppID 与微信开放平台上的 AppID 一致
wx_key required string 商户支付密钥,用于报文签名及验签。微信商户平台 => API 安全 =>设置密钥,将设置的 32 位密钥填入此处
wx_app_secret required string 微信appSecret。微信开放平台 => 管理中心 => 移动应用 => 查看
wx_operator_id required string 退款操作员ID。微信商户平台 =>员工账号 =>新增员工账号,将员工的登录账号填入此处
wx_client_cert required string 微信客户端证书。微信商户平台 => API 安全 => API 证书 =>下载证书
wx_client_key required string 微信客户端秘钥。微信商户平台 => API 安全 => API 证书 =>下载证书
wx_is_agent optional bool 是否代理商
wx_agent_id optional int 代理商id号
fee_rate optional bool 渠道签约费率,例如:60代表 0.6%

wx_pub 微信公众号支付

参数
fee_rate optional integer 渠道费率,例如:60代表 0.6%
wx_pub_app_id required string 微信公众号AppID(应用 ID),获取地址:微信公众平台 => 开发 => 基本配置
wx_pub_mch_id required string 微信支付商户ID.微信公众号支付申请完成之后,在微信商户平台的通知邮件中获取,请确保邮件上的 AppID 与微信公众平台上的 AppID 一致。
wx_pub_key required string 商户支付API 密钥,用于报文签名及验签。微信商户平台 => API 安全 => 设置密钥,将设置的 32 位密钥填入此处
wx_pub_app_secret required string 应用密钥,用于获取openid。获取地址:微信公众平台 => 开发 => 基本配置
wx_pub_operator_id required string 由商户添加的退款操作员ID,用于退款、退款查询。获取地址:微信商户平台 => 员工账号 => 新增员工账号,将员工的登录账号填入此处
wx_pub_client_cert required string 微信客户端证书(pem格式,不包含秘钥),用于退款、退款查询。微信商户平台 => API 安全 => API 证书 =>下载证书
wx_pub_client_key required string 微信客户端证书秘钥(pem格式),用于退款、退款查询。微信商户平台 => API 安全 => API 证书 =>下载证书
wx_pub_is_agent optional bool 是否是微信代理商子商户
wx_pub_agent_id optional integer 微信代理商ID

wx_pub_qr 微信扫码支付

参数
wx_pub_app_id required string 微信公众号AppID(应用 ID),获取地址:微信公众平台 => 开发 => 基本配置
wx_pub_mch_id required string 微信支付商户ID。微信公众号支付申请完成之后,在微信商户平台的通知邮件中获取,请确保邮件上的 AppID 与微信公众平台上的 AppID 一致。
wx_pub_key required string 商户支付API 密钥,用于报文签名及验签。微信商户平台 => API 安全 => 设置密钥,将设置的 32 位密钥填入此处
wx_pub_app_secret required string 应用密钥,用于获取openid。获取地址:微信公众平台 => 开发 => 基本配置
wx_pub_operator_id required string 由商户添加的退款操作员ID,用于退款、退款查询。获取地址:微信商户平台 => 员工账号 => 新增员工账号,将员工的登录账号填入此处
wx_pub_client_cert required string 微信客户端证书(pem格式,不包含秘钥),用于退款、退款查询。微信商户平台 => API 安全 => API 证书 =>下载证书
wx_pub_client_key required string 微信客户端证书秘钥(pem格式),用于退款、退款查询。微信商户平台 => API 安全 => API 证书 =>下载证书
wx_pub_is_agent optional bool 是否是微信代理商子商户
wx_pub_agent_id optional integer 微信代理商ID
fee_rate optional integer 渠道签约费率。例如:60代表 0.6%

wx_wap 微信 H5 支付

参数
fee_rate optional int 渠道费率,例如:60代表 0.6%
wx_wap_app_id required string 微信公众号AppID(应用 ID), 获取地址:微信公众平台 => 开发 => 基本配置
wx_wap_mch_id required string 微信支付商户ID。微信公众号支付申请完成之后,在微信商户平台的通知邮件中获取,请确保邮件上的 AppID 与微信公众平台上的 AppID 一致。
wx_wap_key required string 商户支付API 密钥,用于报文签名及验签。微信商户平台 => API 安全 => 设置密钥,将设置的 32 位密钥填入此处
wx_wap_app_secret required string 应用密钥,用于获取openid。获取地址:微信公众平台 => 开发 => 基本配置
wx_wap_operator_id required string 由商户添加的退款操作员ID,用于退款、退款查询。获取地址:微信商户平台 => 员工账号 => 新增员工账号,将员工的登录账号填入此处
wx_wap_client_cert required string 微信客户端证书(pem格式,不包含秘钥),用于退款、退款查询。微信商户平台 => API 安全 => API 证书 =>下载证书
wx_wap_client_key required string 微信客户端证书秘钥(pem格式),用于退款、退款查询。微信商户平台 => API 安全 => API 证书 =>下载证书

wx_lite 微信小程序支付

参数
fee_rate optional int 渠道费率,例如:60代表 0.6%
wx_lite_app_id required string 小程序 AppID,微信小程序=>设置=>开发设置
wx_lite_mch_id required string - 微信支付商户号,申请小程序支付时,若选择使用已有的公众号支付,请填写公众号支付商户号;否则,请在新申请的微信商户平台的通知邮件中获取商户号,确保邮件上的 AppID 与微信小程序的一致
wx_lite_key required string API 密钥,微信商户平台 => API 安全 => 设置密钥,将设置的 32 位密钥填入此处
wx_lite_app_secret required string 小程序 AppSecret,微信小程序=>设置=>开发设置
wx_lite_operator_id required string 员工登录帐号,获取地址:微信商户平台 => 员工账号 => 新增员工账号,将员工的登录账号填入此处
wx_lite_client_cert required string API 证书,微信商户平台 => API 安全 => API 证书 =>下载证书
wx_lite_client_key required string API 证书密钥,微信商户平台 => API 安全 => API 证书 =>下载证书

upacp 银联手机支付

参数
upacp_mer_id required string 商户号
upacp_client_cert required string 安全证书(pfx 格式)
upacp_client_key optional string 安全证书密码
upacp_is_encrypted_params optional bool 是否配置敏感数据加密
fee_rate optional int 渠道签约费率

upacp_pc 银联网关支付

参数
upacp_mer_id required string 银联渠道商户号
upacp_client_cert required string 安全证书(pfx 格式)
upacp_client_key optional string 安全证书密码,需配置。
upacp_is_encrypted_params optional bool 是否配置敏感数据加密
fee_rate optional int 渠道签约费率

upacp_wap 银联手机网页支付

参数
upacp_mer_id required string 银联渠道商户号
upacp_client_cert required string 安全证书(pfx 格式)
upacp_client_key optional string 安全证书密码,需配置
upacp_is_encrypted_params optional bool 是否配置敏感数据加密
fee_rate optional int 渠道签约费率

cp_b2b 银联企业网银支付

参数
mer_id required string 银联渠道商户号
sign_file required string 交易证书
sign_pass required string 交易证书密码
verify_file required string ChinaPay 签名校验证书
tran_type required string 支付业务类型
fee_rate optional int 渠道签约费率

yeepay_wap 易宝手机网页支付

参数
fee_rate optional int 渠道费率。例如:60代表 0.6%
yeepay_mer_id required string 易宝商户账号编号,易宝商户平台 => 系统管理 => RSA 公钥管理
yeepay_public_key required string 易宝 RSA 公钥,易宝商户平台 => 系统管理 => RSA 公钥管理 => 一键生成 RSA 密钥
yeepay_mer_private_key required string 商户 RSA 私钥,易宝商户平台 => 系统管理 => RSA 公钥管理 =>一键生成 RSA 密钥

jdpay_wap 京东手机网页支付

参数
fee_rate optional int 渠道费率。例如:60代表 0.6%
jdpay_mer_id required string 京东支付移动端待结算账户,京东钱包企业站 => 资金管理 => 账户查询,一般是 9 位数字商户号 +00X,如 001,002,比如 123456789001
jdpay_des_key required string DES 密钥,京东钱包企业站 => 安全中心 => 密钥设置
jdpay_md5_key required string MD5 密钥,京东钱包企业站 => 安全中心 => 密钥设置
jdpay_public_key required string 京东支付公钥RSA 公钥,非 PKCS8 编码
jdpay_mer_private_key required string 商户私钥(非 PKCS8 编码) ,请联系京东获取 pem 格式的 RSA 私钥
jdpay_version optional string 京东支付版本

fqlpay_wap 分期乐支付

参数
fee_rate optional int 渠道费率。例如:60代表 0.6%
partner_id required string 商户号
partner_key required string 分期乐合作密钥

qgbc_wap 量化派支付

参数
fee_rate optional int 渠道费率。例如:60代表 0.6%
merchant_id required string 量化派商户 ID
private_key required string 商户 RSA 公钥
public_key required string 量化派 RSA 公钥

cmb_wallet 招行一网通

参数
fee_rate optional int 渠道费率。例如:60代表 0.6%
cmb_bank_no required string 网银编号(招行参数邮件中「企业网银编号」的内容)
cmb_br_id required string 分行号,招行参数邮件中「商户号」项目下的前四位数字
cmb_co_id required string 商户号,招行参数邮件中「商户号」项目下的后六位数字
cmb_co_password required string 商户密码,商户平台重置后的密码
cmb_secret_key required string 商户密钥,商户平台 =>商户密钥
cmb_private_key required string 商户私钥
cmb_version optional int 招行版本

applepay_upacp Apple Pay

参数
fee_rate optional int 渠道费率。例如:60代表 0.6%
upacp_mer_id required string 银联渠道商户号
upacp_client_cert required string 安全证书(pfx 格式)
upacp_client_key optional string 安全证书密码
upacp_is_encrypted_params optional bool 是否配置敏感数据加密
upacp_merchant_id required string Apple 开发者中心商户 ID
mode optional int 是否是测试模式(银联下发的测试模式参数,有别于 Ping++ 测试模式,请注意不要混淆)。0:测试模式,1:正式模式

mmdpay_wap 么么贷

参数
fee_rate optional int 渠道费率。例如:60代表 0.6%
partner_id required string APPID
partner_key required string 么么贷合作密钥

qpay QQ钱包支付

参数
fee_rate optional int 渠道费率
qpay_partner_id required string QQ 钱包商户号
qpay_partner_key required string 商户密钥
qpay_operator_id required string 操作员 ID
qpay_operator_pass required string 操作员密码
qpay_client_cert required string 商户证书
qpay_client_cert_pass required string 商户证书密码
qpay_ios_appid optional string QQ 钱包开放平台 App id (iOS)
qpay_ios_appkey optional string QQ 钱包开放平台 App Key (iOS)
qpay_android_appid optional string QQ 钱包开放平台 App id (Android)
qpay_android_appkey optional string QQ 钱包开放平台 App Key (Android)

qpay_pub QQ钱包公众号支付

参数
fee_rate optional int 渠道费率
qpay_pub_partner_id required string QQ 钱包商户号
qpay_pub_partner_key required string 商户密钥
qpay_pub_operator_id required string 操作员 ID
qpay_pub_operator_pass required string 操作员密码
qpay_pub_client_cert required string 商户证书
qpay_pub_client_cert_pass required string 商户证书密码
qpay_pub_appid optional string QQ 钱包开放平台 App ID

bfb 百度钱包App支付

参数
fee_rate optional int 渠道费率。例如:60代表 0.6%
bfb_sp required string 商户 ID
bfb_key required string 百度钱包合作密钥

bfb_wap 百度钱包手机网页支付

参数
fee_rate optional int 渠道费率。例如:60代表 0.6%
bfb_sp required string 商户 ID
bfb_key required string 百度钱包合作密钥

二、企业付款渠道参数说明

alipay 支付宝

参数
fee_rate optional int 渠道签约费率。例如:60代表 0.6% 。
alipay_pid required string 合作者身份(PID),对应商户申请的支付宝的 partnerId。
alipay_app_id optional string 支付宝商户 AppID。在参数 alipay_version 为 2.0 时,需要传入此参数。
alipay_account required string 支付宝账号。
alipay_account_name required string 公司名称。
alipay_sign_type optional string 商户生成签名字符串所使用的签名算法类型,传 rsa 或 rsa2 其中一种。
alipay_security_key required string 支付宝安全校验码(Key)。
alipay_private_key required string 应用私钥。若 alipay_sign_type 为 rsa,则此字段为必填。
alipay_public_key required string 支付宝公钥。若 alipay_sign_type 为 rsa,则此字段为必填。
alipay_private_key_rsa2 required string 应用私钥(RSA2)。若 alipay_sign_type 为 rsa2,则此字段为必填。
alipay_public_key_rsa2 required string 支付宝公钥(RSA2)。若 alipay_sign_type 为 rsa2,则此字段为必填。
alipay_version optional string 支付宝版本,可选值:1、2。1:支付宝1.0接口(mapi);2:支付宝2.0 接口(openapi)。 如何区分支付宝1.0 和2.0

unionpay 银联电子代付

参数
fee_type optional int 渠道费率类型,可选值:1、2。1:万分比,2:固定金额(单位为分)。
fee_rate optional int 渠道签约费率。例如:60代表 0.6% 。
mer_id required string 商户号。
priv_key required string 银联电子代付私钥。
pub_key required string 银联电子代付公钥。

unionpay_gz 贵州银联代付

参数
fee_type optional int 渠道费率类型,可选值:1、2。1:万分比,2:固定金额(单位为分)。
fee_rate_b2c optional int 对私费率。例如:200代表 2%
fee_rate_b2b optional int 对公费率。例如:300代表 3%
fee_rate_b2b_large optional int 对公费率大额(超过 5w 时使用此费率)。
unionpay_gz_cust_id required string 贵州银联支付商户 id。
unionpay_gz_partner_id required string 贵州银联支付合作渠道编号。
unionpay_gz_mer_private_key required string 商户私钥。

wx_pub 微信公众号支付

参数
fee_rate optional integer 渠道费率,例如:60代表 0.6%
wx_pub_app_id required string 微信公众号AppID(应用 ID),获取地址:微信公众平台 => 开发 => 基本配置
wx_pub_mch_id required string 微信支付商户ID。微信公众号支付申请完成之后,在微信商户平台的通知邮件中获取,请确保邮件上的 AppID 与微信公众平台上的 AppID 一致。
wx_pub_key required string 商户支付 API 密钥,用于报文签名及验签。微信商户平台 => API 安全 => 设置密钥,将设置的 32 位密钥填入此处
wx_pub_app_secret required string 应用密钥,用于获取openid。获取地址:微信公众平台 => 开发 => 基本配置
wx_pub_operator_id required string 由商户添加的退款操作员ID,用于退款、退款查询。获取地址:微信商户平台 => 员工账号 => 新增员工账号,将员工的登录账号填入此处
wx_pub_client_cert required string 微信客户端证书(pem格式,不包含秘钥),用于退款、退款查询。微信商户平台 => API 安全 => API 证书 =>下载证书
wx_pub_client_key required string 微信客户端证书秘钥(pem格式),用于退款、退款查询。微信商户平台 => API 安全 => API 证书 =>下载证书
wx_pub_is_agent optional bool 是否是微信代理商子商户
wx_pub_agent_id optional integer 微信代理商ID

wx_lite 微信小程序支付

参数
fee_rate optional integer 渠道费率,例如:60代表 0.6%
wx_lite_app_id required string 小程序 AppID(应用 ID)。获取地址:微信公众平台 => 设置 => 开发设置
wx_lite_mch_id required string 微信支付商户 ID。在微信商户平台的通知邮件中获取,请确保邮件上的 AppID 与微信公众平台上的 AppID 一致
wx_lite_key required string 商户支付 API 密钥,用于报文签名及验签。微信商户平台 => API 安全 => 设置密钥,将设置的 32 位密钥填入此处
wx_lite_app_secret required string 小程序 AppSecret(应用密钥)。获取地址:微信公众平台 => 设置 => 开发设置
wx_lite_operator_id required string 由商户添加的退款操作员ID,用于退款、退款查询。获取地址:微信商户平台 => 员工账号 => 新增员工账号,将员工的登录账号填入此处
wx_lite_client_cert required string 微信客户端 API 证书(pem格式,不包含秘钥),用于退款、退款查询。微信商户平台 => API 安全 => API 证书 =>下载证书
wx_lite_client_key required string 微信客户端 API 证书秘钥(pem格式),用于退款、退款查询。微信商户平台 => API 安全 => API 证书 =>下载证书

jdpay 京东代付

参数
fee_type optional int 渠道费率类型,可选值:1、2。1:万分比,2:固定金额(单位为分)。
fee_rate optional int 渠道费率。例如:60代表 0.6% 。
jdpay_mer_id required string 商户号。
jdpay_mer_sign_key required string 密钥。
jdpay_mer_public_key required string 京东支付公钥 RSA 公钥,非 PKCS8 编码。
jdpay_mer_private_key required string 商户私钥(非 PKCS8 编码) ,请联系京东获取 pem 格式的 RSA 私钥。
jdpay_public_key required string 京东支付公钥 RSA 公钥。

allinpay 通联代付

参数
fee_type optional int 渠道费率类型,可选值:1、2。1:万分比,2:固定金额(单位为分)。
fee_rate optional int 渠道费率。例如:60代表 0.6% 。
allinpay_mer_id required string 商户号。
allinpay_mer_username required string 系统对接用户名。
allinpay_mer_password required string 商户后台密码。
allinpay_mer_private_key required string 私钥证书(p12)。
allinpay_public_key required string 公钥证书(cer)。

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
  "channel": "alipay",
  "params": {
    "alipay_pid": "2088111111111111",
    "alipay_app_id": "2016666666666666",
    "alipay_account": "example@example.com",
    "alipay_security_key": "a5srakrbci3nf1pracb52xcs9xlhu8gu",
    "alipay_mer_app_private_key": "-----BEGIN PRIVATE KEY-----  your private key-----END PRIVATE KEY-----",
    "alipay_app_public_key": "-----BEGIN PUBLIC KEY-----  your public key
    -----END PUBLIC KEY-----",
    "alipay_mer_app_private_key_rsa2": null,
    "alipay_app_public_key_rsa2": null,
    "alipay_version": 1,
    "alipay_refund_nopwd": true
  },
  "banned": false,
  "banned_msg": "your banned_msg",
  "description": "Your alipay description"
}'

返回示例

{
  "object": "channel",
  "channel": "alipay",
  "banned": false,
  "banned_msg": "your banned_msg",
  "created": 1494854723,
  "description": "Your alipay description",
  "params": {
    "alipay_pid": "2088111111111111",
    "alipay_app_id": "2016666666666666",
    "alipay_account": "example@example.com",
    "alipay_security_key": "a5srakrbci3nf1pracb52xcs9xlhu8gu",
    "alipay_mer_app_private_key": "-----BEGIN PRIVATE KEY-----  your private key-----END PRIVATE KEY-----",
    "alipay_app_public_key": "-----BEGIN PUBLIC KEY-----  your public key-----END PUBLIC KEY-----",
    "alipay_mer_app_private_key_rsa2": null,
    "alipay_app_public_key_rsa2": null,
    "alipay_version": 1,
    "alipay_refund_nopwd": true
  }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1496917659" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
  "channel": "alipay_wap",
  "banned": false,
  "banned_msg": null,
  "description": "description for channel alipay_wap",
  "params": {
    "fee_rate": 8,
    "alipay_pid": "2088111111111111",
    "alipay_app_id": "8888888888888888",
    "alipay_account": "user@example.com",
    "alipay_sign_type": "rsa",
    "alipay_security_key": "yp019rfh1jvc4ccrnt5kj75266ezjzaz",
    "alipay_mer_wap_private_key": "-----BEGIN PRIVATE KEY-----  your private key-----END PRIVATE KEY-----",
    "alipay_wap_public_key": "-----BEGIN PUBLIC KEY-----  your public key-----END PUBLIC KEY-----",
    "alipay_mer_wap_private_key_rsa2": null,
    "alipay_wap_public_key_rsa2": null,
    "alipay_version": 2,
    "alipay_refund_nopwd": true
  }
}'

返回示例

{
  "object": "channel",
  "channel": "alipay_wap",
  "banned": false,
  "banned_msg": null,
  "created": 1496917659,
  "description": "description for channel alipay_wap",
  "params": {
    "fee_rate": 8,
    "alipay_pid": "2088111111111111",
    "alipay_app_id": "8888888888888888",
    "alipay_account": "user@example.com",
    "alipay_sign_type": "rsa",
    "alipay_security_key": "yp019rfh1jvc4ccrnt5kj75266ezjzaz",
    "alipay_mer_wap_private_key": "-----BEGIN PRIVATE KEY-----  your private key-----END PRIVATE KEY-----",
    "alipay_wap_public_key": "-----BEGIN PUBLIC KEY-----  your public key-----END PUBLIC KEY-----",
    "alipay_mer_wap_private_key_rsa2": null,
    "alipay_wap_public_key_rsa2": null,
    "alipay_version": 2,
    "alipay_refund_nopwd": true
  }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1496917936" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
 "channel": "alipay_pc_direct",
 "banned": false,
 "banned_msg": null,
 "description": "description for channel alipay_pc_direct",
 "params": {
   "fee_rate": 60,
   "alipay_pid": "2088111111111111",
   "alipay_account": "user@example.com",
   "alipay_security_key": "yp019rfh1jvc4ccrnt5kj75266ezjzaz",
   "alipay_private_key": "-----BEGIN PRIVATE KEY-----  your private key-----END PRIVATE KEY-----",
   "alipay_public_key": "-----BEGIN PUBLIC KEY-----  your public key-----END PUBLIC KEY-----",
   "alipay_refund_nopwd": true,
   "alipay_service_type": 0
 }
}'

返回示例

{
  "object": "channel",
  "channel": "alipay_pc_direct",
  "banned": false,
  "banned_msg": null,
  "created": 1496917936,
  "description": "description for channel alipay_pc_direct",
  "params": {
    "fee_rate": 60,
    "alipay_pid": "2088111111111111",
    "alipay_account": "user@example.com",
    "alipay_security_key": "yp019rfh1jvc4ccrnt5kj75266ezjzaz",
    "alipay_private_key": "-----BEGIN PRIVATE KEY-----  your private key-----END PRIVATE KEY-----",
    "alipay_public_key": "-----BEGIN PUBLIC KEY-----  your public key-----END PUBLIC KEY-----",
    "alipay_refund_nopwd": true,
    "alipay_service_type": 0
  }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
  "channel": "alipay_qr",
  "params": {
    "alipay_qr_pid": "2088111111111111",
    "alipay_qr_app_id": "8888888888888888",
    "alipay_sign_type": "rsa",
    "alipay_qr_mer_private_key": "-----BEGIN PRIVATE KEY-----  your private key-----END PRIVATE KEY-----",
    "alipay_qr_public_key": "-----BEGIN PUBLIC KEY-----  your public key-----END PUBLIC KEY-----",
    "alipay_qr_mer_private_key_rsa2": null,
    "alipay_qr_public_key_rsa2": null
  },
  "banned": false,
  "banned_msg": "your banned_msg",
  "description": "Your alipay_qr description"
}'

返回示例

{
  "object": "channel",
  "channel": "alipay_qr",
  "banned": false,
  "banned_msg": "your banned_msg",
  "created": 1494853598,
  "description": "Your alipay_qr description",
  "params": {
    "alipay_qr_pid": "2088111111111111",
    "alipay_qr_app_id": "8888888888888888",
    "alipay_sign_type": "rsa",
    "alipay_qr_mer_private_key": "-----BEGIN PRIVATE KEY-----  your private key-----END PRIVATE KEY-----",
    "alipay_qr_public_key": "-----BEGIN PUBLIC KEY-----  your public key-----END PUBLIC KEY-----",
    "alipay_qr_mer_private_key_rsa2": null,
    "alipay_qr_public_key_rsa2": null
  }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
  "channel": "wx",
  "params": {
    "wx_app_id": "wxv2eefqfjfylvtdx3",
    "wx_mch_id": "1266666666",
    "fee_rate": 200,
    "wx_key": "8v0QFJTOHbZE7d5tG97LZNv5bhrvkpYS",
    "wx_app_secret": "kp9qzseg33lbhgunp2zfgulrbcmmsbfd",
    "wx_operator_id": "operator@1266666666",
    "wx_client_cert": "-----BEGIN CERTIFICATE-----**your cert **-----END CERTIFICATE-----",
    "wx_client_key": "-----BEGIN PRIVATE KEY-----  your private key-----END PRIVATE KEY-----",
    "wx_is_agent": true,
    "wx_agent_id": 1
  },
  "banned": false,
  "banned_msg": "your banned_msg",
  "description": "Your description"
}'

返回示例

{
  "object": "channel",
  "channel": "wx",
  "banned": false,
  "banned_msg": "your banned_msg",
  "created": 1494850516,
  "description": "Your wx channel description",
  "params": {
    "wx_app_id": "wxv2eefqfjfylvtdx3",
    "wx_mch_id": "1266666666",
    "fee_rate": 200,
    "wx_key": "8v0QFJTOHbZE7d5tG97LZNv5bhrvkpYS",
    "wx_app_secret": "kp9qzseg33lbhgunp2zfgulrbcmmsbfd",
    "wx_operator_id": "operator@1266666666",
    "wx_client_cert": "-----BEGIN CERTIFICATE-----your cert -----END CERTIFICATE-----",
    "wx_client_key": "-----BEGIN PRIVATE KEY-----  your private key-----END PRIVATE KEY-----",
    "wx_is_agent": true,
    "wx_agent_id": 1
  }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1496923177" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
  "channel": "wx_pub",
  "banned": false,
  "banned_msg": null,
  "description": "description for channel wx_pub",
  "params": {
    "fee_rate": 60,
    "wx_pub_app_id": "wxqjztoo4kaxjabcmj",
    "wx_pub_mch_id": "10066666",
    "wx_pub_key": "65F1DD9AA103883118E7A5B076453BCC",
    "wx_pub_app_secret": "1cbdd4af01854247c8202f970ecc81fa",
    "wx_pub_operator_id": "10066666@10066666",
    "wx_pub_client_cert": "-----BEGIN CERTIFICATE-----your cert -----END CERTIFICATE-----",
    "wx_pub_client_key": "-----BEGIN PRIVATE KEY-----  your private key-----END PRIVATE KEY-----"
  }
}'

返回示例

{
  "object": "channel",
  "channel": "wx_pub",
  "banned": false,
  "banned_msg": null,
  "created": 1496923177,
  "description": "description for channel wx_pub",
  "params": {
    "fee_rate": 60,
    "wx_pub_app_id": "wxqjztoo4kaxjabcmj",
    "wx_pub_mch_id": "10066666",
    "wx_pub_key": "65F1DD9AA103883118E7A5B076453BCC",
    "wx_pub_app_secret": "1cbdd4af01854247c8202f970ecc81fa",
    "wx_pub_operator_id": "10066666@10066666",
    "wx_pub_client_cert": "-----BEGIN CERTIFICATE-----your cert -----END CERTIFICATE-----",
    "wx_pub_client_key": "-----BEGIN PRIVATE KEY-----  your private key-----END PRIVATE KEY-----"
  }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
  "channel": "wx_pub_qr",
  "params": {
    "wx_pub_app_id": "wx95aa6688abcd22cc",
    "wx_pub_mch_id": "10066666",
    "fee_rate": 60,
    "wx_pub_key": "g3ev8sxhlt1ppbhaqobsnwkegalqelhk",
    "wx_pub_app_secret": "PLgo4E5QYx6d8dNo1PHOLRssSEJWqQHG",
    "wx_pub_operator_id": "10066666@10088888",
    "wx_pub_client_cert": "-----BEGIN CERTIFICATE-----your cert -----END CERTIFICATE-----",
    "wx_pub_client_key": "-----BEGIN PRIVATE KEY-----  your private key-----END PRIVATE KEY-----"
  },
  "banned": false,
  "banned_msg": "your banned_msg",
  "description": "Your description"
}'

返回示例

{
  "object": "channel",
  "channel": "wx_pub_qr",
  "banned": false,
  "banned_msg": "your banned_msg",
  "created": 1494849219,
  "description": "Your description",
  "params": {
    "wx_pub_app_id": "wx95aa6688abcd22cc",
    "wx_pub_mch_id": "10066666",
    "fee_rate": 60,
    "wx_pub_is_agent": false,
    "wx_pub_agent_id": null,
    "actual_channel": null,
    "wx_pub_key": "g3ev8sxhlt1ppbhaqobsnwkegalqelhk",
    "wx_pub_app_secret": "PLgo4E5QYx6d8dNo1PHOLRssSEJWqQHG",
    "wx_pub_operator_id": "10066666@10088888",
    "wx_pub_client_cert": "-----BEGIN CERTIFICATE-----your cert -----END CERTIFICATE-----",
    "wx_pub_client_key": "-----BEGIN PRIVATE KEY-----  your private key-----END PRIVATE KEY-----"
  }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1496925827" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
  "channel": "wx_wap",
  "banned": false,
  "banned_msg": null,
  "description": "description for channel wx_wap",
  "params": {
    "fee_rate": 150,
    "wx_wap_app_id": "wxqjztoo4kaxjabcmj",
    "wx_wap_mch_id": "10066666",
    "wx_wap_key": "65F1DD9AA103883118E7A5B076453BCC",
    "wx_wap_app_secret": "1cbdd4af01854247c8202f970ecc81fa",
    "wx_wap_operator_id": "10066666@10066666",
    "wx_wap_client_cert": "-----BEGIN CERTIFICATE-----your cert -----END CERTIFICATE-----",
    "wx_wap_client_key": "-----BEGIN PRIVATE KEY-----  your private key-----END PRIVATE KEY-----"
  }
}'

返回示例

{
  "object": "channel",
  "channel": "wx_wap",
  "banned": false,
  "banned_msg": null,
  "created": 1496925827,
  "description": "description for channel wx_wap",
  "params": {
    "fee_rate": 150,
    "wx_wap_app_id": "wxqjztoo4kaxjabcmj",
    "wx_wap_mch_id": "10066666",
    "wx_wap_key": "65F1DD9AA103883118E7A5B076453BCC",
    "wx_wap_app_secret": "1cbdd4af01854247c8202f970ecc81fa",
    "wx_wap_operator_id": "10066666@10066666",
    "wx_wap_client_cert": "-----BEGIN CERTIFICATE-----your cert -----END CERTIFICATE-----",
    "wx_wap_client_key": "-----BEGIN PRIVATE KEY-----  your private key-----END PRIVATE KEY-----"
  }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1496926039" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
  "channel": "wx_lite",
  "banned": false,
  "banned_msg": null,
  "description": "description for channel wx_lite",
  "params": {
    "fee_rate": 60,
    "wx_lite_app_id": "wxqjztoo4kaxjabcmj",
    "wx_lite_mch_id": "10066666",
    "wx_lite_key": "65F1DD9AA103883118E7A5B076453BCC",
    "wx_lite_app_secret": "1cbdd4af01854247c8202f970ecc81fa",
    "wx_lite_operator_id": "10066666@10066666",
    "wx_lite_client_cert": "-----BEGIN CERTIFICATE-----your cert -----END CERTIFICATE-----",
    "wx_lite_client_key": "-----BEGIN PRIVATE KEY-----  your private key-----END PRIVATE KEY-----"
  }
}'

返回示例

{
  "object": "channel",
  "channel": "wx_lite",
  "banned": false,
  "banned_msg": null,
  "created": 1496926039,
  "description": "description for channel wx_lite",
  "params": {
    "fee_rate": 60,
    "wx_lite_app_id": "wxqjztoo4kaxjabcmj",
    "wx_lite_mch_id": "10066666",
    "wx_lite_key": "65F1DD9AA103883118E7A5B076453BCC",
    "wx_lite_app_secret": "1cbdd4af01854247c8202f970ecc81fa",
    "wx_lite_operator_id": "10066666@10066666",
    "wx_lite_client_cert": "-----BEGIN CERTIFICATE-----your cert -----END CERTIFICATE-----",
    "wx_lite_client_key": "-----BEGIN PRIVATE KEY-----  your private key-----END PRIVATE KEY-----"
  }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
 -d '{
  "channel": "upacp",
  "params": {
    "upacp_mer_id": "808880088888838",
    "upacp_client_cert": "your client cert"
  },
  "banned": false,
  "banned_msg": "your banned_msg",
  "description": "Your upacp description"
}'

返回示例

{
  "object": "channel",
  "channel": "upacp",
  "banned": false,
  "banned_msg": "your banned_msg",
  "created": 1494856019,
  "description": "Your upacp description",
  "params": {
    "upacp_mer_id": "808880088888838",
    "upacp_client_cert": "Bag Attributes\n localKeyID: 01 00 00 00 \n friendlyName: {12F88888-FFFF-ABCD-6666-02EF666666FF}\n Microsoft CSP Name: Microsoft Enhanced Cryptographic Provider v1.0\nKey Attributes\n X509v3 Key Usage: 10 \n-----BEGIN PRIVATE KEY-----  your private key-----END PRIVATE KEY-----\nBag Attributes\n localKeyID: 01 00 00 00 \nsubject=/C=cn/O=CFCA OCA1/OU=Local RA OCA1/OU=Enterprises/CN=041@8310000000083040@802310048993438:SIGN@00006817\nissuer=/C=CN/O=CFCA OCA1\n-----BEGIN CERTIFICATE-----your cert -----END CERTIFICATE-----\nBag Attributes: <Empty Attributes>\nsubject=/C=CN/O=CFCA CS CA\nissuer=/C=CN/O=CFCA CS CA\n-----BEGIN CERTIFICATE-----your cert -----END CERTIFICATE-----\nBag Attributes: <Empty Attributes>\nsubject=/C=CN/O=CFCA OCA1\nissuer=/C=CN/O=CFCA CS CA\n-----BEGIN CERTIFICATE-----your cert -----END CERTIFICATE-----\""
  }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "channel": "upacp_pc",
    "banned": false,
    "banned_msg": null,
    "description": "description for channel upacp_pc",
    "params": {
        "upacp_mer_id": "808880088888838",
        "fee_rate": 0,
        "upacp_client_cert":  "your client cert",
        "upacp_client_key": "666666"
    }
}'

返回示例

{
  "object": "channel",
  "channel": "upacp_pc",
  "banned": false,
  "banned_msg": null,
  "created": 1494934478,
  "description": "description for channel upacp_pc",
  "params": {
    "upacp_mer_id": "808880088888838",
    "fee_rate": 0,
    "upacp_client_cert": "your client cert"",
    "upacp_client_key": "666666"
  }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1475029155" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "channel": "upacp_wap",
    "banned": false,
    "banned_msg": null,
    "description": "description for channel upacp_wap",
    "params": {
        "upacp_mer_id": "808880088888838",
        "fee_rate": 0,
        "upacp_client_cert":  "your client cert",
        "upacp_client_key": "666666"
    }
}'

返回示例

{
  "object": "channel",
  "channel": "upacp_wap",
  "banned": false,
  "banned_msg": null,
  "created": 1494934478,
  "description": "description for channel upacp_wap",
  "params": {
    "upacp_mer_id": "808880088888838",
    "fee_rate": 0,
    "upacp_client_cert": "your client cert"",
    "upacp_client_key": "666666"
  }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1496921461" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "channel": "cp_b2b",
    "banned": false,
    "banned_msg": null,
    "description": "description for channel cp_b2b",
    "params": {
        "fee_rate": 1000,
        "mer_id": "481611512088888",
        "sign_file": "01101011111011110****",
        "sign_pass": "31466666xxx",
        "verify_file": "-----BEGIN CERTIFICATE-----
        \n<内容省略>\n
        -----END CERTIFICATE-----",
        "tran_type": "0002"
    }
}'

返回示例

{
  "object": "channel",
  "channel": "cp_b2b",
  "banned": false,
  "banned_msg": null,
  "created": 1496921461,
  "description": "description for channel cp_b2b",
  "params": {
    "fee_rate": 1000,
    "mer_id": "481611512088888",
    "sign_file": "01101011111011110****",
    "sign_pass": "31466666xxx",
    "verify_file": "-----BEGIN CERTIFICATE-----
    \n<内容省略>\n
	 -----END CERTIFICATE-----",
    "tran_type": "0002"
  }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1496926855" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
  "channel": "yeepay_wap",
  "banned": false,
  "banned_msg": null,
  "description": "description for channel yeepay_wap",
  "params": {
    "fee_rate": 60,
    "yeepay_mer_id": "10000666666",
    "yeepay_public_key": "your public key"
  }
}'

返回示例

{
  "object": "channel",
  "channel": "yeepay_wap",
  "banned": false,
  "banned_msg": null,
  "created": 1496926855,
  "description": "description for channel yeepay_wap",
  "params": {
    "fee_rate": 60,
    "yeepay_mer_id": "10000666666",
    "yeepay_public_key": "your public key"
  }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1496927062" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "channel": "jdpay_wap",
    "banned": false,
    "banned_msg": null,
    "description": "description for channel jdpay_wap",
    "params": {
        "fee_rate": 60,
        "jdpay_mer_id": "110078720001",
        "jdpay_des_key": "wfHHDkY0B9xKDumMJQH35bNrxOVKAZfv",
        "jdpay_md5_key": "wSxKguEzHQjwmRDkEDwmxk1mcpjIUljU",
        "jdpay_public_key": "-----BEGIN PUBLIC KEY-----your public key-----\n",
        "jdpay_mer_private_key": "-----BEGIN RSA PRIVATE KEY-----your private key-----END RSA PRIVATE KEY-----\n",
        "jdpay_version": "2.0"
    }
}'

返回示例

{
  "object": "channel",
  "channel": "jdpay_wap",
  "banned": false,
  "banned_msg": null,
  "created": 1496927062,
  "description": "description for channel jdpay_wap",
  "params": {
    "fee_rate": 60,
    "jdpay_mer_id": "110078720001",
    "jdpay_des_key": "wfHHDkY0B9xKDumMJQH35bNrxOVKAZfv",
    "jdpay_md5_key": "wSxKguEzHQjwmRDkEDwmxk1mcpjIUljU",
    "jdpay_public_key": "-----BEGIN PUBLIC KEY-----your public key-----END PUBLIC KEY-----",
    "jdpay_mer_private_key": "-----BEGIN RSA PRIVATE KEY-----your private key-----END RSA PRIVATE KEY-----",
    "jdpay_version": "2.0"
  }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1496927629" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "channel": "fqlpay_wap",
    "banned": false,
    "banned_msg": null,
    "description": "description for channel fqlpay_wap",
    "params": {
        "fee_rate": 20,
        "partner_id": "MPA201606616666666",
        "partner_key": "befb666666666f66a66666dcd6b66d0b"
    }
}'

返回示例

{
  "object": "channel",
  "channel": "fqlpay_wap",
  "banned": false,
  "banned_msg": null,
  "created": 1496927629,
  "description": "description for channel fqlpay_wap",
  "params": {
    "fee_rate": 20,
    "partner_id": "MPA201606616666666",
    "partner_key": "befb666666666f66a66666dcd6b66d0b"
  }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1496927840" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "channel": "qgbc_wap",
    "banned": false,
    "banned_msg": null,
    "description": "description for channel qgbc_wap",
    "params": {
        "fee_rate": 50,
        "merchant_id": "abcd10066",
        "private_key": "your private key-----END RSA PRIVATE KEY-----\n",
        "public_key": "-----BEGIN PUBLIC KEY-----your public key-----\n"
    }
}'

返回示例

{
  "object": "channel",
  "channel": "qgbc_wap",
  "banned": false,
  "banned_msg": null,
  "created": 1496927840,
  "description": "description for channel qgbc_wap",
  "params": {
    "fee_rate": 50,
    "merchant_id": "abcd10066",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----your private key-----END RSA PRIVATE KEY-----",
    "public_key": "-----BEGIN PUBLIC KEY-----your public key-----END PUBLIC KEY-----"
  }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1496928076" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "channel": "cmb_wallet",
    "banned": false,
    "banned_msg": null,
    "description": "description for channel cmb_wallet",
    "params": {
        "fee_rate": 0,
        "cmb_bank_no": "00000002",
        "cmb_br_id": "0066",
        "cmb_co_id": "006606",
        "cmb_co_password": "666666",
        "cmb_secret_key": "d4ur4h8Ap4JXGAnZ",
        "cmb_private_key": "your private key-----END RSA PRIVATE KEY-----\n",
        "cmb_version": 1
    }
}'

返回示例

{
  "object": "channel",
  "channel": "cmb_wallet",
  "banned": false,
  "banned_msg": null,
  "created": 1496928076,
  "description": "description for channel cmb_wallet",
  "params": {
    "fee_rate": 0,
    "cmb_bank_no": "00000002",
    "cmb_br_id": "0066",
    "cmb_co_id": "006606",
    "cmb_co_password": "666666",
    "cmb_secret_key": "d4ur4h8Ap4JXGAnZ",
    "cmb_private_key": "-----BEGIN RSA PRIVATE KEY-----your private key-----END RSA PRIVATE KEY-----",
    "cmb_version": 1
  }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1496929010" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
  "channel": "applepay_upacp",
  "banned": false,
  "banned_msg": null,
  "description": "description for channel applepay_upacp",
  "params": {
    "fee_rate": 0,
    "upacp_mer_id": "898660666666666",
    "upacp_client_cert": "-----BEGIN CERTIFICATE-----your cert -----END PRIVATE KEY-----",
    "upacp_client_key": "000000",
    "upacp_merchant_id": "merchant.com.xyz",
    "mode": 1
  }
}'

返回示例

{
  "object": "channel",
  "channel": "applepay_upacp",
  "banned": false,
  "banned_msg": null,
  "created": 1496929010,
  "description": "description for channel applepay_upacp",
  "params": {
    "fee_rate": 0,
    "upacp_mer_id": "898660666666666",
    "upacp_client_cert": "-----BEGIN CERTIFICATE-----your cert-----END PRIVATE KEY-----",
    "upacp_client_key": "000000",
    "upacp_merchant_id": "merchant.com.xyz",
    "mode": 1
  }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1496929251" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "channel": "mmdpay_wap",
    "banned": false,
    "banned_msg": null,
    "description": "description for channel mmdpay_wap",
    "params": {
        "fee_rate": 70,
        "partner_id": "1fb2724c5db3733258b20b9dbf1de9ab",
        "partner_key": "65f1dd9aa103883118e7a5b076453bc9a60877b465f1dd9aa103883120b9dbf1"
    }
}'

返回示例

{
  "object": "channel",
  "channel": "mmdpay_wap",
  "banned": false,
  "banned_msg": null,
  "created": 1496929251,
  "description": "description for channel mmdpay_wap",
  "params": {
    "fee_rate": 70,
    "partner_id": "1fb2724c5db3733258b20b9dbf1de9ab",
    "partner_key": "65f1dd9aa103883118e7a5b076453bc9a60877b465f1dd9aa103883120b9dbf1"
  }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1496929010" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "channel": "qpay",
    "banned": false,
    "banned_msg": null,
    "description": "description for channel qpay",
    "params": {
        "fee_rate": 100,
        "qpay_partner_id": "1900066666",
        "qpay_partner_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
        "qpay_operator_id": "1900066688",
        "qpay_operator_pass": "1900068866",
        "qpay_client_cert": "-----BEGIN CERTIFICATE-----your cert -----END CERTIFICATE-----\n-----BEGIN PRIVATE KEY-----  your private key-----END PRIVATE KEY-----",
        "qpay_client_cert_pass": "1399484801",
        "qpay_ios_appid": "1106688666",
        "qpay_ios_appkey": "9e1e06ec8e0A1B2c3",
        "qpay_android_appid": "1106688666",
        "qpay_android_appkey": "9e1e06ec8e0A1B2c3"
    }
}

返回示例

{
  "object": "channel",
  "channel": "qpay",
  "banned": false,
  "banned_msg": null,
  "created": 1496929529,
  "description": "description for channel qpay",
  "params": {
    "fee_rate": 100,
    "qpay_partner_id": "1900066666",
    "qpay_partner_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "qpay_operator_id": "1900066688",
    "qpay_operator_pass": "1900068866",
    "qpay_client_cert": "-----BEGIN CERTIFICATE-----your cert -----END CERTIFICATE-----\n-----BEGIN PRIVATE KEY-----  your private key-----END PRIVATE KEY-----",
    "qpay_client_cert_pass": "1399484801",
    "qpay_ios_appid": "1106688666",
    "qpay_ios_appkey": "9e1e06ec8e0A1B2c3",
    "qpay_android_appid": "1106688666",
    "qpay_android_appkey": "9e1e06ec8e0A1B2c3"
  }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1496929010" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "channel": "qpay_pub",
    "params": {
        "fee_rate": 60,
        "qpay_pub_partner_id": "1326836123",
        "qpay_pub_partner_key": "c1236b0536ec19d3vfc39504fe1410f4",
        "qpay_pub_operator_id": "1312334567027",
        "qpay_pub_operator_pass": "operatorpassword",
        "qpay_pub_client_cert": "-----BEGIN CERTIFICATE-----
        \n<内容省略>\n
        -----END PRIVATE KEY-----"
    }
}'

返回示例

{
    "object": "channel",
    "channel": "qpay_pub",
    "banned": false,
    "banned_msg": null,
    "created": 1503573380,
    "description": null,
    "params": {
        "fee_rate": 60,
        "qpay_pub_appid": null,
        "qpay_pub_partner_id": "1326836745",
        "qpay_pub_partner_key": "c7226b0536ec19d3vfc39504fe1410f4",
        "qpay_pub_operator_id": "1352234567027",
        "qpay_pub_operator_pass": "operatorpassword",
        "qpay_pub_client_cert": "-----BEGIN CERTIFICATE-----
        \n<内容省略>\n
        -----END PRIVATE KEY-----",
        "qpay_pub_client_cert_pass": null
    }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1496920721" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
  "channel": "bfb",
  "banned": false,
  "banned_msg": null,
  "description": "description for channel bfb",
  "params": {
    "fee_rate": 60,
    "bfb_sp": "1500300666",
    "bfb_key": "HKaX9Ozz5SGKeLuHiLCm50K8bz5KTuLm"
  }
}'

返回示例

{
  "object": "channel",
  "channel": "bfb",
  "banned": false,
  "banned_msg": null,
  "created": 1496920721,
  "description": "description for channel bfb",
  "params": {
    "fee_rate": 60,
    "bfb_sp": "1500300666",
    "bfb_key": "HKaX9Ozz5SGKeLuHiLCm50K8bz5KTuLm"
  }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/channels \
-H "Pingplusplus-Request-Timestamp: 1496921004" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
  "channel": "bfb",
  "banned": false,
  "banned_msg": null,
  "description": "description for channel bfb_wap",
  "params": {
    "fee_rate": 60,
    "bfb_sp": "1500300666",
    "bfb_key": "HKaX9Ozz5SGKeLuHiLCm50K8bz5KTuLm"
  }
}'

返回示例

{
  "object": "channel",
  "channel": "bfb_wap",
  "banned": false,
  "banned_msg": null,
  "created": 1496921004,
  "description": "description for channel bfb",
  "params": {
    "bfb_sp": "1500300666",
    "fee_rate": 60,
    "bfb_key": "HKaX9Ozz5SGKeLuHiLCm50K8bz5KTuLm"
  }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/sub_apps/app_GaDuf99evvfTi5Wb/transfer_channels \
-H "Pingplusplus-Request-Timestamp: 1501207993" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "channel": "alipay",
    "params": {
        "fee_rate": 3,
        "alipay_app_id": "2016666666666666",
        "alipay_pid": "2088111111111111",
        "alipay_account": "example@example.com",
        "alipay_account_name": "Your Account Name",
        "alipay_sign_type": "rsa",
        "alipay_security_key": "a5srakrbci3nf1pracb52xcs9xlhu8gu",
        "alipay_private_key": "-----BEGIN PRIVATE KEY-----
        \n<内容省略>\n
		  	-----END PRIVATE KEY-----",
        "alipay_public_key": "-----BEGIN PUBLIC KEY-----
        \n<内容省略>\n
			-----END PUBLIC KEY-----",
        "alipay_private_key_rsa2": "-----BEGIN PRIVATE KEY-----
        \n<内容省略>\n
			-----END PRIVATE KEY-----",
        "alipay_public_key_rsa2": "-----BEGIN PUBLIC KEY-----
        \n<内容省略>\n
			-----END PUBLIC KEY-----",
        "alipay_version": 2
    },
    "banned": false,
    "banned_msg": null,
    "description": "description for channel alipay"
}'

返回示例

{
    "object": "channel",
    "channel": "alipay",
    "banned": false,
    "banned_msg": null,
    "created": 1501207993,
    "description": "description for channel alipay",
    "params": {
        "fee_rate": 3,
        "alipay_app_id": "2016666666666666",
        "alipay_pid": "2088111111111111",
        "alipay_account": "example@example.com",
        "alipay_account_name": "Your Account Name",
        "alipay_sign_type": "rsa",
        "alipay_security_key": "a5srakrbci3nf1pracb52xcs9xlhu8gu",
        "alipay_private_key": "-----BEGIN PRIVATE KEY-----
        \n<内容省略>\n
			-----END PRIVATE KEY-----",
        "alipay_public_key": "-----BEGIN PUBLIC KEY-----
        \n<内容省略>\n
			-----END PUBLIC KEY-----",
        "alipay_private_key_rsa2": "-----BEGIN PRIVATE KEY-----
        \n<内容省略>\n
			-----END PRIVATE KEY-----",
        "alipay_public_key_rsa2": "-----BEGIN PUBLIC KEY-----
        \n<内容省略>\n
			-----END PUBLIC KEY-----",
        "alipay_version": 2
    }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/sub_apps/app_GaDuf99evvfTi5Wb/transfer_channels \
-H "Pingplusplus-Request-Timestamp: 1500990342" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "channel": "unionpay",
    "params": {
        "fee_type": 2,
        "fee_rate": 2,
        "mer_id": "898660666666666",
        "priv_key": "[NetPayClient]\nMERID=898660666666123\nprikeyS=\nprikeyE=36****",
        "pub_key": "[NetPayClient]\nPGID=999999999999123\npubkeyS=39****"
    },
    "banned": false,
    "banned_msg": null,
    "description": "description for channel unionpay"
}'

返回示例

{
    "object": "channel",
    "channel": "unionpay",
    "banned": false,
    "banned_msg": null,
    "created": 1500990342,
    "description": "description for channel unionpay",
    "params": {
        "fee_type": 2,
        "fee_rate": 2,
        "mer_id": "898660666666666",
        "priv_key": "[NetPayClient]\nMERID=898660666666123\nprikeyS=\nprikeyE=36****",
        "pub_key": "[NetPayClient]\nPGID=999999999999123\npubkeyS=393****"
    }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/sub_apps/app_GaDuf99evvfTi5Wb/transfer_channels \
-H "Pingplusplus-Request-Timestamp: 1500990342" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "channel": "unionpay_gz",
    "params": {
        "fee_type": 2,
        "fee_rate_b2c": 200,
        "fee_rate_b2b": 300,
        "fee_rate_b2b_large": 500,
        "unionpay_gz_cust_id": "CB0000124084",
        "unionpay_gz_partner_id": "00001012",
        "unionpay_gz_mer_private_key": "-----BEGIN RSA PRIVATE KEY-----\n<内容省略>\n-----END RSA PRIVATE KEY-----"
    },
    "banned": false,
    "banned_msg": null,
    "description": ""
}'

返回示例

{
    "object": "channel",
    "channel": "unionpay",
    "created": 1500990342,
    "params": {
        "fee_type": 2,
        "fee_rate_b2c": 200,
        "fee_rate_b2b": 300,
        "fee_rate_b2b_large": 500,
        "unionpay_gz_cust_id": "CB0000124084",
        "unionpay_gz_partner_id": "00001012",
        "unionpay_gz_mer_private_key": "-----BEGIN RSA PRIVATE KEY-----\n<内容省略>\n-----END RSA PRIVATE KEY-----"
    }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/transfer_channels \
-H "Pingplusplus-Request-Timestamp: 1496923177" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
  "channel": "wx_pub",
  "banned": false,
  "banned_msg": null,
  "description": "description for channel wx_pub",
  "params": {
    "fee_rate": 60,
    "wx_pub_app_id": "wxqjztoo4kaxjabcmj",
    "wx_pub_mch_id": "10066666",
    "wx_pub_key": "65F1DD9AA103883118E7A5B076453BCC",
    "wx_pub_app_secret": "1cbdd4af01854247c8202f970ecc81fa",
    "wx_pub_operator_id": "10066666@10066666",
    "wx_pub_client_cert": "-----BEGIN CERTIFICATE-----your cert -----END CERTIFICATE-----",
    "wx_pub_client_key": "-----BEGIN PRIVATE KEY-----your private key-----END PRIVATE KEY-----"
  }
}'

返回示例

{
  "object": "channel",
  "channel": "wx_pub",
  "banned": false,
  "banned_msg": null,
  "created": 1496923177,
  "description": "description for channel wx_pub",
  "params": {
    "fee_rate": 60,
    "wx_pub_app_id": "wxqjztoo4kaxjabcmj",
    "wx_pub_mch_id": "10066666",
    "wx_pub_key": "65F1DD9AA103883118E7A5B076453BCC",
    "wx_pub_app_secret": "1cbdd4af01854247c8202f970ecc81fa",
    "wx_pub_operator_id": "10066666@10066666",
    "wx_pub_client_cert": "-----BEGIN CERTIFICATE-----your cert -----END CERTIFICATE-----",
    "wx_pub_client_key": "-----BEGIN PRIVATE KEY-----your private key-----END PRIVATE KEY-----"
  }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_LibTW1n1SOq9Pin1/sub_apps/app_GaDuf99evvfTi5Wb/transfer_channels \
-H "Pingplusplus-Request-Timestamp: 1496923177" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "channel": "wx_lite",
    "params": {
        "fee_rate": 60,
        "wx_lite_app_id": "wxf1b140611016a216",
        "wx_lite_mch_id": "1328932817",
        "wx_lite_key": "lGKgtjClGY83o9bDBaiim5A8uxn6ZwO7",
        "wx_lite_app_secret": "afb0a23ad473e4fc3c5545ec3cd96345",
        "wx_lite_operator_id": "operator@1328932817",
        "wx_lite_client_cert": "-----BEGIN CERTIFICATE-----\n<内容省略>\n-----END CERTIFICATE-----",
        "wx_lite_client_key": "-----BEGIN PRIVATE KEY-----\n<内容省略>\n-----END PRIVATE KEY-----"
    },
    "banned": false,
    "banned_msg": null,
    "description": ""
}'

返回示例

{
  "object": "channel",
  "channel": "wx_pub",
  "banned": false,
  "banned_msg": null,
  "created": 1496923177,
  "description": "",
  "params": {
        "fee_rate": 60,
        "wx_lite_app_id": "wxf1b140611016a216",
        "wx_lite_mch_id": "1328932817",
        "wx_lite_key": "lGKgtjClGY83o9bDBaiim5A8uxn6ZwO7",
        "wx_lite_app_secret": "afb0a23ad473e4fc3c5545ec3cd96345",
        "wx_lite_operator_id": "operator@1328932817",
        "wx_lite_client_cert": "-----BEGIN CERTIFICATE-----\n<内容省略>\n-----END CERTIFICATE-----",
        "wx_lite_client_key": "-----BEGIN PRIVATE KEY-----\n<内容省略>\n-----END PRIVATE KEY-----"
    }
}

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/sub_apps/app_GaDuf99evvfTi5Wb/transfer_channels \
-H "Pingplusplus-Request-Timestamp: 1501409444" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '
{
  "channel": "jdpay_transfer",
  "params": {
    "fee_type": 2,
    "fee_rate": 100,
    "jdpay_mer_id": "366666662767266616",
    "jdpay_public_key": "-----BEGIN CERTIFICATE-----\nMII****\n-----END CERTIFICATE-----",
    "jdpay_mer_sign_key": "366666662767266616abc",
    "jdpay_mer_public_key": "-----BEGIN CERTIFICATE-----\nMII****n-----END PRIVATE KEY-----",
    "jdpay_mer_private_key": "-----BEGIN CERTIFICATE-----\nMII****n-----END PRIVATE KEY-----"
  },
  "banned": false,
  "banned_msg": null,
  "description": "description for channel jdpay"
}
'

返回示例

{
    "object": "channel",
    "channel": "jdpay_transfer",
    "banned": false,
    "banned_msg": null,
    "created": 1501409444,
    "description": "description for channel jdpay",
    "params": {
        "fee_type": 2,
        "fee_rate": 100,
        "jdpay_mer_id": "366666662767266616",
        "jdpay_public_key": "-----BEGIN CERTIFICATE-----\nMII****\n-----END CERTIFICATE-----",
        "jdpay_mer_sign_key": "366666662767266616abc",
        "jdpay_mer_public_key": "-----BEGIN CERTIFICATE-----\nMII****\n-----END CERTIFICATE-----",
        "jdpay_mer_private_key": "-----BEGIN PRIVATE KEY-----\nMIIC****\n-----END PRIVATE KEY-----"
    }

请求示例

curl https://api.pingxx.com/v1/apps/app_1Gqj58ynP0mHeX1q/sub_apps/app_GaDuf99evvfTi5Wb/transfer_channels \
-H "Pingplusplus-Request-Timestamp: 1501410563" \
-H "Pingplusplus-Signature: SIGNATURE" \
-u sk_live_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '
{
    "channel": "allinpay",
    "params": {
        "fee_type": 2,
        "fee_rate": 100,
        "allinpay_mer_id": "266566666666662",
        "allinpay_mer_username": "26656666666666264",
        "allinpay_mer_password": "111111",
        "allinpay_public_key": "-----BEGIN CERTIFICATE-----\nMII****\n-----END CERTIFICATE-----",
        "allinpay_mer_private_key": "Bag Attributes\n    localKeyID: 48 10 B9 F7 BE C5 6D 6C C2 8B AE 51 9E 6C AC AD E5 95 D6 97 \n    friendlyName: 266566666666662\nKey Attributes: <No Attributes>\n-----BEGIN PRIVATE KEY-----\nMII****\n-----END PRIVATE KEY-----"
    },
    "banned": false,
    "banned_msg": null,
    "description": "description for channel allinpay"
}
'

返回示例

{
    "object": "channel",
    "channel": "allinpay",
    "banned": false,
    "banned_msg": null,
    "created": 1501410563,
    "description": "description for channel allinpay",
    "params": {
        "fee_type": 2,
        "fee_rate": 100,
        "allinpay_mer_id": "266566666666662",
        "allinpay_mer_username": "26656666666666264",
        "allinpay_mer_password": "111111",
        "allinpay_public_key": "-----BEGIN CERTIFICATE-----\nMII****\n-----END CERTIFICATE-----",
        "allinpay_mer_private_key": "Bag Attributes\n    localKeyID: 48 10 B9 F7 BE C5 6D 6C C2 8B AE 51 9E 6C AC AD E5 95 D6 97 \n    friendlyName: 266566666666662\nKey Attributes: <No Attributes>\n-----BEGIN PRIVATE KEY-----\nMII****\n-----END PRIVATE KEY-----"
    }
}

易宝支付商品类型码

商品类别码 描述
1 虚拟产品
3 公共事业缴费
4 手机充值
6 公益事业
7 实物电商
8 彩票业务
10 行政教育
11 线下服务业
13 微信实物电商
14 微信虚拟电商
15 保险行业
16 基金行业
17 电子票务
18 金融投资
19 大额支付
20 其他
21 旅游机票
22 畅付 D

易宝支付用户标识类型码

代码 备注
0 IMEI 国际移动设备身份码的缩写,国际移动装备辨识码,是由 15 位数字组成的"电子串号",它与每台手机一一对应。
1 MAC 地址 MAC(Media Access Control)地址,或称为 MAC 位址、硬件位址,用来定义网络设备的位置。在 OSI 模型中,第三层网络层负责 IP 地址,第二层数据链路层则负责 MAC 位址。因此一个主机会有一个 IP 地址,而每个网络位置会有一个专属于它的 MAC 位址。
2 用户 ID 用户编号。
3 用户 Email
4 用户手机号
5 用户身份证号
6 用户纸质订单协议号

银联电子代付银行编号说明

open_bank_code open_bank
0100 中国邮政储蓄银行
0102 工商银行
0103 农业银行
0104 中国银行
0105 建设银行
0301 交通银行
0302 中信银行
0303 光大银行
0304 华夏银行
0305 民生银行
0306 广发银行
0308 招商银行
0309 兴业银行
0310 浦发银行
0311 恒丰银行
0313 临沂市商业银行
0316 浙商银行
0317 渤海银行
0318 平安银行
0328 新韩银行(中国)
0329 韩亚银行(中国)
0336 企业银行
0401 上海银行
0402 厦门银行
0403 北京银行
0404 烟台市商业银行
0405 福建海峡银行
0406 吉林银行
0408 宁波银行
0412 温州银行
0413 广州银行
0414 汉口银行
0418 洛阳银行
0420 大连银行
0422 河北银行
0423 杭州商业银行
0424 南京银行
0427 乌鲁木齐市商业银行
0428 绍兴银行
0433 葫芦岛市商业银行
0434 天津银行
0435 郑州银行
0436 宁夏银行
0438 齐商银行
0439 锦州银行
0440 徽商银行
0441 重庆银行
0442 哈尔滨银行
0443 贵阳银行
0447 兰州银行
0448 南昌银行
0449 晋商银行
0450 青岛银行
0455 日照市商业银行
0456 鞍山银行
0458 青海银行
0459 台州银行
0461 长沙银行
0463 赣州银行
0465 营口银行
0467 阜新银行
0474 内蒙古银行
0475 湖州市商业银行
0476 沧州银行
0479 包商银行
0481 威海商业银行
0483 攀枝花市商业银行
0485 绵阳市商业银行
0490 张家口市商业银行
0492 龙江银行
0495 柳州银行
0497 莱商银行
0498 德阳银行
0503 晋城银行
0505 东莞商行
0508 江苏银行
0513 承德市商业银行
0515 德州银行
0517 邯郸市商业银行
0525 浙江民泰商业银行
0526 上饶市商业银行
0527 东营银行
0528 泰安市商业银行
0530 浙江稠州商业银行
0534 鄂尔多斯银行
0537 济宁银行
0547 昆仑银行
0554 邢台银行
0556 漯河商行
1401 上海农商银行
1402 昆山农信社
1403 常熟市农村商业银行
1404 深圳农村商业银行
1405 广州农村商业银行
1408 佛山顺德农村商业银行
1409 昆明农村信用社联合社
1410 湖北农信社
1415 东莞农村商业银行
1416 张家港农村商业银行
1417 福建省农村信用社联合社
1418 北京农村商业银行
1419 天津农村商业银行
1420 宁波鄞州农村合作银行
1424 江苏省农村信用社联合社
1428 江苏吴江农村商业银行
1430 苏州银行
1443 广西农村信用社联合社
1446 黄河农村商业银行
1447 安徽省农村信用社联合社
1448 海南省农村信用社联合社
1513 重庆农村商业银行
6462 潍坊市商业银行
6466 富滇银行
6473 浙江泰隆商业银行
6478 广西北部湾银行
6567 商丘商行

通联代付银行编号说明

open_bank_code open_bank
0100 中国邮政储蓄银行
0102 工商银行
0103 农业银行
0104 中国银行
0105 建设银行
0301 交通银行
0302 中信银行
0303 光大银行
0304 华夏银行
0305 民生银行
0306 广发银行
0308 招商银行
0309 兴业银行
0310 浦发银行
0311 恒丰银行
0313 临沂市商业银行
0316 浙商银行
0317 渤海银行
0318 平安银行
0328 新韩银行(中国)
0329 韩亚银行(中国)
0336 企业银行
0401 上海银行
0402 厦门银行
0403 北京银行
0404 烟台市商业银行
0405 福建海峡银行
0406 吉林银行
0408 宁波银行
0412 温州银行
0413 广州银行
0414 汉口银行
0418 洛阳银行
0420 大连银行
0422 河北银行
0423 杭州商业银行
0424 南京银行
0427 乌鲁木齐市商业银行
0428 绍兴银行
0433 葫芦岛市商业银行
0434 天津银行
0435 郑州银行
0436 宁夏银行
0438 齐商银行
0439 锦州银行
0440 徽商银行
0441 重庆银行
0442 哈尔滨银行
0443 贵阳银行
0447 兰州银行
0448 南昌银行
0449 晋商银行
0450 青岛银行
0455 日照市商业银行
0456 鞍山银行
0458 青海银行
0459 台州银行
0461 长沙银行
0463 赣州银行
0465 营口银行
0467 阜新银行
0474 内蒙古银行
0475 湖州市商业银行
0479 包商银行
0481 威海商业银行
0483 攀枝花市商业银行
0485 绵阳市商业银行
0490 张家口市商业银行
0492 龙江银行
0497 莱商银行
0505 东莞商行
0547 昆仑银行
1401 上海农商银行
1402 昆山农信社
1403 常熟市农村商业银行
1404 深圳农村商业银行
1405 广州农村商业银行
1408 佛山顺德农村商业银行
1409 昆明农村信用社联合社
1410 湖北农信社
1415 东莞农村商业银行
1416 张家港农村商业银行
1418 北京农村商业银行
1419 天津农村商业银行
1420 宁波鄞州农村合作银行
1424 江苏省农村信用社联合社
1447 安徽省农村信用社联合社
1513 重庆农村商业银行
6462 潍坊市商业银行
6473 浙江泰隆商业银行

京东代付银行编号说明

open_bank_code open_bank
0100 中国邮政储蓄银行
0102 工商银行
0103 农业银行
0104 中国银行
0105 建设银行
0301 交通银行
0302 中信银行
0303 光大银行
0304 华夏银行
0305 民生银行
0306 广发银行
0308 招商银行
0309 兴业银行
0310 浦发银行
0311 恒丰银行
0317 渤海银行
0318 平安银行
0328 新韩银行(中国)
0329 韩亚银行(中国)
0401 上海银行
0402 厦门银行
0403 北京银行
0406 吉林银行
0408 宁波银行
0412 温州银行
0413 广州银行
0414 汉口银行
0418 洛阳银行
0420 大连银行
0424 南京银行
0435 郑州银行
0436 宁夏银行
0438 齐商银行
0439 锦州银行
0440 徽商银行
0441 重庆银行
0442 哈尔滨银行
0443 贵阳银行
0447 兰州银行
0450 青岛银行
0465 营口银行
0467 阜新银行
0476 沧州银行
0479 包商银行
0483 攀枝花市商业银行
0492 龙江银行
0508 江苏银行
0515 德州银行
0527 东营银行
0528 泰安市商业银行
0534 鄂尔多斯银行
0537 济宁银行
0554 邢台银行
1401 上海农商银行
1404 深圳农村商业银行
1405 广州农村商业银行
1415 东莞农村商业银行
1446 黄河农村商业银行
1513 重庆农村商业银行

通联代付业务代码说明

业务代码 类型
00601 保险分红
00308 保险给付金
00600 保险理赔
06000 保证金
00603 大病赔款
05101 代发工资
05102 代发奖金
05105 代发劳务费
05103 代发养老金
05100 代发佣金
09900 代付其他
09100 汇款
09500 贷款
09001 基金分红
09000 基金赎回
09999 内部调账
09200 商户退款
00602 退垫付保费
09501 退款
09300 信用卡还款
09400 虚拟账户取现
09998 业务代码摘要测试代付

认证接口 result_code 说明

返回码 返回信息
0 成功
1001 签名验证失败
1002 参数格式不正确
2001 调用第三方接口失败
2002 操作数据库失败
3200 无效的商户号
3204 无效的 sessionId
3300 商户号未找到
3303 商户号与服务访问账号不匹配
3420 请求参数不合法
3431 身份证信息不匹配
3432 身份证信息匹配失败
3433 身份验证活体照片非法
3434 身份验证上传登记照失败
3435 身份验证照片比对失败
3441 银行卡信息认证失败
3442 银行卡信息认证请求异常
3443 银行卡信息认证请求超时
3451 银行卡信息认证校验失败
3452 银行卡信息认证校验异常

海关编号说明

表一 微信海关编号说明

海关编号 参数意义
GUANGZHOU 广州海关
HANGZHOU 杭州海关
NINGBO 宁波海关
SHANGHAI 上海海关
ZHENGZHOU_BS 郑州海关(保税物流中心)
ZHENGZHOU_ZH 郑州海关(综合保税区)
CHONGQING 重庆海关

表二 支付宝海关编号说明

海关编号 参数意义
HANGZHOU 杭州海关
ZHENGZHOU 郑州海关
GUANGZHOU 广州海关
CHONGQING 重庆海关
NINGBO 宁波海关
SHENZHEN 深圳海关
HENAN 河南海关
SHANGHAI 上海海关
XIAN 西安海关
FUJIAN 福建海关
TIANJIN 天津海关
NANSHAGJ 南沙国检
ZONGSHU 海关总署

表三 银联海关编号说明

海关编号 参数意义
ZONGSHU 海关总署
SHENZHEN 深圳海关
NINGBO 宁波海关
GUANGZHOU 广州海关
NANJING 广州海关
HANGZHOU 杭州海关
ZHENGZHOU 郑州海关
CHONGQING 重庆海关
XIAN 西安海关
PINGTAN 福建(平潭)海关

API 更新日志


2017-11-01

  1. 更新 balance 支付渠道 extra 参数说明。详情请参考API文档
  2. 更新 Order 订单有效期延长至 7 天。详情请参考API文档
  3. 新增 Order 订单自定义支付渠道 custom。详情请参考API文档
  4. 新增支付 Order 接口 time_expire 字段。详情请参考API文档
  5. 新增针对微信服务商模式下商户的提示信息。详情请参考API文档
  6. 新增账户系统代付渠道 wx_lite / unionpay_gz 相关文档。详情请参考API文档

2017-10-18

  1. 更新余额充值接口支持自定义渠道给系统用户充值。详情请参考API文档
  2. 新增 QQ 钱包公众号支付。详情请参考API文档
  3. 新增分润结算对象与对应订单列表关联参数。详情请参考API文档
  4. 新增批量企业付款贵州银联代付渠道。详情请参考API文档
  5. 新增支付宝当面付渠道口碑支付。详情请参考API文档

2017-09-20

  1. 新增 Webhooks Event 事件 transfer.failed 示例。详情请参考API文档
  2. 新增微信公众号刷卡支付及支付宝条码支付。详情请参考API文档
  3. 新增企业付款 jdpay allinpay 渠道支持打款至信用卡功能。详情请参考API文档
  4. 新增企业付款贵州银联代付及微信小程序渠道。详情请参考API文档
  5. 新增批量企业付款微信小程序渠道。详情请参考API文档
  6. 新增子商户应用支付渠道参数对于企业付款的相关说明。详情请参考API文档
  7. 新增撤销 Charge 接口。详情请参考API文档

2017-09-04

  1. 更新 Balance Transaction 对象 source 字段描述。详情请参考API文档
  2. 新增 Webhooks Event 事件类型示例。详情请参考API文档

2017-08-30

  1. 更新招行接口(1.0 和 2.0)商户订单号限制规则。详情请参考API文档
  2. 更新 subject、body 字段对于支付宝部分渠道的说明。详情请参考API文档
  3. 更新认证接口 result_code 说明。详情请参考API文档
  4. 新增 Webhooks 事件类型。详情请参考API文档

2017-07-26

  1. 更新 Refund 退款中 funding_source 字段的描述。详情请参考API文档
  2. 更新企业付款 alipay 渠道 extra 字段 recipient_name 参数描述。详情请参考API文档
  3. 更新批量企业付款 alipay 渠道 recipients 字段 name 参数描述。详情请参考API文档
  4. 新增银联网关支付 upacp_pc 渠道 extra 参数 iss_ins_code(发卡机构代码)。详情请参考API文档

2017-07-12

  1. 新增红包状态 refunding:退款中。详情请参考API文档
  2. 新增报关接口针对 C#、Java、Ruby、Python 的示例。详情请参考API文档
  3. 新增身份证银行卡信息认证接口针对 Phyhon、C# 的示例。详情请参考API文档
  4. 新增支付宝电脑网站渠道 2.0 接口参数说明。详情请参考API文档

2017-06-28

  1. 分页 list API 方法中 limit 参数限制范围更新为 1~100,详情请参考API文档
  2. alipayalipay_wap 渠道 extern_token 字段添加说明:仅适用于支付宝 1.0 接口,详情请参考API文档
  3. 更新支付宝各个渠道的 order_no 描述,详情请参考API文档
  4. 新增大数据产品支付数据字段说明,详情请参考API文档

2017-06-15

  1. 『企业付款(银行卡)』渠道名称更新为『银联电子代付』,详情请参考API文档
  2. Charge 支付中 time_settle 属性:『仅针对个人开发者』更新为『暂不生效』,详情请参考API文档
  3. jdpay_wap 渠道中添加 extra 字段 pay_list ,详情请参考API 文档
  4. 新增 Transfers 企业付款渠道:京东代付和通联代付,详情请参考API文档
  5. 新增 Batch Transfers 批量企业付款针对 C# SDK 的示例,详情请参考API文档
  6. 认证中的 C# 语言示例 Pingpp.Key 改为 Pingpp.Pingpp.SetApiKey ,详情请参考API文档
  7. Webhooks 重发次数及通知时间间隔更正,详情请参考API文档

2017-04-26

  1. 新增支付宝 Charges 支付对应支付宝 2.0 接口的花呗分期支付方式、禁用信用卡等新功能;新增对应 extra 返回参数,详情请参考API文档
  2. 调整部分文档格式。

2017-04-19

  1. 新增支付宝渠道的 Transfers 企业付款,详情请参考API文档
  2. 新增支付宝、微信渠道的 Batch Transfers 批量企业付款,详情请参考API文档
  3. 补充红包接口,测试模式下需要主动调用查询接口才能出发 Webhooks 回调,性情请参考API文档

2017-04-05

  1. 补充 Transfers 企业付款付款金额 amount 字段说明,详情请参考API文档
  2. 补充 API 接口错误码和对应报错信息,详情请参考API文档
  3. 新增元数据 Metadata 可选字段,详情请参考API文档

2017-02-15

  1. 新增 customs.succeededbatch_refund.succeeded 两个 Event 事件类型和对应 Event 回调对象示例,详情请参考API文档
  2. 修改支付宝即时到账渠道名为支付宝电脑网站支付,详情请参考API文档
  3. 修改报关接口说明,添加请求接口说明文档中对 applepay_upacp 渠道的支持,详情请参考API文档

2017-02-08

  1. 修改 Transfers 企业付款 description 参数说明,查询 Trasnfer 对象列表 limit 参数说明,详情请参考API文档
  2. 修改 Events 事件类型 summary 类型事件触发时间,详情请参考API文档
  3. 新增 辅助接口、Transfer 对应 unionpay 渠道 API 验签方式说明,详情请参考API文档
  4. 调整部分文档格式。

2017-01-12

  1. 修改报关接口说明文档,去掉不支持拆单的文字描述,新增 trade_no 字段说明,详情请参考API文档
  2. 新增银联全渠道返回参数 pay_typeacc_nopay_card_type,详情请参考API文档
  3. 新增创建 Red Envelope 对象的 extra 参数 scene_id,详情请参考API文档
  4. 新增微信小程序支付渠道 wx_lite ,并添加渠道 extra 参数,详情请参考API文档
  5. 新增 jdpay_wap 京东手机网页支付渠道的 extra 参数,添加可选参数 user_typeuser_id,详情请参考API文档

2016-12-28

  1. 修改请求报关接口 curl 示例,添加请求内容中的 apikey ,添加对应 phpgopython示例文档 ,详情请参考API文档
  2. 添加批量企业付款接口对应 phpgojava 示例文档,详情请参考API文档
  3. 添加批量退款接口对应 phpgo 示例文档,详情请参考API文档
  4. 添加身份认证接口对应 go 示例文档,详情请参考API文档
  5. 修改退款接口对应 java 示例文档,详情请参考API文档
  6. 修改批量退款接口 per_page 默认值为 10 ,详情请参考API文档
  7. 修改批量企业付款请求接口 per_page 默认值为 10 ,详情请参考API文档
  8. 添加支付、批量退款、红包、企业付款、批量企业付款对应查询列表对象接口文档示例,新增请求示例中的 expand[]=app
  9. 修正红包请求接口中 metadata 字段为可选,详情请参考API文档
  10. 修正支付宝电脑网站支付渠道对应 extra 参数,添加返回参数 buyer_account,详情请参考API文档
  11. 调整文档格式,标题栏所有对象名首字母大写。

2016-11-30

  1. 新增批量企业付款到银行卡接口,详情请参考API文档
  2. 新增批量退款查询列表接口请求示例部分的验签示例,详情请参考API文档
  3. 下线 Event 对象列表查询接口。

2016-11-23

  1. 下线应用内快捷支付相关说明文档和示例。

2016-11-16

  1. 新增 metadata 可选字段 phone_number,更新对应语言请求和返回示例,详情请参考API文档
  2. 更新 Node.js SDK 批量企业付款接口,详情请参考API文档
  3. 修改 API 更新日志中批量企业付款链接部分错误,详情请参考API文档

2016-11-09

  1. 调整标题"回调"为"Webhooks 回调",新增相关 Webhooks 通知说明,详情请参考API文档
  2. 修改报关接口部分参数问题,详情请参考API文档
  3. 新增批量企业付款单次请求的企业付款订单数量限制,详情请参考API文档

2016-11-02

  1. 修改文档中"批量付款"为"批量企业付款",详情请参考API文档
  2. 调整文档中交易部分的目录结构顺序,详情请参考API文档
  3. 修改批量退款 和 批量企业付款部分文档示例,修改batch_no字段说明,允许字母和英文,详情请参考API文档
  4. 修改支付渠道属性值,补充各渠道支付场景,详情请参考API文档
  5. 新增更新 Transfer 接口 Node.js SDK 请求示例,详情请参考API文档

2016-10-19

  1. 新增 QQ 钱包渠道说明文档,详情请参考API文档
  2. 新增 微信渠道退款字段 funding_source,详情请参考API文档
  3. 修改 Batch Transfers 批量企业付款接口说明,去掉 transaction_no 字段,修改部分示例代码,详情请参考API文档
  4. 修改 企业付款(银行卡)渠道 order_no 字段说明,只支持 1~16 位纯数字,详情请参考API文档

2016-10-10

  1. 新增身份认证 Java SDK请求示例,详情请参考API文档
  2. 新增 Batch Transfers 批量企业付款接口,详情请参考API文档
  3. 修改 Batch Refunds 批量退款接口查询列表强制验签说明,详情请参考API文档
  4. 新增 batch_transfer.succeeded 批量企业付款 event 事件和事例说明,详情请参考API文档

2016-09-20

  1. 招行一网通渠道修改 extra 参数说明备注,详情请参考API文档
  2. 新增 applepay_upacp 渠道报关文档说明,详情请参考API文档
  3. 修改企业付款和红包接口的文档,不再支持 wx 渠道的企业付款和红包,详情请参考Transfers 企业付款Red envelopes 红包

2016-09-07

  1. 新增银联报关接口,修改原支付宝,微信报关接口参数,接入规则请参考API文档
  2. 新增招行一网通渠道返回参数,extra 中新增优惠金额参数 discount_amount,接入规则请参考API文档

2016-08-24

  1. 新增支付宝批量退款接口,接入规则请参考API文档

2016-08-17

  1. 更新企业付款(银行卡)渠道参数:新增extra字段 open_bank_code 参数,修改 open_bankprovcity 参数为optional,新增该渠道接口调用注意点,接入规则请参考API文档
  2. 新增企业付款(银行卡)银行编号附录,接入规则请参考API文档
  3. 修改 wx_wap 渠道extra字段:去掉 limit_pay 参数,新增 result_url 参数,接入规则请参考API文档

2016-08-10

  1. 新增支付渠道:么么贷 mmdpay_wap,接入规则请参考 API 文档
  2. 添加 charge 对象 time_paid 说明:银联支付成功时间为接收异步通知的时间,请参考API文档

2016-08-03

  1. 新增 alipay_wap 渠道extra字段 app_pay 参数,用于判断是否使用支付宝客户端支付;修改 cancel_url 参数说明,当 app_pay 为true时,cancel_url 字段无效,接入规则参考API文档
  2. 修改招行一网通extra字段参数说明,p_no, seq, m_uid, mobile 这几个参数决定是否签约,传同样的参数,就不会重新签约,具体请参考API文档
  3. 新增 jdpay_wap 渠道extra字段 order_typeis_mobile 参数,接入规则请参考API文档

2016-07-27

  1. 身份证银行卡信息认证接口更新phone_number参数,添加说明:暂不支持178开头的手机号,请参考API文档
  2. 身份证银行卡信息认证接口添加php,ruby对应SDK请求示例和返回示例,接入规则请参考API文档

2016-07-20

  1. 新增 更新 Transfer 对象接口:接入规则请参考API文档
  2. 修改 Customer 对象,Card 对象请求参数:添加sms_code[id]sms_code[code] 参数,修改 Customer 对象 和 Card 对象请求示例,请参考API文档

2016-07-13

  1. 新增支付渠道: 微信WAP支付 wx_wap ,接入规则请参考 API 文档;使用该渠道,需更新客户端 SDK ,请参考 pingpp-js
  2. 修改 身份证银行卡信息认证接口参数:app_id 改成 appidcard 改成 id_cardbankcard 改成 bank_carduser_name 改成 id_name,接入规则请参考 API 文档
  3. 修改 报关接口参数:app_id 改成 app,接入规则请参考 API 文档

2016-07-06

  1. 新增 报关接口,接入规则请参考 API 文档
  2. 新增 企业付款(银行卡)接口,接入规则请参考 API 文档

2016-06-30

  1. 新增支付渠道: 招行一网通 cmb_wallet ,接入规则请参考 API 文档
  2. 新增 身份证银行卡信息认证接口 ,接口规则请参考 API 文档

2016-06-22

退款 Refund 对象中增加商户订单号 charge_order_no 字段,请求退款之后会在返回的 Refund 中带回付款订单的商户订单号,详情参考 API 文档

2016-06-16

升级支付宝手机网站(alipay_wap)支付接口,针对已经接入旧接口的用户请在 3 个月内更新成新接口。旧接口的用户更新只需要三步:

  • 更新客户端 H5 SDK
  • 在服务端请求中增加额外的请求字段 new_version ,详细步骤请参照 alipay_wap 接口更新说明
  • 更新 Ping++ 管理平台上的支付宝手机网站支付的渠道参数,更新成支付宝的 合作伙伴密钥 对应的参数,详情请参考帮助中心
  • 更新到新接口之后,alipay_wap渠道的同步返回参数也会有相应的变更,具体内容请参考 帮助中心

2016-05-18

红包接口和微信官方接口同步:下线 extra 参数中的 nick_namelogoshare_urlshare_contentshare_img 字段。兼容旧接口,已接入用户可忽略该变更;未接入用户请参考 API 文档 进行接入。

2016-04-27

  1. API-微信类接口增加 goods_tag 字段;具体使用方法请参见: API 文档
  2. API-支付宝电脑网站支付可选参数 anti_phishing_key 变更为 enable_anti_phishing_key,为布尔值,具体使用方法请参见: API 文档
  3. API-修复代理商 App 创建微信企业付款( transfer )时报错信息错误的问题;
  4. API-修复红包在测试模式 transaction_no 值为 null 的问题。