paypal 订阅

1. 创建 paypal subscription

POST /bp/asset/paypal_sub

接口功能：创建 paypal 订阅订单。服务端返回创建的订阅订单信息和用户当前的资产情况。

请求头部参数 (Headers)

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

请求体

content-type: "application/json"

Parameters	Type	Required	Desc
product_id	string	true	待创建的订阅对应的 bytepower product_id
country_code	string	false	用户的国家码，可选参数。国家码为 2 位大写字母，根据 ISO_3166-1 Alpha-2 code 编码。参考链接。
return_url	string	false	可选参数，用户在 paypal 支付页面 approve 订单后，跳转到的页面，具体说明参考 paypal 官方文档。不填默认为 console 上配置的 return_url。
cancel_url	string	false	可选参数，用户在 paypal 支付页面取消处理订单后，跳转到的页面，具体说明参考paypal 官方文档。不填默认为 console 上配置的 cancel_url

请求体示例：

json

{
  "product_id": "BUYCQD6NV7PLG665"
}

响应

HTTP 状态码：200

参数	Type	Desc
paypal_sub	object	paypal subscription 信息
assets	array	用户的 asset 信息

paypal_sub 数据结构见 paypal_sub 对象说明

响应示例：

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-7X917145DM3139335",
      "quantity": 300,
      "receipt_id": "I-08GVT9V0JTKR",
      "sub_canceled": false,
      "sub_canceled_time": "0001-01-01T00:00:00Z",
      "sub_canceled_ts": 0,
      "total_quantity": 300,
      "type": "subscription",
      "valid_seconds": 101407
    }
  ],
  "paypal_sub": {
    "id": "I-08GVT9V0JTKR",
    "plan_id": "P-86E6357727421122EMXOZZOI",
    "status": "APPROVAL_PENDING",
    "approve_link_href": "https://www.sandbox.paypal.com/webapps/billing/subscriptions?ba_token=BA-8N286094XM6371235",
    "canceled_time": "0001-01-01T00:00:00Z",
    "canceled_ts": 0,
    "last_payment_ts": 0,
    "next_billing_ts": 0,
    "bp_product_id": "BUY4GM3SSXAKHI56",
    "paypal_product_id": "PROD-7X917145DM3139335"
  }
}

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

json

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

error_type：

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

2. 查询刚支付的 paypal subscription，并同步用户资产

GET /bp/asset/paypal_sub/{sub_id}/sync

该接口与 GET /bp/asset/paypal_sub/{sub_id} 接口的功能相同，请优先使用 sync 接口， GET /bp/asset/paypal_sub/{sub_id} 接口已被废弃。

接口功能：获取 paypal subscription 的信息, 并同步用户资产。paypal subscription id 由 URL 路径中的 sub_id 给出。

使用场景：该接口只用于支付成功后，立刻同步用户资产的场景。当用户支付成功后，paypal 会向 bytepower 发送 webhook 通知支付成功，bytepower 接收到 webhook 后为用户加资产。由于 webhook 的发送是异步的，会有延迟，如果客户端想在支付成功后较快地刷新用户资产，可以使用 sync 接口。

请求头部参数 (Headers)

参考接入 BytePower

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

请求体

无

响应

HTTP 状态码：200

参数	Type	Desc
paypal_sub	object	paypal subscription 信息
assets	array	用户的 asset 信息

paypal_sub 数据结构见 paypal_sub 对象说明

响应示例：

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-7X917145DM3139335",
      "quantity": 300,
      "receipt_id": "I-08GVT9V0JTKR",
      "sub_canceled": false,
      "sub_canceled_time": "0001-01-01T00:00:00Z",
      "sub_canceled_ts": 0,
      "total_quantity": 300,
      "type": "subscription",
      "valid_seconds": 101407
    }
  ],
  "paypal_sub": {
    "id": "I-08GVT9V0JTKR",
    "plan_id": "P-86E6357727421122EMXOZZOI",
    "status": "ACTIVE",
    "approve_link_href": "https://www.sandbox.paypal.com/webapps/billing/subscriptions?ba_token=BA-8N286094XM6371235",
    "canceled_time": "0001-01-01T00:00:00Z",
    "canceled_ts": 0,
    "last_payment_ts": 0,
    "next_billing_ts": 0,
    "bp_product_id": "BUY4GM3SSXAKHI56",
    "paypal_product_id": "PROD-7X917145DM3139335",
    "latest_transaction": {
      "id": "51S38762T20035204",
      "status": "COMPLETED",
      "amount": 1000,
      "currency": "usd",
      "ts": 1715675369
    }
  }
}

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

json

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

error_type：

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

3. 查询 paypal subscription 信息

GET /bp/asset/paypal_sub/{sub_id}/fetch

接口功能：获取 paypal subscription 的信息。paypal subscription id 由 URL 路径中的 sub_id 给出。与 sync 接口不同，该接口不会同步用户资产。

请求头部参数 (Headers)

参考接入 BytePower

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

请求体

无

响应

HTTP 状态码：200

参数	Type	Desc
paypal_sub	object	paypal subscription 信息
assets	array	用户的 asset 信息

paypal_sub 数据结构见 paypal_sub 对象说明

响应示例：

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-7X917145DM3139335",
      "quantity": 300,
      "receipt_id": "I-08GVT9V0JTKR",
      "sub_canceled": false,
      "sub_canceled_time": "0001-01-01T00:00:00Z",
      "sub_canceled_ts": 0,
      "total_quantity": 300,
      "type": "subscription",
      "valid_seconds": 101407
    }
  ],
  "paypal_sub": {
    "id": "I-08GVT9V0JTKR",
    "plan_id": "P-86E6357727421122EMXOZZOI",
    "status": "ACTIVE",
    "approve_link_href": "https://www.sandbox.paypal.com/webapps/billing/subscriptions?ba_token=BA-8N286094XM6371235",
    "canceled_time": "0001-01-01T00:00:00Z",
    "canceled_ts": 0,
    "last_payment_ts": 0,
    "next_billing_ts": 0,
    "bp_product_id": "BUY4GM3SSXAKHI56",
    "paypal_product_id": "PROD-7X917145DM3139335",
    "latest_transaction": {
      "id": "51S38762T20035204",
      "status": "COMPLETED",
      "amount": 1000,
      "currency": "usd",
      "ts": 1715675369
    },
    "next_billing_amount": 1000,
    "next_billing_currency": "usd"
  }
}

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

json

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

error_type：

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

4. 升级 paypal 订阅

POST /bp/asset/paypal_sub/{sub_id}/upgrade

接口功能：升级 paypal subscription 至较高级的套餐, paypal subscription id 由 URL 路径中的 sub_id 给出。

套餐的等级规则不由 bytepower 规定，而是产品来确定当前订阅能升级到哪个套餐，推荐在 bytepower console 上配置 product 的 tag 来自定义升级规则。

注意：如果订阅已通过之前的 revise 接口进行了订阅的变更，但 revise 的目标订阅套餐仍未生效，则不能使用该 upgrade 接口进行升级。如果 revise 的目标订阅套餐已经生效，则可使用该 upgrade 接口进行升级。

升级后的行为：

新套餐立即生效，根据当前时刻重新计算订阅周期
新套餐首次付费时支付全款，新套餐生效后会有老套餐的退款，退款按照老套餐使用比例进行计算
实现升级的方法是先创建并支付新订阅，然后再退款并取消老订阅。故新套餐生效后，订阅 id (是 I- 开头的字符串）会发生变化

升级订阅时，原订阅需要是 paypal 平台的订阅, 且目前的订阅状态是 ACTIVE。升级的目标套餐不能有试用期【包括免费试用期和付费试用期】。

调用该接口后，新套餐并没有支付完成，需要将用户引导至返回的 approve_link_href 链接中进行确认和支付（和支付新订阅的流程一致），支付完成后，可以调用 sync 接口实时刷新用户资产。

请求头部参数 (Headers)

参考接入 BytePower

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

请求体

content-type: "application/json"

Parameters	Type	Required	Desc
new_bp_product_id	string	true	待升级的 bytepower product_id

请求体示例：

json

{
  "new_bp_product_id": "BUYCQD6NV7PLG665"
}

响应

HTTP 状态码：200

参数	Type	Desc
paypal_sub	object	paypal subscription 信息
assets	array	用户的 asset 信息

paypal_sub 数据结构见 paypal_sub 对象说明

响应示例：

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-7X917145DM3139335",
      "quantity": 300,
      "receipt_id": "I-08GVT9V0JTKR",
      "sub_canceled": false,
      "sub_canceled_time": "0001-01-01T00:00:00Z",
      "sub_canceled_ts": 0,
      "total_quantity": 300,
      "type": "subscription",
      "valid_seconds": 101407
    }
  ],
  "paypal_sub": {
    "id": "I-08GVT9V0JTKR",
    "plan_id": "P-86E6357727421122EMXOZZOI",
    "status": "APPROVAL_PENDING",
    "approve_link_href": "https://www.sandbox.paypal.com/webapps/billing/subscriptions?ba_token=BA-8N286094XM6371235",
    "canceled_time": "0001-01-01T00:00:00Z",
    "canceled_ts": 0,
    "last_payment_ts": 0,
    "next_billing_ts": 0,
    "bp_product_id": "BUY4GM3SSXAKHI56",
    "paypal_product_id": "PROD-7X917145DM3139335"
  }
}

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

json

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

error_type：

invalid_parameter (请求参数错误)
config_invalid （console 配置问题）
subscription_unsupported_upgrade (不支持的升级操作，如原订阅不是 paypal 订阅)
backend unavailable (paypal 第三方错误)
invalid_operation （非法的升级操作，如当前订阅不处于活跃状态）

5. 查询刚升级的 paypal subscription，并同步用户资产

GET /bp/asset/paypal_sub/{sub_id}/sync_upgrade

接口功能：获取 paypal subscription 的信息, 并同步用户资产。paypal subscription id 由 URL 路径中的 sub_id 给出。

使用场景：该接口只用于升级支付成功后，立刻同步用户资产的场景。当用户支付成功后，paypal 会向 bytepower 发送 webhook 通知支付成功，bytepower 接收到 webhook 后为用户加资产。由于 webhook 的发送是异步的，会有延迟，如果客户端想在支付成功后较快地刷新用户资产，可以使用 sync_upgrade 接口。

请求头部参数 (Headers)

参考接入 BytePower

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

请求体

无

响应

HTTP 状态码：200

参数	Type	Desc
paypal_sub	object	paypal subscription 信息
assets	array	用户的 asset 信息

paypal_sub 数据结构见 paypal_sub 对象说明

响应示例：

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-7X917145DM3139335",
      "quantity": 300,
      "receipt_id": "I-08GVT9V0JTKR",
      "sub_canceled": false,
      "sub_canceled_time": "0001-01-01T00:00:00Z",
      "sub_canceled_ts": 0,
      "total_quantity": 300,
      "type": "subscription",
      "valid_seconds": 101407
    }
  ],
  "paypal_sub": {
    "id": "I-08GVT9V0JTKR",
    "plan_id": "P-86E6357727421122EMXOZZOI",
    "status": "ACTIVE",
    "approve_link_href": "https://www.sandbox.paypal.com/webapps/billing/subscriptions?ba_token=BA-8N286094XM6371235",
    "canceled_time": "0001-01-01T00:00:00Z",
    "canceled_ts": 0,
    "last_payment_ts": 0,
    "next_billing_ts": 0,
    "bp_product_id": "BUY4GM3SSXAKHI56",
    "paypal_product_id": "PROD-7X917145DM3139335",
    "latest_transaction": {
      "id": "51S38762T20035204",
      "status": "COMPLETED",
      "amount": 1000,
      "currency": "usd",
      "ts": 1715675369
    }
  }
}

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

json

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

error_type：

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

数据结构

paypal_sub

参数	类型	说明明
id	string	paypal 订阅 id
plan_id	string	paypal 订阅对应的 plan_id
status	string	订阅状态，参考 paypal 文档
approve_link_href	string	付款的重定向 url，前端直接跳转到此地址让用户付款
canceled_ts	int	订阅取消时间的秒级时间戳。如果订阅没有取消，则为 0；如果订阅已经取消，则为已取消时间的时间戳（过去时间的时间戳）
canceled_time	string	订阅取消时间。如果订阅没有取消，则为 0001-01-01T00:00:00Z；如果订阅已经取消，则为已取消时间（过去的时间）。该字段已废弃，请使用 canceled_ts 字段
last_payment_ts	int	最近一次支付的秒级时间戳
next_billing_ts	int	下次支付的秒级时间戳, 订阅状态为 ACTIVE 时有效。
bp_product_id	string	订阅关联的 bytepower product_id
paypal_product_id	string	订阅关联的 paypal product id
latest_transaction	paypal_sub_transaction 对象	订阅最近的 transaction。如果订阅没有 transaction，则不返回该字段
next_billing_amount	int	下个周期扣款金额，美元以分计。订阅状态为 ACTIVE 时有效。该字段只在 fetch 接口返回
next_billing_currency	string	一个周期扣款币种，币种缩写小写，如 usd。订阅状态为 ACTIVE 时有效。该字段只在 fetch 接口返回

举例如下:

json

{
  "id": "I-08GVT9V0JTKR",
  "plan_id": "P-86E6357727421122EMXOZZOI",
  "status": "ACTIVE",
  "approve_link_href": "https://www.sandbox.paypal.com/webapps/billing/subscriptions?ba_token=BA-8N286094XM6371235",
  "canceled_time": "0001-01-01T00:00:00Z",
  "canceled_ts": 0,
  "last_payment_ts": 0,
  "next_billing_ts": 0,
  "bp_product_id": "BUY4GM3SSXAKHI56",
  "paypal_product_id": "PROD-7X917145DM3139335",
  "latest_transaction": {
    "id": "51S38762T20035204",
    "status": "COMPLETED",
    "amount": 1000,
    "currency": "usd",
    "ts": 1715675369
  },
  "next_billing_amount": 1000,
  "next_billing_currency": "usd"
}

paypal_sub_transaction

参数	类型	说明明
id	string	paypal 订阅 transaction id
status	string	transaction 状态，具体参考 paypal 文档的 status 字段
amount	int	transaction 交易金额，如果币种是美元，则该字段单位为美分。其它币种的单位还有待确定。
currency	string	transaction 交易币种，小写字母表示，如 usd
ts	int	transaction 处理时间的秒级时间戳

paypal 订阅 ​

1. 创建 paypal subscription ​

POST /bp/asset/paypal_sub ​

请求头部参数 (Headers) ​

请求体 ​

响应 ​

2. 查询刚支付的 paypal subscription，并同步用户资产 ​

GET /bp/asset/paypal_sub/{sub_id}/sync ​

请求头部参数 (Headers) ​

请求体 ​

响应 ​

3. 查询 paypal subscription 信息 ​

GET /bp/asset/paypal_sub/{sub_id}/fetch ​

请求头部参数 (Headers) ​

请求体 ​

响应 ​

4. 升级 paypal 订阅 ​

POST /bp/asset/paypal_sub/{sub_id}/upgrade ​

请求头部参数 (Headers) ​

请求体 ​

响应 ​

5. 查询刚升级的 paypal subscription，并同步用户资产 ​

GET /bp/asset/paypal_sub/{sub_id}/sync_upgrade ​

请求头部参数 (Headers) ​

请求体 ​

响应 ​

数据结构 ​

paypal_sub ​

paypal_sub_transaction ​

paypal 订阅

1. 创建 paypal subscription

POST /bp/asset/paypal_sub

请求头部参数 (Headers)

请求体

响应

2. 查询刚支付的 paypal subscription，并同步用户资产

GET /bp/asset/paypal_sub/{sub_id}/sync

请求头部参数 (Headers)

请求体

响应

3. 查询 paypal subscription 信息

GET /bp/asset/paypal_sub/{sub_id}/fetch

请求头部参数 (Headers)

请求体

响应

4. 升级 paypal 订阅

POST /bp/asset/paypal_sub/{sub_id}/upgrade

请求头部参数 (Headers)

请求体

响应

5. 查询刚升级的 paypal subscription，并同步用户资产

GET /bp/asset/paypal_sub/{sub_id}/sync_upgrade

请求头部参数 (Headers)

请求体

响应

数据结构

paypal_sub

paypal_sub_transaction