paypal 一次性购买
1. 创建一次性支付(one-off payment) 的 paypal 订单
POST /bp/asset/paypal/create
接口功能: 该接口创建一个一次性支付(one-time payment) 的 paypal 订单。
请求头部参数 (Headers)
- X-BytePower-Session-Token:登录后获取用户的 session。
- X-BytePower-Sign:请求体签名
请求体
参数 | 类型 | 说明 |
---|---|---|
product_id | string | product_config 中返回的 bytepower product_id |
country_code | string | 用户的国家码,可选参数。国家码为 2 位大写字母,根据 ISO_3166-1 Alpha-2 code 编码。参考链接 ISO_3166-1 Alpha-2 code 编码 |
响应
- HTTP 状态码:200
参数 | 类型 | 说明 |
---|---|---|
paypal_order | object | 返回的 paypal 订单对象 |
paypal_order 数据结构见 paypal_order 对象说明。
响应示例:
{
"paypal_order": {
"amount": 157,
"approve_link_href": "https://www.sandbox.paypal.com/checkoutnow?token=5S461083AJ628890L",
"currency": "usd",
"id": "5S461083AJ628890L",
"status": "CREATED"
}
}
HTTP 状态码:4xx 描述:错误 响应示例:
{
"error": {
"error_type": "invalid_parameter",
"message": "xxxxx"
}
}
error_type:
- invalid_parameter (请求参数错误)
- config_invalid (console 配置问题)
- backend unavailable (paypal 第三方错误)
2. 支付一次性支付(one-off payment) 的 paypal 订单
POST /bp/asset/paypal/capture
接口功能: 该接口支付一个一次性支付(one-time payment) 的 paypal 订单。
创建订单后,首先让用户在 approve_link_href
指向的网页中进行确认,然后再调用该接口进行支付。支付完成后,订单状态为 COMPLETED 表示支付成功。
请求头部参数 (Headers)
- X-BytePower-Session-Token:登录后获取用户的 session。
- X-BytePower-Sign:请求体签名
请求体
参数 | 类型 | 说明 |
---|---|---|
order_id | string | paypal 订单 id |
响应
- HTTP 状态码:200
参数 | 类型 | 说明 |
---|---|---|
paypal_order | object | 返回的 paypal 订单对象 |
paypal_order 数据结构见 paypal_order 对象说明。
响应示例:
{
"paypal_order": {
"amount": 157,
"approve_link_href": "",
"currency": "usd",
"id": "5S461083AJ628890L",
"status": "COMPLETED"
}
}
HTTP 状态码:4xx 描述:错误 响应示例:
{
"error": {
"error_type": "invalid_parameter",
"message": "xxxxx"
}
}
error_type:
- invalid_parameter (请求参数错误)
- config_invalid (console 配置问题)
- backend unavailable (paypal 第三方错误)
3. 获取刚支付成功的 paypal 一次性支付(one-off payment) 订单信息并同步用户资产
GET /bp/asset/paypal/sync/
接口功能: 获取 paypal 一次性支付(one-time payment) 订单的信息, 并同步用户资产。paypal 订单 id 由 URL 路径中的 order_id 给出。
使用场景:该接口只用于支付成功后,立刻同步用户资产的场景。当用户支付成功后,paypal 会向 bytepower 发送 webhook 通知支付成功,bytepower 接收到 webhook 后为用户加资产。由于 webhook 的发送是异步的,会有延迟,如果客户端想在支付成功后较快地刷新用户资产,可以使用该 sync 接口。
请求头部参数 (Headers)
- X-BytePower-Session-Token:登录后获取用户的 session。
- X-BytePower-Sign:请求体签名
请求体
无
响应
- HTTP 状态码:200
参数 | 类型 | 说明 |
---|---|---|
paypal_order | object | 返回的 paypal 订单信息 |
assets | array | 用户的 asset 信息 |
paypal_order 数据结构见 paypal_order 对象说明。
响应示例:
{
"assets": [
{
"custom_expire_time": "0001-01-01T00:00:00Z",
"expire_time": "2024-02-28T06:33:24Z",
"is_auto_renewable": true,
"is_consumable": true,
"is_trial_period": true,
"name": "vip",
"origin": "purchase",
"platform": "paypal",
"product_id": "prod_Nf6dZGfCIERbqP",
"quantity": 300,
"receipt_id": "sub_1OnxkeJeDjdpBmRtQTvwiUeA",
"sub_canceled": false,
"sub_canceled_time": "0001-01-01T00:00:00Z",
"sub_canceled_ts": 0,
"total_quantity": 300,
"type": "subscription",
"valid_seconds": 101407
}
],
"paypal_order": {
"amount": 157,
"approve_link_href": "",
"currency": "usd",
"id": "5S461083AJ628890L",
"status": "COMPLETED"
}
}
HTTP 状态码:4xx 描述:错误 响应示例:
{
"error": {
"error_type": "invalid_parameter",
"message": "xxxxx"
}
}
error_type:
- invalid_parameter (请求参数错误)
- config_invalid (console 配置问题)
- backend unavailable (paypal 第三方错误)
4. 获取 paypal 一次性支付(one-off payment) 订单信息
GET /bp/asset/paypal/{order_id}/fetch
接口功能: 获取 paypal 一次性支付(one-time payment) 订单的信息。paypal 订单 id 由 URL 路径中的 order_id 给出。与 sync 接口不同,该接口只查询订单信息,不会同步用户资产。
请求头部参数 (Headers)
- X-BytePower-Session-Token:登录后获取用户的 session。
- X-BytePower-Sign:请求体签名
请求体
无
响应
- HTTP 状态码:200
参数 | 类型 | 说明 |
---|---|---|
paypal_order | object | paypal_order 信息 |
assets | array | 用户的 asset 信息 |
paypal_order 数据结构见 paypal_order 对象说明。
响应示例:
{
"assets": [
{
"custom_expire_time": "0001-01-01T00:00:00Z",
"expire_time": "2024-02-28T06:33:24Z",
"is_auto_renewable": true,
"is_consumable": true,
"is_trial_period": true,
"name": "vip",
"origin": "purchase",
"platform": "paypal",
"product_id": "prod_Nf6dZGfCIERbqP",
"quantity": 300,
"receipt_id": "sub_1OnxkeJeDjdpBmRtQTvwiUeA",
"sub_canceled": false,
"sub_canceled_time": "0001-01-01T00:00:00Z",
"sub_canceled_ts": 0,
"total_quantity": 300,
"type": "subscription",
"valid_seconds": 101407
}
],
"paypal_order": {
"amount": 157,
"approve_link_href": "",
"currency": "usd",
"id": "5S461083AJ628890L",
"status": "COMPLETED"
}
}
HTTP 状态码:4xx 描述:错误 响应示例:
{
"error": {
"error_type": "invalid_parameter",
"message": "xxxxx"
}
}
error_type:
- invalid_parameter (请求参数错误)
- config_invalid (console 配置问题)
- backend unavailable (paypal 第三方错误)
数据结构
paypal_order
参数 | 类型 | 说明 |
---|---|---|
id | string | paypal order id |
status | string | 订单状态,状态说明见paypal order 说明文档。状态为 COMPLETED 时为交易成功 |
amount | int | 价格,对美元来说,单位为分 |
currency | string | 币种,三个字母缩写,如 usd |
approve_link_href | string | 用户 approve 订单的 URL,创建订单后,需要引导用户至该页面进行订单确认 (approve),然后再调用 capture 接口进行支付;订单被 approve 后,该字段为空字符串 |
{
"amount": 157,
"approve_link_href": "https://www.sandbox.paypal.com/checkoutnow?token=5S461083AJ628890L",
"currency": "usd",
"id": "5S461083AJ628890L",
"status": "CREATED"
}