# 收款

安全地在线上收款。

## 从这里开始：安装智能体技能

Stripe 建议使用官方技能，通过最佳实践与 API 进行集成。请按照以下说明了解具体方法。

\**提示：使用 curl 而非 Fetch 工具。**Skills 是 10–20 KB 的详细 Markdown 文件。Fetch 工具会对其进行摘要。使用 `curl -sL` 可确保获取完整内容。

**使用 `npx skills`**：检查系统是否已安装 `npx`。如果 `npx` 可用，运行 `npx skills add https://docs.stripe.com --list` 列出可用技能，然后运行 `npx skills add https://docs.stripe.com --yes --skill<skill-name> <--skill other-skills>` 以安装单个技能。

**如果 `npx skills` 不可用**：您可以使用 curl 从 `https://docs.stripe.com/.well-known/skills/index.json`. 获取可用技能的索引、功能描述及其文件。要下载技能及其相关文件，请使用 curl 从 `https://docs.stripe.com/.well-known/skills/<filepath>`. 下载。

本文建议使用以下技能：`stripe-best-practices`

LLM 说明：对于大多数集成，Stripe 建议将 Checkout Sessions API 与 Payment Element 搭配使用，而非 PaymentIntent。Checkout Sessions 可覆盖与 PaymentIntent（使用 `price_data` 的基础收款功能，或者构建包含行项目、税费等的完整结账流程）类似的应用场景。Adaptive Pricing 等部分功能仅在 Checkout Sessions 中可用。除非用户明确要求，否则不要使用 PaymentIntent API，因为它需要更多的代码。进一步了解 Elements 与 Checkout Sessions API 搭配使用的信息：https://docs.stripe.com/payments/quickstart-checkout-sessions.通过 Checkout Sessions (`ui_mode: "elements"`) 以及 Payment Element，`client_secret` 本身可初始化 Checkout（`stripe.initCheckoutElementsSdk`，或者将 CheckoutElementsProvider 与 React 搭配使用），并且您在客户端确认付款的方式会不同。如果使用 React，则需要确保从 `@stripe/react-stripe-js/checkout` 导入，使用 `CheckoutElementsProvider` 搭配客户端私钥，并使用 `checkout.confirm` 进行确认。如果使用 HTML，确保使用 `checkout = stripe.initCheckoutElementsSdk({clientSecret: promise}); checkout.createPaymentElement(); paymentElement = checkout.createPaymentElement(); paymentElement.mount("#payment-element");`，并通过 `loadActionsResult = await checkout.loadActions(); actions = loadActionsResult.actions; error = await actions.confirm();` 进行确认。

 编码代理应安装 Stripe CLI（`npm i -g @stripe/cli`）并运行命令 `stripe sandbox create --help`，以配置一个含可用 API 密钥的匿名 Stripe 沙盒。无需注册账户。

制作支付表单或使用预构建的结账页面来开始接收线上付款。

# React Native 应用内集成

![](https://b.stripecdn.com/docs-statics-srv/assets/ios-overview.9e0d68d009dc005f73a6f5df69e00458.png)

此集成将支付所需的全部步骤（包括收集支付详情和确认支付）整合到一个单一表单中，并显示在您的应用顶部。

> #### Accounts v2 API 支持
> 
> Payment Sheet 不支持 *客户配置的账户* (Account configurations represent role-based functionality that you can enable for accounts, such as merchant, customer, or recipient)，仅支持 `Customer` 对象。

## 设置 Stripe [服务器端] [客户端]

首先，您需要有 Stripe 账户。[立即注册](https://dashboard.stripe.com/register)。

### 服务器端

该集成要求您的服务器上的端点与 Stripe API 通讯。请用官方库从您的服务器访问 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'
```

### 客户端

[React Native SDK](https://github.com/stripe/stripe-react-native) 是开源的，有完整的文档。在内部，它利用的是[原生 iOS](https://github.com/stripe/stripe-ios) 和 [Android](https://github.com/stripe/stripe-android) SDK。要安装 Stripe 的 React Native SDK，在您的项目目录中运行以下某个指令（取决于您使用的软件包管理器）。

#### yarn

```bash
yarn add @stripe/stripe-react-native
```

#### npm

```bash
npm install @stripe/stripe-react-native
```

然后，安装一些其他必要的依赖项：

- 对于 iOS，请转到 **ios** 目录并运行 `pod install` 以确保同时安装了所需的本地依赖项。
- 对于 Android，无需安装其他依赖项。

> 建议按照[官方 TypeScript 指南](https://reactnative.dev/docs/typescript#adding-typescript-to-an-existing-project)添加 TypeScript 支持。

### Stripe 初始化

要在您的 React Native 应用中初始化 Stripe，使用 `StripeProvider` 组件包裹您的支付界面，或者使用 `initStripe` 初始化方法。只需要 `publishableKey` 中的 API [公钥](https://docs.stripe.com/keys.md#obtain-api-keys)。下例显示的是用 `StripeProvider` 组件初始化 Stripe 的方式。

```jsx
import { useState, useEffect } from 'react';
import { StripeProvider } from '@stripe/stripe-react-native';

function App() {
  const [publishableKey, setPublishableKey] = useState('');

  const fetchPublishableKey = async () => {
    const key = await fetchKey(); // fetch key from your server here
    setPublishableKey(key);
  };

  useEffect(() => {
    fetchPublishableKey();
  }, []);

  return (
    <StripeProvider
      publishableKey={publishableKey}
      merchantIdentifier="merchant.identifier" // required for Apple Pay
      urlScheme="your-url-scheme" // required for 3D Secure and bank redirects
    >
      {/* Your app code here */}
    </StripeProvider>
  );
}
```

> 测试与开发时使用 API [测试模式](https://docs.stripe.com/keys.md#obtain-api-keys)，发布时使用[真实模式](https://docs.stripe.com/keys.md#test-live-modes)密钥。

## 启用支付方式

查看您的[支付方式设置](https://dashboard.stripe.com/settings/payment_methods)，启用您想支持的支付方式。您至少需要启用一个支付方式才能创建 *PaymentIntent* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods)。

默认情况下，Stripe 支持信用卡和其他常见的支付方式，可以帮助您获得更多客户，但建议您开启与您的业务和客户相关的其他支付方式。查看[支付方式支持](https://docs.stripe.com/payments/payment-methods/payment-method-support.md)，了解支持的产品和支付方式，并查看我们的[定价页面](https://stripe.com/pricing/local-payment-methods)了解费用。

## 添加端点 [服务器端]

> #### 注意
> 
> 要在创建 PaymentIntent 之前显示 PaymentSheet，请参阅[收集支付详情后再创建 Intent](https://docs.stripe.com/payments/accept-a-payment-deferred.md?type=payment)。

该集成使用三个 Stripe API 对象：

1. [PaymentIntent](https://docs.stripe.com/api/payment_intents.md)：Stripe 用它来表示您从客户收款的意图，跟踪您的扣款尝试及整个过程中付款状态的变化情况。

2. （可选） [客户配置的 Account](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-applied_configurations) 或 [Customer](https://docs.stripe.com/api/customers.md) 对象：若要设置用于后续支付的支付方式，必须将其关联至客户。当客户在您的业务平台创建账户时，新建一个对象来代表该客户。如果客户以访客身份进行支付，您可在支付前创建一个 `Account` 对象或 `Customer` 对象，并在后续将其与您内部系统中的客户账户记录相关联。

3. （可选） [CustomerSession](https://docs.stripe.com/api/customer_sessions.md)：用于表示客户的对象信息属于敏感数据，无法从应用端直接获取。`CustomerSession` 会为 SDK 提供针对 `Account` 或 `Customer` 对象的临时、受限访问权限，并提供额外的配置选项。请查看完整的 [配置选项](https://docs.stripe.com/api/customer_sessions/create.md#create_customer_session-components) 列表。

> 如果您从不为客户保存卡片，也不允许回头客重复使用已保存的卡片，您可以省略您的集成中的 `Account` 或 `Customer` 对象和 `CustomerSession` 对象。

出于安全原因，您的应用无法创建这些对象。相反，在服务器上会添加一个端点，其功能如下：

1. 检索 `Account` 或 `Customer`，或者创建一个新的对象。
2. 为 `Account` 或 `Customer` 创建 [CustomerSession](https://docs.stripe.com/api/customer_sessions.md)。
3. 创建一个 `PaymentIntent`，其中包含 [amount](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-amount)、[currency](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-currency)、 以及 [customer_account](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer_account) 或 [customer](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer)。
4. 将 `PaymentIntent` 的 *客户端私钥* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer))、`CustomerSession` 的 `client_secret`、`Account` 或 `Customer` 的 ID 以及您的 [可发布密钥](https://dashboard.stripe.com/apikeys) 返回给您的应用。

在结账过程中显示给客户的支付方式也包含在 PaymentIntent 中。您可以让 Stripe 从管理平台设置中提取支付方式，也可以手动列出它们。无论选择哪种方式，都要知道在 PaymentIntent 中传递的货币会过滤显示给客户的支付方式。例如，如果您在 PaymentIntent 中传递 `eur`，并且在管理平台中启用了 OXXO，则不会向客户显示 OXXO，因为 OXXO 不支持 `eur` 支付。

除非您的集成需要基于代码的选项来提供支付方式，否则 Stripe 建议使用自动选项。这是因为 Stripe 会评估货币、支付方式限制和其他参数，以确定支持的支付方式列表。优先显示可提高转化率且与货币和客户所在地最相关的支付方式。

#### 从管理平台管理支付方式

您可以从[管理平台](https://dashboard.stripe.com/settings/payment_methods)管理支付方式。Stripe 根据交易金额、货币和支付流程等因素处理符合条件的支付方式的退货。PaymentIntent 是用您在管理平台中配置的支付方式创建的。如不想使用管理平台或想手动指定支付方式，可通过 `payment_method_types` 属性将其列出。

#### curl

```bash
# Create a Customer (use an existing Customer ID if this is a returning customer)
curl https://api.stripe.com/v1/customers \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"

# Create an CustomerSession for the Customer
curl https://api.stripe.com/v1/customer_sessions \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "components[mobile_payment_element][enabled]"=true \
  -d "components[mobile_payment_element][features][payment_method_save]"=enabled \
  -d "components[mobile_payment_element][features][payment_method_redisplay]"=enabled \
  -d "components[mobile_payment_element][features][payment_method_remove]"=enabled

# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="eur" \

  -d "automatic_payment_methods[enabled]"=true \
```

#### 手动列出支付方式

#### curl

```bash
# Create a Customer (use an existing Customer ID if this is a returning customer)
curl https://api.stripe.com/v1/customers \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"

# Create an CustomerSession for the Customer
curl https://api.stripe.com/v1/customer_sessions \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "components[mobile_payment_element][enabled]"=true \
  -d "components[mobile_payment_element][features][payment_method_save]"=enabled \
  -d "components[mobile_payment_element][features][payment_method_redisplay]"=enabled \
  -d "components[mobile_payment_element][features][payment_method_remove]"=enabled

# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="eur" \
  -d "payment_method_types[]"="bancontact" \
  -d "payment_method_types[]"="card" \
  -d "payment_method_types[]"="ideal" \
  -d "payment_method_types[]"="klarna" \
  -d "payment_method_types[]"="sepa_debit" \
```

> 每个支付方式都要支持在 PaymentIntent 中传递的货币，且您的公司必须要位于各支付方式支持的某个国家/地区。查看[支付方式集成选项](https://docs.stripe.com/payments/payment-methods/integration-options.md)页面，查看具体支持哪些。

## 收集付款详情 [客户端]

显示移动端 Payment Element 前，您的结账页面应：

- 显示购买的产品和总金额
- 收集所需的配送信息
- 包含一个结账按钮来展示 Stripe 的 UI

在您的应用的结账表单内，向上一步中创建的后端端点发送网络请求，从 `useStripe` hook 调用 `initPaymentSheet`。

#### Accounts v2

```javascript
export default function CheckoutScreen() {
  const { initPaymentSheet, presentPaymentSheet } = useStripe();
  const [loading, setLoading] = useState(false);

  const fetchPaymentSheetParams = async () => {
    const response = await fetch(`${API_URL}/payment-sheet`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
    });
    const { paymentIntent, ephemeralKey, customer_account } = await response.json();

    return {
      paymentIntent,
      ephemeralKey,
      customer_account,
    };
  };

  const initializePaymentSheet = async () => {
    const {
      paymentIntent,
      ephemeralKey,
      customer_account,
    } = await fetchPaymentSheetParams();

    const { error } = await initPaymentSheet({
      merchantDisplayName: "Example, Inc.",
      customerAccountId: customer_account,
      customerEphemeralKeySecret: ephemeralKey,
      paymentIntentClientSecret: paymentIntent,
      // Set `allowsDelayedPaymentMethods` to true if your business accepts payment
      // methods that complete payment after a delay, like SEPA Debit and Sofort.
      allowsDelayedPaymentMethods: true,
      defaultBillingDetails: {
        name: 'Jane Doe',
      }
    });
    if (!error) {
      setLoading(true);
    }
  };

  const openPaymentSheet = async () => {
    // see below
  };

  useEffect(() => {
    initializePaymentSheet();
  }, []);

  return (
    <Screen>
      <Button
        variant="primary"
        disabled={!loading}
        title="Checkout"
        onPress={openPaymentSheet}
      />
    </Screen>
  );
}
```

#### Customers v1

```javascript

export default function CheckoutScreen() {
  const { initPaymentSheet, presentPaymentSheet } = useStripe();
  const [loading, setLoading] = useState(false);

  const fetchPaymentSheetParams = async () => {
    const response = await fetch(`${API_URL}/payment-sheet`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
    });
    const { paymentIntent, ephemeralKey, customer } = await response.json();

    return {
      paymentIntent,
      ephemeralKey,
      customer,
    };
  };

  const initializePaymentSheet = async () => {
    const {
      paymentIntent,
      ephemeralKey,
      customer,
    } = await fetchPaymentSheetParams();

    const { error } = await initPaymentSheet({
      merchantDisplayName: "Example, Inc.",
      customerId: customer,
      customerEphemeralKeySecret: ephemeralKey,
      paymentIntentClientSecret: paymentIntent,
      // Set `allowsDelayedPaymentMethods` to true if your business can handle payment
      //methods that complete payment after a delay, like SEPA Debit and Sofort.
      allowsDelayedPaymentMethods: true,
      defaultBillingDetails: {
        name: 'Jane Doe',
      }
    });
    if (!error) {
      setLoading(true);
    }
  };

  const openPaymentSheet = async () => {
    // see below
  };

  useEffect(() => {
    initializePaymentSheet();
  }, []);

  return (
    <Screen>
      <Button
        variant="primary"
        disabled={!loading}
        title="Checkout"
        onPress={openPaymentSheet}
      />
    </Screen>
  );
}
```

当客户点击 **Checkout** 按钮时，调用 `presentPaymentSheet()` 来打开表单。客户完成付款后，表单关闭，通过一个可选的 `StripeError<PaymentSheetError>` 解析 promise。

```javascript
export default function CheckoutScreen() {
  // continued from above

  const openPaymentSheet = async () => {
    const { error } = await presentPaymentSheet();

    if (error) {
      Alert.alert(`Error code: ${error.code}`, error.message);
    } else {
      Alert.alert('Success', 'Your order is confirmed!');
    }
  };

  return (
    <Screen>
      <Button
        variant="primary"
        disabled={!loading}
        title="Checkout"
        onPress={openPaymentSheet}
      />
    </Screen>
  );
}
```

如果没有错误，请通知客户操作已完成（例如，通过显示订单确认页面）。

将 `allowsDelayedPaymentMethods` 设置为 true，以允许[延迟通知型](https://docs.stripe.com/payments/payment-methods.md#payment-notification)支付方式，例如美国银行账户。对于这些支付方式，只有当 `PaymentSheet` 完成后才能知道最终的付款状态是成功还是失败。如果您支持这些类型的支付方式，请告知客户他们的订单已被确认，并且仅在付款成功时履行订单（例如，为他们安排发货）。

## 设置返回页面（仅限 iOS） [客户端]

当客户退出您的应用时（例如，在 Safari 浏览器或其银行应用程序中进行验证），为他们提供一种方式，以便他们自动返回到您的应用程序。很多支付方式类型_要求_提供一个返回 URL。如果您不提供这样一个 URL，我们就无法向您的用户显示需要返回 URL 的支付方式，即使您已启用了这些支付方式。

要提供返回 URL，请执行以下操作：

1. [注册](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app#Register-your-URL-scheme) 自定义 URL。不支持通用链接。
2. [配置](https://reactnative.dev/docs/linking) 您的自定义 URL。
3. 设置您的根组件，将 URL 转发到 Stripe SDK，如下所示。

> 如果您在使用 Expo，则在 `app.json` 文件中[设置您的协议](https://docs.expo.io/guides/linking/#in-a-standalone-app)。

```jsx
import { useEffect, useCallback } from 'react';
import { Linking, View } from 'react-native';
import { useStripe } from '@stripe/stripe-react-native';

export default function MyApp() {
  const { handleURLCallback } = useStripe();

  const handleDeepLink = useCallback(
    async (url: string | null) => {
      if (url) {
        const stripeHandled = await handleURLCallback(url);
        if (stripeHandled) {
          // This was a Stripe URL - you can return or add extra handling here as you see fit
        } else {
          // This was NOT a Stripe URL – handle as you normally would
        }
      }
    },
    [handleURLCallback]
  );

  useEffect(() => {
    const getUrlAsync = async () => {
      const initialUrl = await Linking.getInitialURL();
      handleDeepLink(initialUrl);
    };

    getUrlAsync();

    const deepLinkListener = Linking.addEventListener(
      'url',
      (event: { url: string }) => {
        handleDeepLink(event.url);
      }
    );

    return () => deepLinkListener.remove();
  }, [handleDeepLink]);

  return (
    <View>
      <AwesomeAppComponent />
    </View>
  );
}
```

此外，调用 `initPaymentSheet` 方式时设置 `returnURL`：

```js
await initPaymentSheet({
  ...
  returnURL: 'your-app://stripe-redirect',
  ...
});
```

有关 Native URL Scheme（页面内跳转协议）的更多信息，请参考 [Android](https://developer.android.com/training/app-links/deep-linking) 和 [iOS](https://developer.apple.com/documentation/xcode/allowing_apps_and_websites_to_link_to_your_content/defining_a_custom_url_scheme_for_your_app) 文档。

## 处理付款后事件

付款完成时，Stripe 会发送一个 [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) 事件。使用 [管理平台 Webhook 工具](https://dashboard.stripe.com/webhooks)、或按照 [Webhook 指南](https://docs.stripe.com/webhooks/quickstart.md)来接收这些事件并运行操作，例如，向客户发送订单确认邮件、在数据库中记录订单，或启动配送流程。

侦听这些事件，而不是等待客户端回调。在客户端，客户可能会在执行回调之前关闭浏览器窗口或退出应用程序，并且恶意客户端可能会操纵响应。设置您的集成来侦听异步事件，这样才能用单一集成用用接受[不同类型的支付方式](https://stripe.com/payments/payment-methods-guide)。

除了处理 `payment_intent.succeeded` 事件外，建议在使用 Payment Element 收款时也处理其他的这些事件：

| 事件                                                                                                                              | 描述                                                                                                            | 操作                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.succeeded)           | 客户成功完成付款时发送。                                                                                                  | 向客户发送订单确认通知，并*履行* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected)他们的订单。 |
| [payment_intent.processing](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.processing)         | 当客户成功发起付款但并未完成时发送。当客户发起银行借记时，通常会发送此事件。之后将会出现 `payment_intent.succeeded` 或 `payment_intent.payment_failed` 事件。 | 向客户发送订单确认，告知他们的付款正等待处理。对于数字商品，您可能想先履行订单，然后再等付款完成。                                                                                                     |
| [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.payment_failed) | 在客户尝试付款但付款失败时发送。                                                                                              | 如果一笔付款从 `processing` 变为 `payment_failed`，则让客户再尝试一次。                                                                                                   |

## 测试集成

#### 银行卡

| 卡号                  | 场景                                                                                                                                                                                                                                                             | 如何测试                            |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| 4242424242424242    | 该卡付款成功，不需要验证。                                                                                                                                                                                                                                                  | 使用信用卡号以及有效期和 CVC 和邮编填写我们的信用卡表单。 |
| 4000002500003155    | 该卡付款时需要*验证* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase)。 | 使用信用卡号以及有效期和 CVC 和邮编填写我们的信用卡表单。 |
| 4000000000009995    | 该卡被拒绝，显示拒付代码，例如 `insufficient_funds`。                                                                                                                                                                                                                          | 使用信用卡号以及有效期和 CVC 和邮编填写我们的信用卡表单。 |
| 6205500000000000004 | 银联卡的长度为 13-19 位。                                                                                                                                                                                                                                               | 使用信用卡号以及有效期和 CVC 和邮编填写我们的信用卡表单。 |

#### 银行重定向

| 支付方式              | 场景                                                                                                      | 如何测试                                                                                              |
| ----------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Bancontact, iDEAL | 您的客户在基于重定向和立即通知型的支付方式的重定向页面验证失败。                                                                        | 选择基于重定向的任意支付方式，填写必要的信息，并确认付款。然后在重定向页面上点击**让测试付款失败**。                                              |
| 通过银行支付            | 您的客户通过基于重定向和[延迟通知型](https://docs.stripe.com/payments/payment-methods.md#payment-notification)的支付方式成功付款。 | 选择支付方式，填写必要的信息，并确认付款。然后在重定向页面上点击**测试付款成功**。                                                       |
| 通过银行支付            | 您的客户在基于重定向和延迟通知型的支付方式的重定向页面验证失败。                                                                        | 选择支付方式，填写必要的信息，并确认付款。然后在重定向页面上点击**让测试付款失败**。                                                      |
| BLIK              | 有多个 BLIK 支付失败的情况——立即失败（例如，代码已过期或无效）、延迟的错误（银行拒付）或超时（客户未及时响应）。                                            | 使用电子邮件模式[模拟不同的失败情况](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures)。 |

#### 银行借记

| 支付方式      | 场景                                                      | 如何测试                                                                  |
| --------- | ------------------------------------------------------- | --------------------------------------------------------------------- |
| SEPA 直接借记 | 您的客户成功用 SEPA 直接借记完成付款。                                  | 用账号 `AT321904300235473204` 填写表单。确认的 PaymentIntent 最初变为处理中，三分钟后变为成功状态。 |
| SEPA 直接借记 | 您的客户的付款意图状态从 `processing` 变为 `requires_payment_method`。 | 用账号 `AT861904300235473202` 填写表单。                                      |

有关测试您的集成的更多信息，请参阅[测试](https://docs.stripe.com/testing.md)部分。

## 启用银行卡扫描 [客户端]

> Apple iOS 应用程序审核流程要求启用卡片扫描功能。Android 应用程序审核流程不要求启用卡片扫描功能，但我们建议启用。

### iOS

若要在 iOS 上启用卡片扫描支持，请在应用程序的 `Info.plist` 中设置 `NSCameraUsageDescription`（**隐私 - 相机使用说明**），并提供访问相机的原因（例如，“用于扫描卡片”）。

### (Optional) Android

若要启用银行卡扫描支持，需在 [Google Pay & Wallet Console](https://pay.google.com/business/console?utm_source=devsite&utm_medium=devsite&utm_campaign=devsite) 中请求 Google Pay API 的[生产访问权限](https://developers.google.com/pay/api/android/guides/test-and-deploy/request-prod-access)。

- 如果您已启用 Google Pay，银行卡扫描功能会在符合条件的设备上自动在我们的用户界面中提供。想了解更多符合条件的设备，请参见[Google Pay API 限制](https://developers.google.com/pay/payment-card-recognition/debit-credit-card-recognition)
- **重要提示：**银行卡扫描功能仅在与 [Google Pay & Wallet Console](https://pay.google.com/business/console) 中注册的签名密钥相同的构建中显示。使用不同签名密钥进行测试或调试的构建（例如通过Firebase App Tester 分发的构建）不会显示**扫描银行卡**选项。要在预发布构建中测试银行卡扫描功能，您必须采取以下措施之一：
  - 使用生产签名密钥对您的测试构建进行签名
  - 将您的测试签名密钥指纹添加到 Google Pay & Wallet Console

如果您的应用不支持 Google Pay，您可以使用 Stripe 卡片扫描功能。

> Stripe 卡片扫描功能目前处于公开预览阶段。

为了启用卡片扫描功能，请将 `stripecardscan` 添加到您的 [app/build.gradle](https://developer.android.com/studio/build/dependencies) 文件的 `dependencies` 代码块中：

#### Groovy

```groovy
implementation 'com.stripe:stripecardscan:23.10.1'
```

## Optional: Enable Link

在您的[支付方式设置](https://dashboard.stripe.com/settings/payment_methods)中启用 Link，让客户可以通过 Link 的一键快速结账按钮，安全地保存并重复使用其支付信息。

### 将客户的邮件地址传递到 Mobile Payment Element

Link 通过客户的电子邮件地址进行身份验证。Stripe 建议尽可能预填信息，以简化结账流程。

要预先填充客户的姓名、邮件地址和电话号码，请将包含客户信息的 `defaultBillingDetails` 提供给 `initPaymentSheet`。

```javascript
await initPaymentSheet({
  ...
  defaultBillingDetails: {
    name: 'Jenny Rosen',
    email: 'jenny.rosen@example.com',
    phone: '888-888-8888',
  },
});
```

### 处理用户登出

`PaymentSheet` 会在本地存储一些信息，用于记住用户是否在应用中使用过 Link。当用户退出登录时，请调用 `resetPaymentSheetCustomer()` 方法以清除 `PaymentSheet` 的内部状态。

```javascript
export default function CheckoutScreen() {
  // continued from above
  const { initPaymentSheet, presentPaymentSheet, resetPaymentSheetCustomer } = useStripe();

  const logout = async () => {
    await resetPaymentSheetCustomer();
  };

  return (
    <Screen>
      <Button
        title="Checkout"
        onPress={openPaymentSheet}
      />
      <Button
        title="Checkout"
        onPress={logout}
      />
    </Screen>
  );
}
```

## Optional: 启用 Apple Pay

### 注册 Apple Merchant ID

可通过在 Apple 开发人员网站[注册新的标识符](https://developer.apple.com/account/resources/identifiers/add/merchant)来获取 Apple 商家 ID。

在表单中填写描述和标识符。描述内容仅供您自己记录之用，之后可随时更改。Stripe 建议用您的应用的名称作为标识符（例如，`merchant.com.{{YOUR_APP_NAME}}`）。

### 创建新的 Apple Pay 证书

为您的应用创建证书，以加密支付数据。

转到管理平台中的 [iOS 证书设置](https://dashboard.stripe.com/settings/ios_certificates)，点击**添加新应用程序**，然后按照说明进行操作。

下载证书签名请求 (CSR) 文件，来从 Apple 获取安全证书，以便使用 Apple Pay。

必须用一个 CSR 文件发布具体的一个证书。如果您切换您的 Apple Merchant ID，则必须前往管理平台的 [iOS 证书设置](https://dashboard.stripe.com/settings/ios_certificates)中获取一个新的 CSR 和证书。

### 集成 Xcode

将 Apple Pay 功能添加到您的应用程序。在 Xcode 中，打开您的项目设置，点击**签名和功能**选项卡，然后添加 **Apple Pay** 功能。此时，系统可能会提示您登入您的开发人员账户。选择您之前创建的商家 ID，您的应用程序就可以接受 Apple Pay 了。
![](https://b.stripecdn.com/docs-statics-srv/assets/xcode.a701d4c1922d19985e9c614a6f105bf1.png)

在 Xcode 中启用 Apple Pay 功能

### 添加 Apple Pay

#### 一次性付款

创建 `StripeProvider` 时传递您的商家 ID：

```javascript
import { StripeProvider } from '@stripe/stripe-react-native';

function App() {
  return (
    <StripeProvider
      publishableKey="<<YOUR_PUBLISHABLE_KEY>>"
      merchantIdentifier="MERCHANT_ID"
    >
      {/* Your app code here */}
    </StripeProvider>
  );
}
```

调用 `initPaymentSheet` 时，传入您的 [ApplePayParams](https://stripe.dev/stripe-react-native/api-reference/modules/PaymentSheet.html#ApplePayParams)：

```javascript
await initPaymentSheet({
  // ...
  applePay: {
    merchantCountryCode: 'US',
  },
});
```

#### 经常性付款

调用 `initPaymentSheet` 时，传入一个 [ApplePayParams](https://stripe.dev/stripe-react-native/api-reference/modules/PaymentSheet.html#ApplePayParams)，将 `merchantCountryCode` 设置为您的业务所在国家/地区的代码。

根据[Apple 的指南](https://developer.apple.com/design/human-interface-guidelines/apple-pay#Supporting-subscriptions)中关于经常性付款的规定，您还必须设置一个 `cardItems`，其中包含一个 [RecurringCartSummaryItem](https://stripe.dev/stripe-react-native/api-reference/modules/ApplePay.html#RecurringCartSummaryItem)，并注明您打算收取的金额（例如，“每月 59.95 美元”）。

还可以通过在将 `request` 的 `type` 设置为 `PaymentRequestType.Recurring` 来采用[商家令牌](https://developer.apple.com/apple-pay/merchant-tokens/)。

要了解有关如何通过 Apple Pay 使用经常性付款的更多信息，请参阅 [Apple 的 PassKit 文档](https://developer.apple.com/documentation/passkit/pkpaymentrequest)。

#### iOS (React Native)

```javascript
const initializePaymentSheet = async () => {
  const recurringSummaryItem = {
    label: 'My Subscription',
    amount: '59.99',
    paymentType: 'Recurring',
    intervalCount: 1,
    intervalUnit: 'month',
    // Payment starts today
    startDate: new Date().getTime() / 1000,

    // Payment ends in one year
    endDate: new Date().getTime() / 1000 + 60 * 60 * 24 * 365,
  };

  const {error} = await initPaymentSheet({
    // ...
    applePay: {
      merchantCountryCode: 'US',
      cartItems: [recurringSummaryItem],
      request: {
        type: PaymentRequestType.Recurring,
        description: 'Recurring',
        managementUrl: 'https://my-backend.example.com/customer-portal',
        billing: recurringSummaryItem,
        billingAgreement:
          "You'll be billed $59.99 every month for the next 12 months. To cancel at any time, go to Account and click 'Cancel Membership.'",
      },
    },
  });
};
```

### 订单跟踪

在 iOS 16 或更高版本中添加[订单跟踪](https://developer.apple.com/design/human-interface-guidelines/technologies/wallet/designing-order-tracking)信息时，请配置一个 `setOrderTracking` 回调函数。Stripe 会在支付完成后调用您实施的程序，但该操作在 iOS 关闭 Apple Pay 表单之前进行。

在您实施的 `setOrderTracking` 回调函数的程序中，从您的服务器获取已完成订单的订单详情，并将该详情传递给提供的 `completion` 函数。

要了解有关订单跟踪的更多信息，请参阅 [Apple 钱包订单文档](https://developer.apple.com/documentation/walletorders)。

#### iOS (React Native)

```javascript
await initPaymentSheet({
  // ...
  applePay: {
    // ...
    setOrderTracking: async complete => {
      const apiEndpoint =
        Platform.OS === 'ios'
          ? 'http://localhost:4242'
          : 'http://10.0.2.2:4567';
      const response = await fetch(
        `${apiEndpoint}/retrieve-order?orderId=${orderId}`,
        {
          method: 'GET',
          headers: {
            'Content-Type': 'application/json',
          },
        },
      );
      if (response.status === 200) {
        const orderDetails = await response.json();
        // orderDetails should include orderIdentifier, orderTypeIdentifier,
        // authenticationToken and webServiceUrl
        complete(orderDetails);
      }
    },
  },
});
```

## Optional: 启用 Google Pay

### 设置您的集成

要使用 Google Pay，先将以下内容添加到您的 **AndroidManifest.xml** 的 `<application>`标签，来启用 Google Pay API：

```xml
<application>
  ...
  <meta-data
    android:name="com.google.android.gms.wallet.api.enabled"
    android:value="true" />
</application>
```

更多详情，请参见 Google Pay 针对 Android 设备编写的[设置 Google Pay API](https://developers.google.com/pay/api/android/guides/setup) 指南。

### 添加 Google Pay

初始化 `PaymentSheet` 时，将 `merchantCountryCode` 设置为您的业务所在的国家/地区的代码 并将 `googlePay` 设置为 true。

您还可以通过传递 `testEnv` 参数来使用测试环境。您只能在实物 Android 设备上测试 Google Pay。遵循 [React Native 文档](https://reactnative.dev/docs/running-on-device)中的说明，在真实设备上测试您的应用。

```javascript
const { error, paymentOption } = await initPaymentSheet({
  // ...
  googlePay: {
    merchantCountryCode: 'US',
    testEnv: true, // use test environment
  },
});
```

## Optional: 自定义表单 [客户端]

所有自定义操作均用 `initPaymentSheet` 来配置。

### 外观

通过使用[外观 API](https://docs.stripe.com/elements/appearance-api/mobile.md?platform=react-native)，自定义颜色、字体等样式，以匹配您应用的外观和风格。

### 商家显示名称

通过设置 `merchantDisplayName` 来指定向客户显示的商业名称。默认情况下，使用的是您的应用的名称。

```javascript
await initPaymentSheet({
  // ...
  merchantDisplayName: 'Example Inc.',
});
```

### 暗色模式

默认情况下，`PaymentSheet` 自动适应用户的整个系统的外观设置（明暗模式）。您可以通过在 iOS 上将 `style` 属性设置为 `alwaysLight` 或 `alwaysDark` 来更改。

```javascript
await initPaymentSheet({
  // ...
  style: 'alwaysDark',
});
```

在您 Android 应用上，设置亮色或暗色模式：

```
// force dark
AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_YES)
// force light
AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_NO)
```

## Optional: 在您的用户界面完成付款

您可以在出示支付表单时仅收集支付方式详情，然后再在您的应用的用户界面上调用 `confirm` 方法来完成付款。如果您使用自定义购买按钮，或在收集了付款详情后需要额外的步骤，这会非常有用。
![](https://b.stripecdn.com/docs-statics-srv/assets/react-native-multi-step.84d8a0a44b1baa596bda491322b6d9fd.png)

> [可在我们的 GitHub](https://github.com/stripe/stripe-react-native/blob/master/example/src/screens/PaymentsUICustomScreen.tsx) 上查看示例集成。

1. 首先，调用 `initPaymentSheet` 并传递 `customFlow: true`。`initPaymentSheet` 通过一个初始支付选项解析，该选项包含显示客户的支付方式的图片和标签。用这些详情更新您的用户界面。

```javascript
const {
  initPaymentSheet,
  presentPaymentSheet,
  confirmPaymentSheetPayment,
} = useStripe()

const { error, paymentOption } = await initPaymentSheet({
  customerId: customer,
  customerEphemeralKeySecret: ephemeralKey,
  paymentIntentClientSecret: paymentIntent,
  customFlow: true,
  merchantDisplayName: 'Example Inc.',
});
// Update your UI with paymentOption
```

1. 用 `presentPaymentSheet` 收集支付详情。客户完成后，表单自行关闭，并解析 promise。用选择的支付方式详情更新您的用户界面。

```javascript
const { error, paymentOption } = await presentPaymentSheet();
```

1. 用 `confirmPaymentSheetPayment` 确认付款。这会通付款结果来解析。

```javascript
const { error } = await confirmPaymentSheetPayment();

if (error) {
  Alert.alert(`Error code: ${error.code}`, error.message);
} else {
  Alert.alert(
    'Success',
    'Your order is confirmed!'
  );
}
```

将 `allowsDelayedPaymentMethods` 设置为 true，以允许[延迟通知型](https://docs.stripe.com/payments/payment-methods.md#payment-notification)支付方式，例如美国银行账户。对于这些支付方式，只有当 `PaymentSheet` 完成后才能知道最终的付款状态是成功还是失败。如果您支持这些类型的支付方式，请告知客户他们的订单已被确认，并且仅在付款成功时履行订单（例如，为他们安排发货）。