Checkout

# Save Bacs Direct Debit bank details Learn how to use Checkout to save payment method details for future Bacs Direct Debit payments. > #### 使用 Accounts v2 API 表示客户 > > Accounts v2 API 通常面向 Connect 用户开放，并对其他 Stripe 用户开放公开预览。如果您参与了 Accounts v2 预览，您需要在代码中[指定预览版本](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning)。 > > 如需申请 Accounts v2 预览版的访问权限， > > 在大多数应用场景下，我们建议[将您的客户建模为客户配置的 Account 对象](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md)，而不是使用 [Customer](https://docs.stripe.com/api/customers.md) 对象。 Use [Stripe Checkout](https://docs.stripe.com/payments/checkout.md) to collect Bacs Direct Debit payment details in advance, with the final amount or payment date determined later. This is useful for: - Saving payment methods to a wallet to streamline future purchases. - Collecting surcharges after fulfilling a service. - [Starting a free trial for a subscription](https://docs.stripe.com/billing/subscriptions/trials.md). ## 设置 Stripe [服务器端] 首先，您需要有 Stripe 账户。[立即注册](https://dashboard.stripe.com/register)。用我们的官方库从您的应用程序访问 Stripe API： #### Ruby ```bash # Available as a gem sudo gem install stripe ``` ```ruby # If you use bundler, you can add this line to your Gemfile gem 'stripe' ``` ## 创建一个 Customer [服务器端] To reuse a Bacs Direct Debit payment method for future payments, you must attach it to a *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments). Create a Customer object when someone creates an account with you and associate the ID of the Customer object with your own internal representation of a customer so you can use the stored payment method details later. If you have an existing Customer object, skip this step. ```curl curl -X POST https://api.stripe.com/v1/customers \ -u "<>:" ``` ## 创建一个 Checkout Session [客户端] [服务器端] [Stripe Checkout](https://docs.stripe.com/payments/checkout.md) provides a hosted payment page that is compliant with Bacs Direct Debit rules. If you would like to design your own Bacs Direct Debit form, please [contact](https://stripe.com/contact/sales) our sales team. Before you can accept Direct Debit payments, your customer must provide their bank account information and give permission to debit their account (also known as a [mandate](https://docs.stripe.com/payments/payment-methods/bacs-debit.md#mandates)) through Stripe Checkout. 在您的网站上添加一个结账按钮，调用一个服务器端点来创建 Checkout Session。 ```html Checkout ``` Create a Checkout Session in `setup` mode to collect the required information. After creating the Checkout Session, redirect your customer to the [URL](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-url) returned in the response. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"="bacs_debit" \ -d mode=setup \ -d customer="{{CUSTOMER_ID}}" \ -d success_url="https://example.com/success?session_id={CHECKOUT_SESSION_ID}" \ ``` When your customer provides their payment method details, they’re redirected to the `success_url`, a page on your website that informs them that their payment method was saved successfully. Make the Session ID available on your success page by including the `{CHECKOUT_SESSION_ID}` template variable in the `success_url` as in the above example. > Don’t rely on the redirect to the `success_url` alone for detecting payment initiation, because: > > - Malicious users could directly access the `success_url` without paying and gain access to your goods or services. - After a successful payment, customers might close their browser tab before they’re redirected to the `success_url`. > The Bacs Direct Debit rules require that customers are sent an email notification when payment details are collected. By default, these emails are sent automatically by Stripe. You can also opt to [send your own Bacs notifications](https://docs.stripe.com/payments/payment-methods/bacs-debit.md#debit-notifications). ## Retrieve the payment method [服务器端] After a customer submits their payment details, retrieve the [PaymentMethod](https://docs.stripe.com/payments/payment-methods.md) object. A *PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) stores the customer’s bank account information for future payments. You can retrieve the PaymentMethod synchronously using the `success_url` or asynchronously using *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests). The decision to retrieve the PaymentMethod synchronously or asynchronously depends on your tolerance for dropoff, as customers might not always reach the `success_url` after a successful payment (for example, it’s possible for them to close their browser tab before the redirect occurs). Using webhooks prevents your integration from experiencing this form of dropoff. #### Webhook Handle `checkout.session.completed` webhooks, which contain a Session object. To learn more, see [setting up webhooks](https://docs.stripe.com/webhooks.md). The following example is a `checkout.session.completed` response. ```json { "id": "evt_1Ep24XHssDVaQm2PpwS19Yt0", "object": "event", "api_version": "2019-03-14", "created": 1561420781, "data": { "object": { "id": "cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k", "object": "checkout.session", "billing_address_collection": null, "client_reference_id": null, "customer": null, "customer_email": null, "display_items": [], "mode": "setup","setup_intent": "seti_1EzVO3HssDVaQm2PJjXHmLlM", "submit_type": null, "subscription": null, "success_url": "https://example.com/success" } }, "livemode": false, "pending_webhooks": 1, "request": { "id": null, "idempotency_key": null }, "type": "checkout.session.completed" } ``` Note the value of the `setup_intent` key, which is the ID for the SetupIntent created with the Checkout Session. A [SetupIntent](https://docs.stripe.com/payments/setup-intents.md) is an object used to set up the customer bank account information for future payments. [Retrieve](https://docs.stripe.com/api/setup_intents/retrieve.md) the SetupIntent object with the ID. The returned object contains the `payment_method` ID. ```curl curl https://api.stripe.com/v1/setup_intents/seti_1EzVO3HssDVaQm2PJjXHmLlM \ -u "<>:" ``` #### 确认 URL Obtain the `session_id` from the URL when a user redirects back to your site and [retrieve](https://docs.stripe.com/api/checkout/sessions/retrieve.md) the Session object. ```curl curl -G https://api.stripe.com/v1/checkout/sessions/{{SESSION_ID}} \ -u "<>:" \ -d "expand[]=setup_intent" ``` > To ensure the `session_id` is available from the URL, include the `session_id={CHECKOUT_SESSION_ID}` template variable in the `success_url` when creating the Checkout Session. Note the SetupIntent created during the Checkout Session. A [SetupIntent](https://docs.stripe.com/payments/setup-intents.md) is an object used to set up the customer bank account information for future payments. The returned object contains the `payment_method` ID. ## Handle post-setup events [服务器端] Once the Checkout Session completes, payment details are submitted to the bank as a mandate. The mandate can change at any time after you’ve collected it. This might be the result of the customer instructing their bank to amend the mandate or because of a change in the bank itself (for example, the customer changes to a different one). Stripe sends the following events when the mandate changes: | Event name | 描述 | Can accept payments? | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | | `mandate.updated` | Occurs whenever a mandate is rejected, canceled, or reactivated by the Bacs network. Check [mandate.status](https://docs.stripe.com/api/mandates/object.md#mandate_object-status) to determine if the mandate can continue to be used. | Yes, if the new status is `active` | | `payment_method.automatically_updated` | Occurs when a customer’s bank account details change. | 是 | These events are available in the [Dashboard](https://dashboard.stripe.com/events), but you can set up a *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) to handle these programmatically. ## 测试集成在 *沙盒环境* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes) 中，您可以使用多个[测试银行账号](https://docs.stripe.com/keys.md#test-live-modes)来确保此集成已准备就绪。您也可以使用对应的令牌，跳过手动输入银行账户详情。 | 分类代码 | 账号 | 令牌 | 描述 | | -------- | ---------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `108800` | `00012345` | `pm_bacsDebit_success` | 付款成功，PaymentIntent 从 `processing` 变为 `succeeded`。 | | `108800` | `90012345` | `pm_bacsDebit_successDelayed` | 三分钟后付款成功，PaymentIntent 从 `processing` 变为 `succeeded`。 | | `108800` | `33333335` | `pm_bacsDebit_debitNotAuthorized` | 付款被接受，但随后立即因失败代码 `debit_not_authorized` 而失败，且 PaymentIntent 状态从 `processing` 转变为 `requires_payment_method`。授权委托变为 `inactive`，且该 PaymentMethod 无法再次使用。 | | `108800` | `93333335` | `pm_bacsDebit_debitNotAuthorizedDelayed` | 付款在三分钟后因失败代码 `debit_not_authorized` 而失败，且 PaymentIntent 状态从 `processing` 转变为 `requires_payment_method`。授权委托变为 `inactive`，且该 PaymentMethod 无法再次使用。 | | `108800` | `22222227` | `pm_bacsDebit_insufficientFunds` | 付款失败，并显示失败代码 `insufficient_funds`，PaymentIntent 从 `processing` 变为 `requires_payment_method`。Mandate 仍为 `active`，PaymentMethod 可再次使用。 | | `108800` | `92222227` | `pm_bacsDebit_insufficientFundsDelayed` | 三分钟后付款失败，并显示失败代码 `insufficient_funds`，PaymentIntent 从 `processing` 变为 `requires_payment_method`。Mandate 仍为 `active`，PaymentMethod 可再次使用。 | | `108800` | `55555559` | `pm_bacsDebit_dispute` | 三分钟后付款成功，PaymentIntent 从 `processing` 变为 `succeeded`，但会立即创建争议。 | | `108800` | `00033333` | `pm_bacsDebit_mandateRefused` | “支付方式”创建成功，但“授权”被客户银行拒绝，立即转为 `inactive` 状态。 | | `108800` | `00044444` | — | 由于账号无效，Bacs 直接借记设置请求立即失败，并提示客户在提交前更新信息。未收集付款信息，因此此情境不存在对应的模拟令牌。 | | `108800` | `34343434` | `pm_bacsDebit_exceedsWeeklyLimit` | 由于支付金额导致账户超过每周支付限额，支付失败了，显示 `charge_exceeds_source_limit` 失败代码。 | | `108800` | `12121212` | `pm_bacsDebit_exceedsTransactionLimit` | 由于付款金额超过账户的交易额度限制，付款失败，并返回 `charge_exceeds_transaction_limit` 失败代码。 | 测试时，可使用上面提供的任意账号。但是，由于 Bacs 直接借记付款需要几天的处理时间，因此使用延迟三分钟的测试账号可以更好地模拟实时付款的行为。 > 默认情况下，Stripe 会在首次收集付款详情以及每次对其账户扣款时，自动向客户发送[电子邮件](https://docs.stripe.com/payments/payment-methods/bacs-debit.md#debit-notifications)。沙盒中不会发送这些通知。 ## Use the payment method for future payments [服务器端] After you set up a *PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs), you can accept future Bacs Direct Debit payments by creating and confirming a [PaymentIntent](https://docs.stripe.com/payments/payment-intents.md). #### curl ```bash curl https://api.stripe.com/v1/payment_intents \ -u <>: \ -d "payment_method_types[]"="bacs_debit" \ -d payment_method="{{PAYMENT_METHOD_ID}}" \ -d customer="{{CUSTOMER_ID}}" \ -d confirm=true \ -d amount=100 \ -d currency=gbp ```