聚合支付¶
支付¶
关于支付，Adapay 系统内数据是通过 Charge对象 的形式进行流转，所有的支付相关信息都会存储在这个对象中，您可以通过 Adapay 开放的方法创建一个新的 Charge对象，也可以通过 Charge对象 的唯一标识 id 来查询一个已经存在的 Charge对象 状态。
使用 Adapay 前端 SDK 进行支付时，也会用到 Charge对象，服务端在传 Charge对象 到客户端进行支付前，请先使用序列化方式将对象转换成 JSON 字符串。
Charge对象¶
属性 |
类型 |
描述 |
|---|---|---|
id |
String |
由 Adapay 生成的支付对象 id， 该 id 在 Adapay 系统内唯一 |
created |
Timestamp |
支付创建时的 Unix 时间戳 |
order_no |
String |
商户订单号 |
livemode |
boolean |
是否为测试模式 |
app_id |
String |
商户发起支付的应用 id，不同的前端应用将无法使用该 Charge对象 完成支付 |
pay_channel |
String |
支付渠道，参见 支付渠道 说明 |
amount |
String |
交易金额，单位：元 |
currency |
String |
详见 货币代码 |
query_url |
String |
可临时用来查询支付订单状态的链接，此链接的有效期与订单有效期相同 |
description |
String |
订单附加说明 |
extra |
Map |
支付渠道请求成功返回的额外参数。详见 支付渠道 extra参数 说明 |
status |
String |
当前订单支付状态，参见 支付状态 说明 |
failure_code |
String |
错误码，详见 错误 |
failure_msg |
String |
错误描述，详见 错误 |
type |
String |
错误类型，详见 错误 |
param |
String |
当发生参数错误时返回具体的参数名，便于定位错误原因，详见 错误 |
创建支付¶
当您想发起一次支付请求时需要通过 Adapay 提供的创建方法获取一个新的 Charge对象，您可使用此 Charge对象 发起支付。 对于支付结果，Adapay 会发送 异步消息通知 告知。
请求参数¶
参数 |
类型 |
必填 |
描述 |
|---|---|---|---|
order_no |
String(64) |
Y |
商户订单号 |
app_id |
String(10) |
Y |
商户交易使用的应用对象 id |
pay_channel |
String(20) |
Y |
支付渠道，参见 支付渠道 |
amount |
String(14) |
Y |
订单总金额（必须大于 0），单位：元 |
subject |
String(32) |
Y |
商品标题 |
body |
String(128) |
Y |
商品描述信息 |
currency |
String(3) |
N |
3位 ISO 货币代码，小写字母，默认为人民币：cny，详见 货币代码 |
description |
String(128) |
N |
订单附加说明 |
time_expire |
String(20) |
N |
订单失效时间，输入格式：yyyyMMddHHmmSS，默认失效时间为创建订单后的 15分钟 |
device_info |
Map |
N |
前端设备信息，详见 设备信息 DeviceInfo |
extra |
Map |
N |
特定渠道发起交易时需要的额外参数，JSON格式，数据内容 key-value 形式填入，详见 支付渠道 extra参数 |
调用示例¶
Java
// 请求参数
Map<String, Object> chargeParams = new HashMap<String, Object>();
chargeParams.put("order_no", "123456789");
chargeParams.put("amount", "998.00");
chargeParams.put("app_id", "001");
chargeParams.put("pay_channel", "alipay");
chargeParams.put("subject", "Your Subject");
chargeParams.put("body", "Your Body");
// 调用创建方法，获取 Charge对象_
Charge ch = Charge.create(chargeParams);
PHP
// 调用创建方法，获取 Charge对象
$ch = \AdaPay\Charge::create(array(
'order_no' => '123456789',
'amount' => '998.00',
'app_id' => 'sfjeijibbTe5jLGCi5rzfH4OqPW9KCif913',
'pay_channel' => 'alipay',
'subject' => 'Your Subject',
'body' => 'Your Body'
));
Python
// 调用创建方法，获取 Charge对象
ch = AdaPay.Charge.create(
order_no = '1234567890',
amount = 998.00,
app_id = 'sfjeijibbTe5jLGCi5rzfH4OqPW9KCif913',
pay_channel = 'alipay',
subject = 'Your Subject',
body = 'Your Body'
)
成功响应
{
"id": "ch_Hm5uTSifDOuTy9iLeLPSurrD",
"created": 1410778843,
"order_no": "123456789",
"livemode": true,
"app_id": "sfjeijibbTe5jLGCi5rzfH4OqPW9KCif913",
"pay_channel": "alipay",
"amount": "998.00",
"currency": "cny",
"query_url": "https://AdaPay.cloudpnr.com/charge/tmp?token=5jLGCi5rzfH4OqPW9KCi",
"status": "pending",
"description": "Charge Discription",
"extra": {
"pay_info": "bax028781ovixf6i8xyf60be"
}
}
支付查询¶
您可以在任何时候，使用查询接口确认支付状态。通过 Charge对象 的 id 查询一个已创建的 Charge对象。
请求参数¶
参数 |
类型 |
必填 |
描述 |
|---|---|---|---|
charge_id |
String |
Y |
由 Adapay 生成的支付对象 id |
调用示例¶
Java
// 在完成初始化设置情况下，调用查询方法，获取 Charge 查询结果
Charge ch = Charge.query("ch_Hm5uTSifDOuTy9iLeLPSurrD");
PHP
// 在完成初始化设置情况下，调用查询方法，获取 Charge 查询结果
$ch = \AdaPay\Charge::query('ch_Hm5uTSifDOuTy9iLeLPSurrD');
Python
// 在完成初始化设置情况下，调用查询方法，获取 Charge 查询结果
ch = Charge.query('ch_Hm5uTSifDOuTy9iLeLPSurrD');
成功响应
{
"id": "ch_Hm5uTSifDOuTy9iLeLPSurrD",
"created": 1410778843,
"order_no": "123456789",
"livemode": true,
"app_id": "sfjeijibbTe5jLGCi5rzfH4OqPW9KCif913",
"pay_channel": "alipay",
"amount": "998.00",
"currency": "cny",
"query_url": "https://AdaPay.cloudpnr.com/charge/tmp?token=5jLGCi5rzfH4OqPW9KCi",
"status": "pending",
"description": "Charge Discription",
"extra": {
"pay_info": "bax028781ovixf6i8xyf60be"
}
}
关单¶
针对已经创建的 Charge对象，您可以调用关单接口进行交易的关闭。调用此接口后，该用户订单将不再能支付成功。 对于关单功能的使用有如下规则：
1.存在关单记录，不能再次关单
2.交易时间一分钟内无法关单成功
3.正扫交易时间超过2小时无法关单成功
4.支付宝正扫接口，如果用户没有扫码，订单不能关闭成功（二维码给用户展示，如果用户没有用手机去扫码，那这笔就不能关单； 如果用户扫过了的话（无需支付成功）就可以关单了）—-微信正扫无此条限制
对于已经成功付款的订单，请使用 退款 接口进行退款处理。我们建议您只有针对未支付的订单调用关单接口。
请求参数¶
参数 |
类型 |
必填 |
描述 |
|---|---|---|---|
charge_id |
String(32) |
Y |
由 Adapay 生成的支付对象 id |
description |
String(255) |
Y |
关单描述 |
响应¶
关单的结果将通过一个 JSON 同步返回，返回参数如下：
参数 |
描述 |
|---|---|
charge_id |
由 Adapay 生成的支付对象 id |
created |
支付创建时的 Unix 时间戳 |
status |
当前订单状态 |
failure_code |
错误码，当发生参数、网络或支付等相关错误时会存在内容，详见 错误 |
failure_msg |
错误描述，当发生参数、网络或支付等相关错误时会存在内容，详见 错误 |
type |
错误类型，当发生参数、网络或支付等相关错误时会存在内容，详见 错误 |
param |
当发生参数错误时返回具体的参数名，便于定位错误原因，详见 错误 |
调用示例¶
Java
// 在完成初始化设置情况下，调用关单方法获取结果
String result = Charge.close("ch_Hm5uTSifDOuTy9iLeLPSurrD", "Description");
PHP
// 在完成初始化设置情况下，调用关单方法获取结果
$result = \AdaPay\Charge::close(array(
'charge_id' => 'ch_Hm5uTSifDOuTy9iLeLPSurrD',
'discription' => 'Description'
));
Python
// 在完成初始化设置情况下，调用关单方法获取结果
result = AdaPay.Charge.close(
'charge_id' => 'ch_Hm5uTSifDOuTy9iLeLPSurrD',
'discription' => 'Description'
);
成功响应
{
"charge_id": "ch_Hm5uTSifDOuTy9iLeLPSurrD",
"created": 1410778843,
"status": "success"
}
退款¶
当您的业务需要发起退款时，可通过 Adapay 系统提供的创建 Refund对象 方法创建一个退款对象，发起退款请求。
Refund对象¶
属性 |
类型 |
描述 |
|---|---|---|
id |
String |
由 Adapay 生成的退款对象 id |
charge_id |
String |
退款目标支付对象 id |
amount |
String |
退款金额 |
trans_state |
String |
退款状态 |
created |
String |
退款对象创建时间 |
fee_amt |
String |
退款手续费 |
failure_code |
String |
错误码，当发生参数、网络或支付等相关错误时会存在内容，详见 错误 |
failure_msg |
String |
错误描述，当发生参数、网络或支付等相关错误时会存在内容，详见 错误 |
type |
String |
错误类型，当发生参数、网络或支付等相关错误时会存在内容，详见 错误 |
param |
String |
当发生参数错误时返回具体的参数名，便于定位错误原因，详见 错误 |
创建退款¶
通过 Adapay 系统提供的方法可创建 Refund对象 方法，退款只能对已经发生交易并且没有全额退款的 Charge对象 发起。 在退款总额未超过原交易金额时，可以进行多次退款。对于每次退款交易，Adapay 都会通过 异步消息通知 告知退款结果。
请求参数¶
参数 |
类型 |
必填 |
描述 |
|---|---|---|---|
charge_id |
String(32) |
Y |
由 Adapay 生成的支付对象 id |
order_no |
String(64) |
Y |
由商户系统生成退款订单号 |
amount |
String(14) |
Y |
退款金额，单位：元 |
description |
String(512) |
N |
退款描述 |
extra |
String(512) |
N |
扩展域 |
dev_info |
String(1024) |
N |
设备静态信息 |
响应¶
同步返回一个 Refund对象 的 JSON。
调用示例
Java
// 在完成初始化设置情况下，调用方法，获取 Refund对象
Map<String, Object> refundParams = new HashMap<String, Object>();
refundParams.put("charge_id", "ch_Hm5uTSifDOuTy9iLeLPSurrD");
refundParams.put("amount", "998.00");
Refund rf = Refund.create(refundParams);
PHP
// 在完成初始化设置情况下，调用方法，获取 Refund对象
$rf = \AdaPay\Refund::create(array(
'charge_id' => 'ch_Hm5uTSifDOuTy9iLeLPSurrD',
'amount' => '998.00'
));
Python
ch = AdaPay.Charge.create(
charge_id = '1234567890',
amount = 998.00
)
成功响应
{
"id": "rf_Hm5uTSifDOuTy9iLeLPSurrD",
"created": 1410778843,
"charge_id": "ch_Hm5uTSifDOuTy9iLeLPSurrD",
"amount": "99.00",
"trans_state": "refunded",
"fee_amt": "0.00",
"status": "pending"
}
退款查询¶
您可以在任何时候，通过退款查询接口确认支付状态。通过 Refund对象 的 id 查询一个已创建的退款记录。
请求参数¶
参数 |
类型 |
必填 |
描述 |
|---|---|---|---|
refund_id |
String(64) |
Y |
由 Adapay 生成的退款对象 id |
调用示例¶
Java
// 在完成初始化设置情况下，调用查询方法，获取 Refund 查询结果
Refund rf = Refund.query("rf_Hm5uTSifDOuTy9iLeLPSurrD");
PHP
// 在完成初始化设置情况下，调用查询方法，获取 Refund 查询结果
$rf = \AdaPay\Refund::query('rf_Hm5uTSifDOuTy9iLeLPSurrD');
Python
// 在完成初始化设置情况下，调用查询方法，获取 Refund 查询结果
rf = AdaPay.Refund.query('rf_Hm5uTSifDOuTy9iLeLPSurrD');
成功响应
{
"id": "rf_Hm5uTSifDOuTy9iLeLPSurrD",
"created": 1410778843,
"charge_id": "ch_Hm5uTSifDOuTy9iLeLPSurrD",
"amount": "99.00",
"trans_state": "refunded",
"fee_amt": "0.00",
"status": "pending"
}
