Skip to content

paypal 一次性购买

1. 创建一次性支付(one-off payment) 的 paypal 订单

POST /bp/asset/paypal/create

接口功能:  该接口创建一个一次性支付(one-time payment) 的 paypal 订单。

请求头部参数 (Headers)

参考接入 BytePower

  • X-BytePower-Session-Token:登录后获取用户的 session。
  • X-BytePower-Sign:请求体签名

请求体

参数类型说明
product_idstringproduct_config 中返回的 bytepower product_id
country_codestring用户的国家码,可选参数。国家码为 2 位大写字母,根据 ISO_3166-1 Alpha-2 code 编码。参考链接 ISO_3166-1 Alpha-2 code 编码

响应

  • HTTP 状态码:200
参数类型说明
paypal_orderobject返回的 paypal 订单对象

paypal_order 数据结构见 paypal_order 对象说明

响应示例:

json
{
  "paypal_order": {
    "amount": 157,
    "approve_link_href": "https://www.sandbox.paypal.com/checkoutnow?token=5S461083AJ628890L",
    "currency": "usd",
    "id": "5S461083AJ628890L",
    "status": "CREATED"
  }
}

HTTP 状态码:4xx 描述:错误 响应示例:

json
{
  "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)

参考接入 BytePower

  • X-BytePower-Session-Token:登录后获取用户的 session。
  • X-BytePower-Sign:请求体签名

请求体

参数类型说明
order_idstringpaypal 订单 id

响应

  • HTTP 状态码:200
参数类型说明
paypal_orderobject返回的 paypal 订单对象

paypal_order 数据结构见 paypal_order 对象说明

响应示例:

json
{
  "paypal_order": {
    "amount": 157,
    "approve_link_href": "",
    "currency": "usd",
    "id": "5S461083AJ628890L",
    "status": "COMPLETED"
  }
}

HTTP 状态码:4xx 描述:错误 响应示例:

json
{
  "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)

参考接入 BytePower

  • X-BytePower-Session-Token:登录后获取用户的 session。
  • X-BytePower-Sign:请求体签名

请求体

响应

  • HTTP 状态码:200
参数类型说明
paypal_orderobject返回的 paypal 订单信息
assetsarray用户的 asset 信息

paypal_order 数据结构见 paypal_order 对象说明

响应示例:

json
{
  "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 描述:错误 响应示例:

json
{
  "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)

参考接入 BytePower

  • X-BytePower-Session-Token:登录后获取用户的 session。
  • X-BytePower-Sign:请求体签名

请求体

响应

  • HTTP 状态码:200
参数类型说明
paypal_orderobjectpaypal_order 信息
assetsarray用户的 asset 信息

paypal_order 数据结构见 paypal_order 对象说明

响应示例:

json
{
  "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 描述:错误 响应示例:

json
{
  "error": {
    "error_type": "invalid_parameter",
    "message": "xxxxx"
  }
}

error_type:

  • invalid_parameter (请求参数错误)
  • config_invalid (console 配置问题)
  • backend unavailable (paypal 第三方错误)

数据结构

paypal_order

参数类型说明
idstringpaypal order id
statusstring订单状态,状态说明见paypal order 说明文档。状态为 COMPLETED 时为交易成功
amountint价格,对美元来说,单位为分
currencystring币种,三个字母缩写,如 usd
approve_link_hrefstring用户 approve 订单的 URL,创建订单后,需要引导用户至该页面进行订单确认 (approve),然后再调用 capture 接口进行支付;订单被 approve 后,该字段为空字符串
json
{
  "amount": 157,
  "approve_link_href": "https://www.sandbox.paypal.com/checkoutnow?token=5S461083AJ628890L",
  "currency": "usd",
  "id": "5S461083AJ628890L",
  "status": "CREATED"
}

京ICP备19011570号-2