开发者 API
集成与 自定义
通过 URL Scheme 从您自己的应用或网站启动 Payment for Stripe，并直接在 Stripe 控制面板中控制哪些产品显示在应用中。
通过 URL Scheme 集成
工作原理
您的应用打开 payment:// 带参数的 URL
Payment for Stripe 启动并处理交易
完成后，应用会带着结果重定向到您的回调 URL
端点
创建收款
payment://new?处理一次性付款，可设置金额、币种和描述。
参数
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
amount | integer | 是 | 金额以美分为单位（例如，1000 = 10.00 美元） |
currency | string | 否 | 三字母 ISO 货币代码（默认值：应用程序当前使用的货币） |
description | string | 否 | URL 编码的收款描述 |
customer别名: customer_id | string | 否 | 现有 Stripe 客户 ID |
email | string | 否 | 用于发送收据的客户电子邮件 |
name | string | 否 | URL 编码的客户姓名 |
metadata | string | 否 | 自定义键值对（URL 编码的 JSON） |
callback | string | 否 | 完成后返回的 URL |
autoprocess别名: auto | boolean | 否 | 跳过主屏幕，立即开始收款 |
auto_return | boolean | 否 | 当结果加载完毕时触发回调函数，而不是等待商家关闭结果对话框。默认值为 false。 |
出售您目录中的商品
payment://cart?将Stripe目录中的商品价格添加到购物车，以便顾客到店付款。销售记录将保存为已付款的Stripe发票。顾客不会收到任何纸质发票。
参数
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
prices别名: line_items | string | 是 | 以逗号分隔的价格 ID 和数量（例如，price_abc:2,price_xyz:1） |
coupon | string | 否 | 要应用于购物车的Stripe优惠券 ID |
customer别名: customer_id | string | 否 | 现有 Stripe 客户 ID |
email | string | 否 | 用于发送收据的客户电子邮件 |
name | string | 否 | URL 编码的客户姓名 |
metadata | string | 否 | 自定义键值对（URL 编码的 JSON） |
callback | string | 否 | 完成后返回的 URL |
autoprocess别名: auto | boolean | 否 | 跳过主屏幕，立即开始收款 |
auto_return | boolean | 否 | 当结果加载完毕时触发回调函数，而不是等待商家关闭结果对话框。默认值为 false。 |
支付现有发票
payment://invoice?使用Stripe现有发票收取线下付款。金额、币种、客户和税费信息均来自发票。任何修改都将被拒绝。商户可通过读卡器/ Tap to Pay付款；付款成功后，发票将被标记为已通过外部渠道支付，并通过 charge_id 和 payment_intent_id 元数据进行关联。包含订阅、default_payment_method 或状态为已支付、已作废或无法收款的发票将被拒绝，并返回可操作的错误信息。草稿发票：iOS 系统会先确认草稿发票，Android 系统则会使用 invoice_state_changed 拒绝草稿发票。
参数
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
id | string | 是 | Stripe 发票 ID（必须以 in_ 开头） |
callback | string | 否 | 完成后返回的 URL。成功后接收 invoice_id 和 payment_intent_id。 |
metadata | string | 否 | 自定义键值对（URL 编码的 JSON）合并到 PaymentIntent 元数据中 |
autoprocess别名: auto | boolean | 否 | 跳过主屏幕，立即开始收款 |
auto_return | boolean | 否 | 当结果加载完毕时触发回调函数，而不是等待商家关闭结果对话框。默认值为 false。 |
处理回调
交易完成后，Payment for Stripe 会重定向到您的回调 URL，并通过查询参数返回结果。默认情况下，重定向会在商家关闭结果对话框后触发，方便其执行收款后的操作（通过电子邮件发送收据、退款）。传入 auto_return=true 可在结果确定后立即触发。iOS 和 Android 均支持。
回调参数
| 参数 | 值 | 描述 |
|---|---|---|
status | success | error | cancelled | 交易结果 |
charge_id | string | Stripe付款 ID（成功时）。iOS 发送付款 ID (ch_)。Android 发送 PaymentIntent ID (pi_) 并将付款 ID 放入 stripe_charge_id 中。 |
stripe_charge_id | string | Stripe付款成功后会返回付款 ID (ch_)。仅限 Android 系统。 |
invoice_id | string | Stripe 发票 ID（成功时，仅限 payment://invoice 流程） |
payment_intent_id | string | Stripe PaymentIntent ID（成功时）。iOS：仅限 payment://invoice 流程。Android：每笔刷卡交易。 |
error | string | 错误信息（出错时） |
已收取费用，但发票无法标记为已付款：iOS 返回 status=error 以及 charge_id、invoice_id 和 payment_intent_id。Android 返回 status=success 以及 invoice_reconciliation_failed=true。
旧版字段，保留用于旧版集成：success, amount, currency, chargeId, cancelled, error[message]。新版集成应读取以上字段。
示例
简单收款
仅凭金额收款 10.00 美元
payment://new?amount=1000带描述的收款
收款 25.00 欧元并附带描述
payment://new?amount=2500¤cy=eur&description=Coffee%20and%20pastry向新客户收款
收取 50.00 美元并创建客户记录
payment://new?amount=5000&name=John%20Smith&[email protected]向现有客户收款
向现有 Stripe 客户收取 75.00 美元
payment://new?amount=7500&customer=cus_ABC123xyz带元数据的收款
收款 100.00 美元，并附带自定义元数据便于记录
payment://new?amount=10000&description=Invoice%20%231234&metadata=%7B%22order_id%22%3A%221234%22%2C%22location%22%3A%22Store%20A%22%7D自动处理并回调
跳过主屏幕，完成后返回您的应用
payment://new?amount=3500&autoprocess=true&callback=myapp://payment-complete出结果后自动返回
结果一出即触发回调，无需等待商家关闭结果对话框
payment://new?amount=3500&autoprocess=true&auto_return=true&callback=myapp://payment-complete购物车中的商品
从您的Stripe目录中收取产品费用
payment://cart?prices=price_coffee:2,price_muffin:1&[email protected]支付现有发票
针对现有 Stripe 发票收取线下付款。成功后返回 invoice_id 和 payment_intent_id。
payment://invoice?id=in_1ABC123xyz&autoprocess=true&callback=myapp://invoice-paid完整示例
组合所有参数，实现完整集成流程
payment://new?amount=15000¤cy=usd&description=Service%20Fee&customer=cus_ABC123xyz&metadata=%7B%22invoice%22%3A%22INV-2024-001%22%7D&autoprocess=true&callback=myapp://payment-resultURL 编码
请记住对参数值中的特殊字符进行 URL 编码。空格会编码为 %20，花括号会编码为 %7B 和 %7D。