stripe 一次性购买

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

POST /bp/asset/stripe/create

接口功能：该接口创建一个一次性支付（one-time payment) 的 stripe 订单，即 stripe payment intent。

请求头部参数 (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 编码
email	string	用户邮箱，可以用于关联订单
use_default_payment_method	bool	选填。是否使用 stripe customer 的 default payment method，默认为 false，即不使用。如果本次支付需要用户输入支付信息（如卡号），则可以不使用该选项，这样支付会使用用户填写的支付方式；如果本次支付希望让用户跳过输入支付信息（如卡号）的步骤，设置该选项为 true，则服务端会尝试使用 stripe customer 的 default payment method 来配置该订单，如果 default payment method 有效，客户端就不再需要用户输入支付信息，可以直接 confirm 订单。目前只支持【通过 setup_intent 创建订阅订单】 (即接口 /bp/asset/stripe_setup_intent 和 /bp/asset/stripe_sub 的联合使用）来设置 stripe customer 的 default payment method。

响应

HTTP 状态码：200

参数	类型	说明
stripe_payment_intent	object	返回的 stripe payment intent 对象（即一次性支付订单）

stripe_payment_intent 数据结构见 stripe_payment_intent 对象说明。

响应示例：

json

{
  "stripe_payment_intent": {
    "amount": 1000,
    "client_secret": "pi_3OoGrUJeDjdpBmRt0ckNRnep_secret_R2XJduJouWqBJ5cI22xEakzT9",
    "currency": "usd",
    "customer_id": "cus_PdXvHigq3f3svX",
    "id": "pi_3OoGrUJeDjdpBmRt0ckNRnep",
    "payment_method_id": "",
    "status": "requires_payment_method"
  }
}

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

json

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

error_type：

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

2. 获取刚支付成功的 stripe 一次性支付(one-off payment) 订单信息并同步用户资产

GET /bp/asset/stripe/sync/

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

接口功能：获取 stripe 一次性支付（one-time payment) 订单的信息, 并同步用户资产。stripe 订单 id 由 URL 路径中的 payment_intent_id 给出。

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

请求头部参数 (Headers)

参考接入 BytePower

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

请求体

无

响应

HTTP 状态码：200

参数	类型	说明
stripe_payment_intent	object	返回的 stripe payment intent 对象（即一次性支付订单）
assets	array	用户的 asset 信息

stripe_payment_intent 数据结构见 stripe_payment_intent 对象说明。

响应示例：

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": "stripe",
      "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
    }
  ],
  "stripe_payment_intent": {
    "amount": 1000,
    "client_secret": "pi_3OoGrUJeDjdpBmRt0ckNRnep_secret_R2XJduJouWqBJ5cI22xEakzT9",
    "currency": "usd",
    "customer_id": "cus_PdXvHigq3f3svX",
    "id": "pi_3OoGrUJeDjdpBmRt0ckNRnep",
    "payment_method_id": "",
    "status": "requires_payment_method"
  }
}

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

json

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

error_type：

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

3. 获取 stripe 一次性支付(one-off payment) 订单信息

GET /bp/asset/stripe_payment_intent/{payment_intent_id}/fetch

接口功能：获取 stripe 一次性支付（one-time payment) 订单的信息。stripe 订单 id 由 URL 路径中的 payment_intent_id 给出。与 sync 接口不同，该接口只查询订单信息，不会同步用户资产。

请求头部参数 (Headers)

参考接入 BytePower

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

请求体

无

响应

HTTP 状态码：200

参数	类型	说明
stripe_payment_intent	object	返回的 stripe payment intent 对象（即一次性支付订单）
assets	array	用户的 asset 信息

stripe_payment_intent 数据结构见 stripe_payment_intent 对象说明。

响应示例：

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": "stripe",
      "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
    }
  ],
  "stripe_payment_intent": {
    "amount": 1000,
    "client_secret": "pi_3OoGrUJeDjdpBmRt0ckNRnep_secret_R2XJduJouWqBJ5cI22xEakzT9",
    "currency": "usd",
    "customer_id": "cus_PdXvHigq3f3svX",
    "id": "pi_3OoGrUJeDjdpBmRt0ckNRnep",
    "payment_method_id": "",
    "status": "requires_payment_method"
  }
}

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

json

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

error_type：

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

4. 更新 stripe customer

POST /bp/asset/stripe_customer/

接口功能：更新 stripe customer 的 email, name, address 信息。 URL 中的 customer_id 参数是 stripe 平台的 customer_id。

请求头部参数 (Headers)

参考接入 BytePower

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

请求体

content-type: "application/json"

Parameters	Type	Required	Desc
email	string	false, 但 3 项参数不能同时为空	合法的邮箱地址
name	string	false, 但 3 项参数不能同时为空	姓名
address	stripe_address object	false, 但 3 项参数不能同时为空	地址

stripe_address 数据结构见 stripe_address 对象说明.

注:

请求体中，email, name 和 address 字段都不要求非空，但一次请求中，要确保其中至少有一项数据为非空，否则 API 会返回错误。
stripe_address 数据结构中只要有一项为非空，整个 address 数据结构就判断为非空。
如果 email 非空，需要是格式合法的 email 地址，否则会返回错误。
如果 address.country 非空，需要是两个字母的国家码缩写，符合 ISO 3166-1 alpha-2 规范。
请求体示例：

json

{
  "email": "abc@163.com",
  "name": "John Smith",
  "address": {
    "city": "Beijing",
    "country": "CN",
    "line1": "XiZhiMen Street",
    "line2": "No 12345",
    "postal_code": "100000",
    "state": "Beijing"
  }
}

响应

HTTP 状态码：200

参数	类型	说明
stripe_customer	stripe_customer object	更新后的 customer 信息

stripe_customer 数据结构见 stripe_customer 对象说明。

响应示例：

json

{
  "stripe_customer": {
    "customer_id": "cus_PdXvHigq3f3svX",
    "name": "John Smith",
    "email": "abc@163.com",
    "address": {
      "city": "Beijing",
      "country": "CN",
      "line1": "XiZhiMen Street",
      "line2": "No 12345",
      "postal_code": "100000",
      "state": "Beijing"
    }
  }
}

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

json

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

error_type：

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

数据结构

stripe_payment_intent

参数	类型	说明
id	string	payment intent (即订单）id
client_secret	string	payment intent 的 client secret, 用于客户端完成支付
status	string	payment intent 的状态，状态说明见intent status 说明文档。状态为 succeeded 时为支付成功
amount	int	价格，对美元来说，单位为分
currency	string	币种，三个字母缩写，如 usd
payment_method_id	string	如果没有使用 use_default_payment_method 参数，新建订单为空，不为空时为支付该订单的支付方式 id
customer_id	string	stripe 平台的 customer id

json

{
  "amount": 1000,
  "client_secret": "pi_3OoGrUJeDjdpBmRt0ckNRnep_secret_R2XJduJouWqBJ5cI22xEakzT9",
  "currency": "usd",
  "customer_id": "cus_PdXvHigq3f3svX",
  "id": "pi_3OoGrUJeDjdpBmRt0ckNRnep",
  "payment_method_id": "",
  "status": "requires_payment_method"
}

stripe_address

参数	类型	说明
city	string	City, district, suburb, town, or village.
country	string	Two-letter country code, 遵循 ISO 3166-1 alpha-2 规范
line1	string	Address line 1 (e.g., street, PO Box, or company name).
line2	string	Address line 2 (e.g., apartment, suite, unit, or building).
postal_code	string	ZIP or postal code.
state	string	State, county, province, or region.

json

{
  "city": "Beijing",
  "country": "CN",
  "line1": "XiZhiMen Street",
  "line2": "No 12345",
  "postal_code": "100000",
  "state": "Beijing"
}

stripe_customer

参数	类型	说明
customer_id	string	stripe customer id
name	string	stripe customer name
email	string	stripe customer email
address	stripe_address object	stripe customer address

json

{
  "customer_id": "cus_PdXvHigq3f3svX",
  "name": "John Smith",
  "email": "abc@163.com",
  "address": {
    "city": "Beijing",
    "country": "CN",
    "line1": "XiZhiMen Street",
    "line2": "No 12345",
    "postal_code": "100000",
    "state": "Beijing"
  }
}

stripe 一次性购买 ​

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

POST /bp/asset/stripe/create ​

请求头部参数 (Headers) ​

请求体 ​

响应 ​

2. 获取刚支付成功的 stripe 一次性支付(one-off payment) 订单信息并同步用户资产 ​

GET /bp/asset/stripe/sync/ ​

请求头部参数 (Headers) ​

请求体 ​

响应 ​

3. 获取 stripe 一次性支付(one-off payment) 订单信息 ​

GET /bp/asset/stripe_payment_intent/{payment_intent_id}/fetch ​

请求头部参数 (Headers) ​

请求体 ​

响应 ​

4. 更新 stripe customer ​

POST /bp/asset/stripe_customer/ ​

请求头部参数 (Headers) ​

请求体 ​

响应 ​

数据结构 ​

stripe_payment_intent ​

stripe_address ​

stripe_customer ​

stripe 一次性购买

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

POST /bp/asset/stripe/create

请求头部参数 (Headers)

请求体

响应

2. 获取刚支付成功的 stripe 一次性支付(one-off payment) 订单信息并同步用户资产

GET /bp/asset/stripe/sync/

请求头部参数 (Headers)

请求体

响应

3. 获取 stripe 一次性支付(one-off payment) 订单信息

GET /bp/asset/stripe_payment_intent/{payment_intent_id}/fetch

请求头部参数 (Headers)

请求体

响应

4. 更新 stripe customer

POST /bp/asset/stripe_customer/

请求头部参数 (Headers)

请求体

响应

数据结构

stripe_payment_intent

stripe_address

stripe_customer