# Cash App Pay 支付

Add support for Cash App Pay to your integration.

> Stripe 可以通过评估货币、付款方式限制和其他参数，自动为客户展示相关支付方式。
> 
> - 请遵循[接受付款](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=checkout&ui=stripe-hosted)指南，构建一个使用[动态支付方式](https://docs.stripe.com/payments/payment-methods/dynamic-payment-methods.md)的 Checkout 集成。
- 如果您不想使用动态支付方式，请按照以下步骤在 Checkout 集成中手动配置支付方式。

This guides you through enabling Cash App Pay on [Checkout](https://docs.stripe.com/payments/checkout.md), our hosted checkout form, and shows the differences between accepting a card payment and a Cash App Pay payment.

## 确定兼容性

**支持的商家所在地**：US

**支持的货币**：`usd`

**展示货币**：`usd`

**支付模式**：Yes

**设置模式**：Yes

**订阅模式**：Yes

A Checkout Session must satisfy all of the following conditions to support Cash App Pay payments:

- *Prices* (Prices define how much and how often to charge for products. This includes how much the product costs, what currency to use, and the interval if the price is for subscriptions) for all line items must be expressed in USD.

## Set up Stripe [Server-side]

首先，您需要一个 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'
```

## 收款

> 该指南建立于基本的[接受付款](https://docs.stripe.com/payments/accept-a-payment.md?integration=checkout) Checkout 集成的基础之上。

### Enable Cash App Pay as a payment method

创建新的 [Checkout Session](https://docs.stripe.com/api/checkout/sessions.md) 时，您需要：

1. Add `cashapp` to the list of `payment_method_types`.
1. Make sure all your `line_items` use the `usd` currency.

#### Stripe-hosted page

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price_data][currency]=usd" \
  -d "line_items[0][price_data][product_data][name]=T-shirt" \
  -d "line_items[0][price_data][unit_amount]=2000" \
  -d "line_items[0][quantity]=1" \
  -d mode=payment \
  -d "payment_method_types[0]=card" \
  -d "payment_method_types[1]=cashapp" \
  --data-urlencode "success_url=https://example.com/success"
```

#### Embedded form

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price_data][currency]=usd" \
  -d "line_items[0][price_data][product_data][name]=T-shirt" \
  -d "line_items[0][price_data][unit_amount]=2000" \
  -d "line_items[0][quantity]=1" \
  -d mode=payment \
  -d "payment_method_types[0]=card" \
  -d "payment_method_types[1]=cashapp" \
  --data-urlencode "return_url=https://example.com/return" \
  -d ui_mode=embedded_page
```

### 履行订单

接受付款后，学习如何[履行订单](https://docs.stripe.com/checkout/fulfillment.md)。

## 测试您的集成

#### Mobile web app testing

To test your integration, choose Cash App Pay as the payment method and tap **Pay**. While testing, this redirects you to a test payment page where you can approve or decline the payment.

In live mode, tapping **Pay** redirects you to the Cash App mobile application—you don’t have the option to approve or decline the payment within Cash App. The payment is automatically approved after the redirect.

#### Desktop web app testing

To test your integration, scan the QR code with a QR code scanning application on your mobile device. While testing, the QR code payload contains a URL that redirects you to a test payment page where you can approve or decline the test payment.

In live mode, scanning the QR code redirects you to the Cash App mobile application—you don’t have the option to approve or decline the payment within Cash App. The payment is automatically approved after you scan the QR code.

## See also

- [Checkout fulfillment](https://docs.stripe.com/checkout/fulfillment.md)
- [Customizing Checkout](https://docs.stripe.com/payments/checkout/customization.md)

# Checkout Sessions API

> This is a Checkout Sessions API for when payment-ui is elements and api-integration is checkout. View the full page at https://docs.stripe.com/payments/cash-app-pay/accept-a-payment?payment-ui=elements&api-integration=checkout.

To determine which API meets your business needs, see the [comparison guide](https://docs.stripe.com/payments/checkout-sessions-and-payment-intents-comparison.md).

Use the [Payment Element](https://docs.stripe.com/payments/payment-element.md) to embed a custom Stripe payment form in your website or application and offer payment methods to customers. For advanced configurations and customizations, refer to the [Accept a Payment](https://docs.stripe.com/payments/accept-a-payment.md) integration guide.

## Determine compatibility

**支持的商家所在地**：US

**支持的货币**：`usd`

**展示货币**：`usd`

**支付模式**：Yes

**设置模式**：Yes

**订阅模式**：Yes

A Checkout Session must satisfy all of the following conditions to support Cash App Pay payments:

- *Prices* (Prices define how much and how often to charge for products. This includes how much the product costs, what currency to use, and the interval if the price is for subscriptions) for all line items must be expressed in USD.

## Set up the server [服务器端]

Use the official Stripe libraries to access the API from your application.

#### 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'
```

## Create a Checkout Session [服务器端]

Add an endpoint on your server that creates a [Checkout Session](https://docs.stripe.com/api/checkout/sessions/create.md) and returns its [client secret](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-client_secret) to your front end. A Checkout Session represents your customer’s session as they pay for one-time purchases or subscriptions. Checkout Sessions expire 24 hours after creation.

We recommend using [dynamic payment methods](https://docs.stripe.com/payments/payment-methods/dynamic-payment-methods.md) to dynamically display the most relevant eligible payment methods to each customer to maximize conversion. You can also [manually list payment methods](https://docs.stripe.com/payments/payment-methods/integration-options.md#listing-payment-methods-manually), which disables dynamic payment methods.

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

#### TypeScript

```javascript
import express, {Express} from 'express';

const app: Express = express();

app.post('/create-checkout-session', async (req: Express.Request, res: Express.Response) => {
  const session = await stripe.checkout.sessions.create({
    line_items: [
      {
        price_data: {
          currency: 'usd',
          product_data: {
            name: 'T-shirt',
          },
          unit_amount: 1099,
        },
        quantity: 1,
      },
    ],
    mode: 'payment',
    ui_mode: 'elements',
    return_url: 'https://example.com/return?session_id={CHECKOUT_SESSION_ID}'
  });

  res.json({checkoutSessionClientSecret: session.client_secret});
});

app.listen(3000, () => {
  console.log('Running on port 3000');
});
```

#### Manually list payment methods

#### TypeScript

```javascript
import express, {Express} from 'express';

const app: Express = express();

app.post('/create-checkout-session', async (req: Express.Request, res: Express.Response) => {
  const session = await stripe.checkout.sessions.create({
    line_items: [
      {
        price_data: {
          currency: 'usd',
          product_data: {
            name: 'T-shirt',
          },
          unit_amount: 1099,
        },
        quantity: 1,
      },
    ],
    mode: 'payment',
    ui_mode: 'elements',
    payment_method_types: ['cashapp'],
    return_url: 'https://example.com/return?session_id={CHECKOUT_SESSION_ID}'
  });

  res.json({checkoutSessionClientSecret: session.client_secret});
});

app.listen(3000, () => {
  console.log('Running on port 3000');
});
```

## Set up the front end [客户端]

#### HTML + JS

在您的结账页面包含 Stripe.js 脚本，方法是将其添加到您的 HTML 文件的 `head`。一定直接从 js.stripe.com 加载 Stripe.js，以保持 PCI 合规。请勿将脚本包含在捆绑包中，也不要自己托管其副本。

Make sure you’re on the latest Stripe.js version by including the following script tag `<script src=“https://js.stripe.com/dahlia/stripe.js”></script>`. Learn more about [Stripe.js versioning](https://docs.stripe.com/sdks/stripejs-versioning.md).

```html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/dahlia/stripe.js"></script>
</head>
```

> Stripe 提供一个 npm 工具包，可用于将 Stripe.js 加载为模块。请参阅 [GitHub 上的项目](https://github.com/stripe/stripe-js)。需要 [7.0.0](https://www.npmjs.com/package/%40stripe/stripe-js/v/7.0.0) 或更高版本。

Initialize stripe.js.

```js
// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe(
  '<<YOUR_PUBLISHABLE_KEY>>',
);
```

#### React

Install [React Stripe.js](https://www.npmjs.com/package/@stripe/react-stripe-js) and the [Stripe.js loader](https://www.npmjs.com/package/@stripe/stripe-js) from the npm public registry. You need at least version 5.0.0 for React Stripe.js and version 8.0.0 for the Stripe.js loader.

```bash
npm install --save @stripe/react-stripe-js@^5.0.0 @stripe/stripe-js@^8.0.0
```

使用公钥在前端初始化 `stripe` 实例。

```javascript
import {loadStripe} from '@stripe/stripe-js';
const stripe = loadStripe("<<YOUR_PUBLISHABLE_KEY>>");
```

## Initialize Checkout [客户端]

#### HTML + JS

调用 [initCheckoutElementsSdk](https://docs.stripe.com/js/custom_checkout/init)，并传入 `clientSecret`。

`initCheckoutElementsSdk` 返回一个 [Checkout](https://docs.stripe.com/js/custom_checkout) 对象，其中包含来自 Checkout Session 的数据以及用于更新这些数据的方法。

从 [actions.getSession()](https://docs.stripe.com/js/custom_checkout/session) 中读取 `total` 和 `lineItems`，并在您的用户界面中显示它们。这样您就能以最小的代码改动启用新功能。例如，如果您显示的是 `total`，那么添加 [manual currency prices](https://docs.stripe.com/payments/custom/localize-prices/manual-currency-prices.md) 时就无需修改界面。

```html
<div id="checkout-container"></div>
```

```javascript
const clientSecret = fetch('/create-checkout-session', {method: 'POST'})
  .then((response) => response.json())
  .then((json) => json.client_secret);

const checkout = stripe.initCheckoutElementsSdk({clientSecret});
const loadActionsResult = await checkout.loadActions();

if (loadActionsResult.type === 'success') {
  const session = loadActionsResult.actions.getSession();
  const checkoutContainer = document.getElementById('checkout-container');

  checkoutContainer.append(JSON.stringify(session.lineItems, null, 2));
  checkoutContainer.append(document.createElement('br'));
  checkoutContainer.append(`Total: ${session.total.total.amount}`);
}
```

#### React

使用 [CheckoutElementsProvider](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider) 组件封装您的应用程序，并传入 `clientSecret` 和 `stripe` 实例。

```jsx
import React from 'react';
import {CheckoutElementsProvider} from '@stripe/react-stripe-js/checkout';
import CheckoutForm from './CheckoutForm';

const clientSecret = fetch('/create-checkout-session', {method: 'POST'})
  .then((response) => response.json())
  .then((json) => json.client_secret);

const App = () => {
  return (
    <CheckoutElementsProvider
      stripe={stripe}options={{clientSecret}}
    >
      <CheckoutForm />
    </CheckoutElementsProvider>
  );
};

export default App;
```

在您的结账表单组件中，使用 `useCheckout()` 钩子来访问 [Checkout](https://docs.stripe.com/js/custom_checkout) 对象。该 `Checkout` 对象包含来自结账会话的数据以及用于更新数据的方法。

从 `Checkout` 对象中读取 `total` 和 `lineItems`，并在您的用户界面中显示它们。这样您就能以最小的代码改动启用新功能。例如，如果您显示的是 `total`，那么添加 [manual currency prices](https://docs.stripe.com/payments/custom/localize-prices/manual-currency-prices.md) 时就无需修改界面。

```jsx
import React from 'react';
import {useCheckout} from '@stripe/react-stripe-js/checkout';

const CheckoutForm = () => {const checkoutState = useCheckout();

  if (checkoutState.type === 'loading') {
    return (
      <div>Loading...</div>
    );
  }

  if (checkoutState.type === 'error') {
    return (
      <div>Error: {checkoutState.error.message}</div>
    );
  }

  return (
    <form>{JSON.stringify(checkoutState.checkout.lineItems, null, 2)}
      {/* A formatted total amount */}
      Total: {checkoutState.checkout.total.total.amount}
    </form>
  );
};
```

## Collect customer email [客户端]

#### HTML + JS

完成 Checkout Session 时，您必须提供有效的客户电子邮箱。

这些指令用于创建电子邮件输入框，并调用 `Checkout` 对象中的 [updateEmail](https://docs.stripe.com/js/custom_checkout/update_email)。

或者，您也可以：

- 在创建 Checkout Session 时，请传入 [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_email)、[customer_account](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_account)（针对以客户配置的 `Account` 对象表示的客户）或 [customer](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer)（针对以 `Customer` 对象表示的客户）。Stripe 会对以这种方式提供的电子邮件进行验证。
- 传入您已在 [checkout.confirm](https://docs.stripe.com/js/custom_checkout/confirm) 中验证过的电子邮箱地址。

```html
<input type="text" id="email" />
<div id="email-errors"></div>
```

```javascript
const checkout = stripe.initCheckoutElementsSdk({clientSecret});
const loadActionsResult = await checkout.loadActions();

if (loadActionsResult.type === 'success') {
  const {actions} = loadActionsResult;
  const emailInput = document.getElementById('email');
  const emailErrors = document.getElementById('email-errors');

  emailInput.addEventListener('input', () => {
    // Clear any validation errors
    emailErrors.textContent = '';
  });

  emailInput.addEventListener('blur', () => {
    const newEmail = emailInput.value;actions.updateEmail(newEmail).then((result) => {
      if (result.error) {
        emailErrors.textContent = result.error.message;
      }
    });
  });
}
```

#### React

完成 Checkout Session 时，您必须提供有效的客户电子邮箱。

这些指令用于创建电子邮件输入框，并调用 `Checkout` 对象中的 [updateEmail](https://docs.stripe.com/js/react_stripe_js/checkout/update_email)。

或者，您也可以：

- 在创建 Checkout Session 时，请传入 [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_email)、[customer_account](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_account)（针对以客户配置的 `Account` 对象表示的客户）或 [customer](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer)（针对以 `Customer` 对象表示的客户）。Stripe 会对以这种方式提供的电子邮件进行验证。
- 传入您已在 [confirm](https://docs.stripe.com/js/react_stripe_js/checkout/confirm) 中验证过的电子邮箱地址。

```jsx
import React from 'react';
import {useCheckout} from '@stripe/react-stripe-js/checkout';

const EmailInput = () => {
  const checkoutState = useCheckout();
  const [email, setEmail] = React.useState('');
  const [error, setError] = React.useState(null);

  if (checkoutState.type === 'loading') {
    return (
      <div>Loading...</div>
    );
  } else if (checkoutState.type === 'error') {
    return (
      <div>Error: {checkoutState.error.message}</div>
    );
  }

  const handleBlur = () => {checkoutState.checkout.updateEmail(email).then((result) => {
      if (result.type === 'error') {
        setError(result.error);
      }
    })
  };

  const handleChange = (e) => {
    setError(null);
    setEmail(e.target.value);
  };

  return (
    <div>
      <label htmlFor="checkout-form-email">Email</label>
      <input
        id="checkout-form-email"
        type="email"
        value={email}
        onChange={handleChange}
        onBlur={handleBlur}
      />
      {error && <div>{error.message}</div>}
    </div>
  );
};

export default EmailInput;
```

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

用 [Payment Element](https://docs.stripe.com/payments/payment-element.md) 在客户端收集支付信息。Payment Element 是一个预构建的 UI 组件，它简化了多种支付方式的收集支付详情的流程。

Payment Element 中包含一个 iframe，它通过一个 HTTPS 连接安全地将支付信息发送到 Stripe。避免将 Payment Element 放在另一个 iframe 中，因为有些支付方式需要重定向到另一个页面进行付款确认。

如果您选择使用 iframe 并希望支持 Apple Pay 或 Google Pay，则必须将 iframe 的 [allow](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#attr-allowpaymentrequest) 属性设置为`"payment *"`。

结账页面地址必须以 `https://` rather 开头，而非 `http://` for，您的集成才能正常工作。您可以在不使用 HTTPS 的情况下测试集成，但在准备接收真实付款时，请务必[启用 HTTPS](https://docs.stripe.com/security/guide.md#tls)。

#### HTML + JS

首先，创建一个容器 DOM 元素来挂载 [Payment Element](https://docs.stripe.com/payments/payment-element.md)。然后使用 [checkout.createPaymentElement](https://docs.stripe.com/js/custom_checkout/create_payment_element) 创建 `Payment Element` 的实例，并通过调用 [element.mount](https://docs.stripe.com/js/element/mount) 挂载它，提供 CSS 选择器或容器 DOM 元素。

```html
<div id="payment-element"></div>
```

```javascript
const paymentElement = checkout.createPaymentElement();
paymentElement.mount('#payment-element');
```

请参阅 [Stripe.js文档](https://docs.stripe.com/js/custom_checkout/create_payment_element#custom_checkout_create_payment_element-options) 以查看支持的选项。

您可以通过在前端初始化 Checkout 时传递 [elementsOptions.appearance](https://docs.stripe.com/js/custom_checkout/init#custom_checkout_init-options-elementsOptions-appearance) 来[自定义所有 Element 的外观](https://docs.stripe.com/payments/checkout/customization/appearance.md)。

#### React

在 [CheckoutElementsProvider](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider) 内部挂载 [Payment Element](https://docs.stripe.com/payments/payment-element.md) 组件。

```jsx
import React from 'react';import {PaymentElement, useCheckout} from '@stripe/react-stripe-js/checkout';

const CheckoutForm = () => {
  const checkoutState = useCheckout();

  if (checkoutState.type === 'loading') {
    return (
      <div>Loading...</div>
    );
  }

  if (checkoutState.type === 'error') {
    return (
      <div>Error: {checkoutState.error.message}</div>
    );
  }

  return (
    <form>

      {JSON.stringify(checkoutState.checkout.lineItems, null, 2)}
      {/* A formatted total amount */}
      Total: {checkoutState.checkout.total.total.amount}
<PaymentElement options={{layout: 'accordion'}}/>
    </form>
  );
};

export default CheckoutForm;
```

请参阅 [Stripe.js文档](https://docs.stripe.com/js/custom_checkout/create_payment_element#custom_checkout_create_payment_element-options) 以查看支持的选项。

您可以通过向 [CheckoutElementsProvider](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider) 传递 [elementsOptions.appearance](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider#react_checkout_provider-options-elementsOptions-appearance)，来[自定义所有 Elements 的外观](https://docs.stripe.com/payments/checkout/customization/appearance.md)。

## Submit the payment [客户端]

#### HTML + JS

渲染 **Pay** 按钮，该按钮通过调用 `Checkout` 实例中的 [confirm](https://docs.stripe.com/js/custom_checkout/confirm) 方法来提交支付。

```html
<button id="pay-button">Pay</button>
<div id="confirm-errors"></div>
```

```js
const checkout = stripe.initCheckoutElementsSdk({clientSecret});

checkout.on('change', (session) => {
  document.getElementById('pay-button').disabled = !session.canConfirm;
});

const loadActionsResult = await checkout.loadActions();

if (loadActionsResult.type === 'success') {
  const {actions} = loadActionsResult;
  const button = document.getElementById('pay-button');
  const errors = document.getElementById('confirm-errors');
  button.addEventListener('click', () => {
    // Clear any validation errors
    errors.textContent = '';

    actions.confirm().then((result) => {
      if (result.type === 'error') {
        errors.textContent = result.error.message;
      }
    });
  });
}
```

#### React

渲染**Pay**按钮，调用 [useCheckout](https://docs.stripe.com/js/react_stripe_js/checkout/use_checkout) 中的 [confirm](https://docs.stripe.com/js/custom_checkout/confirm) 方法以提交支付请求。

```jsx
import React from 'react';
import {useCheckout} from '@stripe/react-stripe-js/checkout';

const PayButton = () => {
  const checkoutState = useCheckout();
  const [loading, setLoading] = React.useState(false);
  const [error, setError] = React.useState(null);

  if (checkoutState.type !== "success") {
    return null;
  }

  const handleClick = () => {
    setLoading(true);checkoutState.checkout.confirm().then((result) => {
      if (result.type === 'error') {
        setError(result.error)
      }
      setLoading(false);
    })
  };

  return (
    <div>
      <button disabled={!checkoutState.checkout.canConfirm || loading} onClick={handleClick}>
        Pay
      </button>
      {error && <div>{error.message}</div>}
    </div>
  )
};

export default PayButton;
```

## 测试您的集成

#### Mobile web app testing

To test your integration, choose Cash App Pay as the payment method and tap **Pay**. While testing, this redirects you to a test payment page where you can approve or decline the payment.

In live mode, tapping **Pay** redirects you to the Cash App mobile application—you don’t have the option to approve or decline the payment within Cash App. The payment is automatically approved after the redirect.

#### Desktop web app testing

To test your integration, scan the QR code with a QR code scanning application on your mobile device. While testing, the QR code payload contains a URL that redirects you to a test payment page where you can approve or decline the test payment.

In live mode, scanning the QR code redirects you to the Cash App mobile application—you don’t have the option to approve or decline the payment within Cash App. The payment is automatically approved after you scan the QR code.


# Payment Intents API

> This is a Payment Intents API for when payment-ui is elements and api-integration is paymentintents. View the full page at https://docs.stripe.com/payments/cash-app-pay/accept-a-payment?payment-ui=elements&api-integration=paymentintents.

This guide shows you how to embed a custom Stripe payment form in your website or application using the [Payment Element](https://docs.stripe.com/payments/payment-element.md). The Payment Element allows you to support Cash App Pay and other payment methods automatically. For advanced configurations and customizations, refer to the [Accept a Payment](https://docs.stripe.com/payments/accept-a-payment.md) integration guide.

## 设置 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'
```

## 创建 PaymentIntent [服务器端]

Stripe uses a [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) object to represent your intent to collect payment from a customer, tracking charge attempts and payment state changes throughout the process.

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

Create a PaymentIntent on your server with an amount and currency. You can manage payment methods from the [Dashboard](https://dashboard.stripe.com/settings/payment_methods). Stripe handles the return of eligible payment methods based on factors such as the transaction’s amount, currency, and payment flow. Before creating the Payment Intent, make sure to turn **Cash App Pay** on in the [payment methods settings](https://dashboard.stripe.com/settings/payment_methods) page.

始终在服务器端决定扣款金额，这是一个可信的环境，客户端不行。这样可防止客户自己选择价格。

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]=true"
```

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

If you don’t want to use the Dashboard or want to manually specify payment methods, you can list them using the `payment_method_types` attribute.

在您的服务器上创建一个 PaymentIntent，包含金额、货币以及支付方式列表。始终在服务器端决定扣款金额，这是一个可信的环境，客户端不行。这样可防止客户自己选择价格。

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=usd \
  -d "payment_method_types[]=cashapp"
```

### 检索客户端私钥

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))，用于在客户端安全地完成支付流程。有不同的方法可以将客户端私钥传递到客户端。

#### 单页应用

使用浏览器的 `fetch` 功能，从您的服务器上的端点获取客户端私钥。如果您的客户端是单页应用，特别是用现代的前端框架（例如 React）搭建的情况，则该方法最为合适。创建服务于客户端私钥的服务器端点：

#### Ruby

```ruby
get '/secret' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end
```

然后在客户端用 JavaScript 获取客户端私钥：

```javascript
(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();
```

#### 服务端呈现

从服务器将客户端私钥传递到客户端。如果在将静态内容发送到浏览器之前，您的应用程序会在服务器上生成静态内容，则此种方法最有效。

在您的结账表单中添加 [client_secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret)。在您的服务器代码中，从 PaymentIntent 检索客户端密钥：

#### Ruby

```erb
<form id="payment-form" data-secret="<%= @intent.client_secret %>">
  <div id="payment-element">
    <!-- placeholder for Elements -->
  </div>
  <button id="submit">Submit</button>
</form>
```

```ruby
get '/checkout' do
  @intent = # ... Fetch or create the PaymentIntent
  erb :checkout
end
```

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

用 [Payment Element](https://docs.stripe.com/payments/payment-element.md) 在客户端收集支付信息。Payment Element 是一个预构建的 UI 组件，它简化了多种支付方式的收集支付详情的流程。

Payment Element 中包含一个 iframe，它通过一个 HTTPS 连接安全地将支付信息发送到 Stripe。避免将 Payment Element 放在另一个 iframe 中，因为有些支付方式需要重定向到另一个页面进行付款确认。

如果您选择使用 iframe 并希望支持 Apple Pay 或 Google Pay，则必须将 iframe 的 [allow](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#attr-allowpaymentrequest) 属性设置为`"payment *"`。

结账页面地址必须以 `https://` rather 开头，而非 `http://` for，您的集成才能正常工作。您可以在不使用 HTTPS 的情况下测试集成，但在准备接收真实付款时，请务必[启用 HTTPS](https://docs.stripe.com/security/guide.md#tls)。

#### HTML + JS

### 设置 Stripe.js

Payment Element 自动可以获取，这是 Stripe.js 的功能。在您的结账页面包含 Stripe.js 脚本，方法是将它添加到您的 HTML 文件的 `head` 部分。为保持 PCI 合规，始终从 js.stripe.com 加载 Stripe.js。不要把脚本打包或自行保留副本。

```html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/dahlia/stripe.js"></script>
</head>
```

用下面的 JavaScript 在您的结账页面创建一个 Stripe 实例：

```javascript
// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');
```

### 将 Payment Element 添加到您的支付页面

Payment Element 需要存在于您的支付页面的某个地方。用您的支付表单中的唯一 ID 创建一个空的 DOM 节点（容器）：

```html
<form id="payment-form">
  <div id="payment-element">
    <!-- Elements will create form elements here -->
  </div>
  <button id="submit">Submit</button>
  <div id="error-message">
    <!-- Display error message to your customers here -->
  </div>
</form>
```

加载了之前的表单后，创建一个 Payment Element 实例，并将它放入容器的 DOM 节点。创建 [Elements](https://docs.stripe.com/js/elements_object/create) 实例时，将上一步的 [client secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) 传入 `options`：

认真处理客户端私钥，因为它会完成收款。不要记录它，而是把它嵌入到 URL，或显示给除客户以外的所有人。

```javascript
const options = {
  clientSecret: '{{CLIENT_SECRET}}',
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in checkout form, passing the client secret obtained in a previous stepconst elements = stripe.elements(options);
// Optional: Autofill user's saved payment methods. If the customer's
// email is known when the page is loaded, you can pass the email
// to the linkAuthenticationElement on mount:
//
//   linkAuthenticationElement.mount("#link-authentication-element",  {
//     defaultValues: {
//       email: 'jenny.rosen@example.com',
//     }
//   })

// Create and mount the Payment Element
const paymentElementOptions = { layout: 'accordion'};
const paymentElement = elements.create('payment', paymentElementOptions);
paymentElement.mount('#payment-element');

```

#### React

### 设置 Stripe.js

从 npm 公共注册表安装 [React Stripe.js](https://www.npmjs.com/package/@stripe/react-stripe-js) 和 [Stripe.js 加载器](https://www.npmjs.com/package/@stripe/stripe-js)：

```bash
npm install --save @stripe/react-stripe-js @stripe/stripe-js
```

### 向您的支付页面添加并配置 Elements 提供程序

要使用 Payment Element 组件，请将您的结账页面组件包裹在 [Elements 提供程序](https://docs.stripe.com/sdks/stripejs-react.md#elements-provider)中。用您的公钥调用 `loadStripe`，并将返回的 `Promise` 传递到 `Elements` 提供程序。另外，将来自上一步的 [client secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) 作为 `options` 传递到 `Elements` 提供程序。

```jsx
import React from 'react';
import ReactDOM from 'react-dom';
import {Elements} from '@stripe/react-stripe-js';
import {loadStripe} from '@stripe/stripe-js';

import CheckoutForm from './CheckoutForm';

// Make sure to call `loadStripe` outside of a component’s render to avoid
// recreating the `Stripe` object on every render.
const stripePromise = loadStripe('<<YOUR_PUBLISHABLE_KEY>>');

function App() {
  const options = {
    // passing the client secret obtained in step 3
    clientSecret: '{{CLIENT_SECRET}}',
    // Fully customizable with appearance API.
    appearance: {/*...*/},
  };

  return (
    <Elements stripe={stripePromise} options={options}>
      <CheckoutForm />
    </Elements>
  );
};

ReactDOM.render(<App />, document.getElementById('root'));
```

### 添加 Payment Element 组件

用 `PaymentElement` 组件构建您的表单。

```jsx
import React from 'react';
import {PaymentElement} from '@stripe/react-stripe-js';

const CheckoutForm = () => {
  return (
    <form>
      // Optional: Autofill user's saved payment methods. If the customer's
      // email is known when the page is loaded, you can pass the email
      // to the linkAuthenticationElement
      //
      // <LinkAuthenticationElement id="link-authentication-element"
        // Prefill the email field like so:
        // options={{defaultValues: {email: 'foo@bar.com'}}}
      // /><PaymentElement />
      <button>Submit</button>
    </form>
  );
};

export default CheckoutForm;
```

## 向 Stripe 提交付款 [客户端]

使用 [stripe.confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment)，用来自 Payment Element 的详情完成付款。为该函数提供一个 [return_url](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-return_url)，告诉 Stripe 在用户完成付款后将他们重定向到哪里。您的用户可能会先被重定向到一个中间站点，如银行授权页面，然后才被重定向到 `return_url`。付款成功时，银行卡付款将立即重定向到 `return_url`。

#### HTML + JS

```javascript
const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();
const {error} = await stripe.confirmPayment({
    //`Elements` instance that was used to create the Payment Element
    elements,
    confirmParams: {
      return_url: 'https://example.com/order/123/complete',
    },
  });

  if (error) {
    // This point will only be reached if there is an immediate error when
    // confirming the payment. Show error to your customer (for example, payment
    // details incomplete)
    const messageContainer = document.querySelector('#error-message');
    messageContainer.textContent = error.message;
  } else {
    // Your customer will be redirected to your `return_url`. For some payment
    // methods like iDEAL, your customer will be redirected to an intermediate
    // site first to authorize the payment, then redirected to the `return_url`.
  }
});
```

#### React

从您的支付表单组件调用 [stripe.confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment) 时，使用 [useStripe](https://docs.stripe.com/sdks/stripejs-react.md#usestripe-hook) 和 [useElements](https://docs.stripe.com/sdks/stripejs-react.md#useelements-hook) 钩子。

如果您不想用 hooks，而是想使用传统的类组件 (Class Components)，则可以使用 [ElementsConsumer](https://docs.stripe.com/sdks/stripejs-react.md#elements-consumer)。

```jsx
import React, {useState} from 'react';
import {useStripe, useElements, PaymentElement} from '@stripe/react-stripe-js';

const CheckoutForm = () => {
  const stripe = useStripe();
  const elements = useElements();

  const [errorMessage, setErrorMessage] = useState(null);

  const handleSubmit = async (event) => {
    // We don't want to let default form submission happen here,
    // which would refresh the page.
    event.preventDefault();

    if (!stripe || !elements) {
      // Stripe.js hasn't yet loaded.
      // Make sure to disable form submission until Stripe.js has loaded.
      return;
    }
const {error} = await stripe.confirmPayment({
      //`Elements` instance that was used to create the Payment Element
      elements,
      confirmParams: {
        return_url: 'https://example.com/order/123/complete',
      },
    });


    if (error) {
      // This point will only be reached if there is an immediate error when
      // confirming the payment. Show error to your customer (for example, payment
      // details incomplete)
      setErrorMessage(error.message);
    } else {
      // Your customer will be redirected to your `return_url`. For some payment
      // methods like iDEAL, your customer will be redirected to an intermediate
      // site first to authorize the payment, then redirected to the `return_url`.
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <PaymentElement />
      <button disabled={!stripe}>Submit</button>
      {/* Show error message to your customers */}
      {errorMessage && <div>{errorMessage}</div>}
    </form>
  );
};

export default CheckoutForm;
```

确保 `return_url` 对应于您网站上显示付款状态的一个页面。Stripe 将客户重定向到 `return_url` 时，我们会提供以下 URL 查询参数。

| 参数                             | 描述                                                                                                                              |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `payment_intent`               | `PaymentIntent` 的唯一标识符。                                                                                                         |
| `payment_intent_client_secret` | `PaymentIntent` 对象的 [client secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret)。 |

> 如果您有可以用来跟踪客户浏览器会话的工具，则您可能需要将 `stripe.com` 域名添加到推荐人列表。重定向会导致一些工具创建新的会话，从而阻止您跟踪完整的会话。

用以下某个查询参数检索 PaymentIntent。检查 [PaymentIntent 的状态](https://docs.stripe.com/payments/paymentintents/lifecycle.md)，以决定向客户显示的内容。您还可以在提供 `return_url` 时附加自己的查询参数，它们会在重定向过程中持续存在。

#### HTML + JS

```javascript

// Initialize Stripe.js using your publishable key
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');

// Retrieve the "payment_intent_client_secret" query parameter appended to
// your return_url by Stripe.js
const clientSecret = new URLSearchParams(window.location.search).get(
  'payment_intent_client_secret'
);

// Retrieve the PaymentIntent
stripe.retrievePaymentIntent(clientSecret).then(({paymentIntent}) => {
  const message = document.querySelector('#message')

  // Inspect the PaymentIntent `status` to indicate the status of the payment
  // to your customer.
  //
  // Some payment methods will [immediately succeed or fail][0] upon
  // confirmation, while others will first enter a `processing` state.
  //
  // [0]: https://stripe.com/docs/payments/payment-methods#payment-notification
  switch (paymentIntent.status) {
    case 'succeeded':
      message.innerText = 'Success! Payment received.';
      break;

    case 'processing':
      message.innerText = "Payment processing. We'll update you when payment is received.";
      break;

    case 'requires_payment_method':
      message.innerText = 'Payment failed. Please try another payment method.';
      // Redirect your user back to your payment page to attempt collecting
      // payment again
      break;

    default:
      message.innerText = 'Something went wrong.';
      break;
  }
});
```

#### React

```jsx
import React, {useState, useEffect} from 'react';
import {useStripe} from '@stripe/react-stripe-js';

const PaymentStatus = () => {
  const stripe = useStripe();
  const [message, setMessage] = useState(null);

  useEffect(() => {
    if (!stripe) {
      return;
    }

    // Retrieve the "payment_intent_client_secret" query parameter appended to
    // your return_url by Stripe.js
    const clientSecret = new URLSearchParams(window.location.search).get(
      'payment_intent_client_secret'
    );

    // Retrieve the PaymentIntent
    stripe
      .retrievePaymentIntent(clientSecret)
      .then(({paymentIntent}) => {
        // Inspect the PaymentIntent `status` to indicate the status of the payment
        // to your customer.
        //
        // Some payment methods will [immediately succeed or fail][0] upon
        // confirmation, while others will first enter a `processing` state.
        //
        // [0]: https://stripe.com/docs/payments/payment-methods#payment-notification
        switch (paymentIntent.status) {
          case 'succeeded':
            setMessage('Success! Payment received.');
            break;

          case 'processing':
            setMessage("Payment processing. We'll update you when payment is received.");
            break;

          case 'requires_payment_method':
            // Redirect your user back to your payment page to attempt collecting
            // payment again
            setMessage('Payment failed. Please try another payment method.');
            break;

          default:
            setMessage('Something went wrong.');
            break;
        }
      });
  }, [stripe]);


  return message;
};

export default PaymentStatus;
```

## Redirect and authenticate transactions

Customers can authenticate Cash App Pay transactions with mobile or desktop apps. The client the customer is using determines the authentication method after calling `confirmPayment`.

#### Mobile app authentication

After calling `confirmPayment`, the customers are redirected to Cash App to approve or decline the payment. After the customers authorize the payment, they’re redirected to the Payment Intent’s `return_url`. Stripe adds `payment_intent`, `payment_intent_client_secret`, `redirect_pm_type`, and `redirect_status` as URL query parameters (along with any existing query parameters in the `return_url`).

An authentication session expires after 60 minutes, and the PaymentIntent’s status transitions back to `require_payment_method`. After the status transitions, the customer sees a payment error and must restart the payment process.

#### Desktop web app authentication

After calling confirmPayment, a QR code displays on the webpage. Your customers can scan the QR code using either their mobile device’s camera or the Cash App mobile app and authenticate the payment using Cash App Pay. A few seconds after customers authenticate the payment successfully, the QR code modal closes automatically and you can fulfill the order. Stripe redirects to the `return_url` when payment is complete. If you don’t want to redirect after payment on web, pass `redirect: if_required` to the Payment Element.

An authentication session expires after 60 minutes. You can refresh the QR code up to 20 times before the PaymentIntent’s status transitions back to `require_payment_method`. After the status transitions, the customer sees a payment error and must restart the payment process.

## Optional: 单独授权和捕获

You can separate authorization and capture to create a charge now, but capture funds later. Stripe cancels the PaymentIntent and sends a [payment_intent.canceled](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.canceled) event if the payment isn’t captured during the 7-day window.

If you know that you can’t capture the payment, we recommend [canceling the PaymentIntent](https://docs.stripe.com/refunds.md#cancel-payment) instead of waiting for the 7-day window to elapse.

### 1. Tell Stripe to authorize only

To indicate that you want separate authorization and capture, set [capture_method](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-capture_method) to `manual` when creating the PaymentIntent. This parameter instructs Stripe to only authorize the amount on the customer’s Cash App Pay account.

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=6000 \
  -d confirm=true \
  -d currency=usd \
  -d "payment_method_types[]=cashapp" \
  -d "payment_method_data[type]=cashapp" \
  -d capture_method=manual \
  --data-urlencode "return_url=https://www.example.com/checkout/done"
```

### 2. Capture the funds

After the authorization succeeds, the PaymentIntent [status](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-status) transitions to `requires_capture`. To capture the authorized funds, make a PaymentIntent [capture](https://docs.stripe.com/api/payment_intents/capture.md) request.

```curl
curl -X POST https://api.stripe.com/v1/payment_intents/{PAYMENT_INTENT_ID}/capture \
  -u "<<YOUR_SECRET_KEY>>:"
```

The total authorized amount is captured by default. You can also specify `amount_to_capture` which can be less or equal to the total.

### (可选) Cancel the authorization

If you need to cancel an authorization, you can [cancel the PaymentIntent](https://docs.stripe.com/api/payment_intents/cancel.md).

## Optional: 处理付款后事件

付款完成时，Stripe 会发送一个 [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) 事件。使用管理平台、自定义 *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 或一个合作伙伴方案来接收这些事件并运行操作，例如，向客户发送订单确认邮件、在数据库中记录订单，或启动配送流程。

侦听这些事件，而不是等待客户端的回调。在客户端上，客户可以在执行回调之前关闭浏览器窗口或退出应用程序，而且恶意客户端可以操纵响应。将集成设置为侦听异步事件还有助于您在未来接受更多支付方式。了解[所有受支持的支付方式之间的差异](https://stripe.com/payments/payment-methods-guide)。

- **在管理平台中手动处理事件**

  [在管理平台中查看测试支付情况](https://dashboard.stripe.com/test/payments)，发送邮件收据，处理提现事宜，或重试失败的付款。

- **创建自定义 Webhook**

  [Build a custom webhook](https://docs.stripe.com/webhooks/handling-payment-events.md#build-your-own-webhook) handler to listen for events and build custom asynchronous payment flows. Test and debug your webhook integration locally with the Stripe CLI.

- **集成一个预构建的 App**

  通过集成合作伙伴的应用程序，处理常见的企业事件，如[自动化](https://stripe.partners/?f_category=automation) 或[市场营销和销售](https://stripe.partners/?f_category=marketing-and-sales)。

## 测试您的集成

#### Mobile web app testing

To test your integration, choose Cash App Pay as the payment method and tap **Pay**. While testing, this redirects you to a test payment page where you can approve or decline the payment.

In live mode, tapping **Pay** redirects you to the Cash App mobile application—you don’t have the option to approve or decline the payment within Cash App. The payment is automatically approved after the redirect.

#### Desktop web app testing

To test your integration, scan the QR code with a QR code scanning application on your mobile device. While testing, the QR code payload contains a URL that redirects you to a test payment page where you can approve or decline the test payment.

In live mode, scanning the QR code redirects you to the Cash App mobile application—you don’t have the option to approve or decline the payment within Cash App. The payment is automatically approved after you scan the QR code.

## Failed payments 

Cash App Pay uses multiple data points to decide when to decline a transaction (for example, their AI model detected high consumer fraud risk for the transaction, or the consumer has revoked your permission to charge them in Cash App).

In these cases, the [PaymentMethod](https://docs.stripe.com/api/payment_methods/object.md) is detached and the [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) object’s status automatically transitions to `requires_payment_method`.

Other than a payment being declined, for a Cash App Pay [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) with a status of `requires_action`, customers must complete the payment within 10 minutes after they’re redirected to Cash App. If no action is taken after 10 minutes, the [PaymentMethod](https://docs.stripe.com/api/payment_methods/object.md) is detached and the [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) object’s status automatically transitions to `requires_payment_method`.

When this happens, the Payment Element renders error messages and instructs your customer to retry using a different payment method.

## Error codes 

The following table details common error codes and recommended actions:

| 错误代码                                                      | 推荐操作                                                                                                                                                                                                                                                                         |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment_intent_invalid_currency`                         | Enter the appropriate currency. Cash App Pay only supports `usd`.                                                                                                                                                                                                            |
| `missing_required_parameter`                              | 查看错误消息以获取有关所需参数的详细信息。                                                                                                                                                                                                                                                        |
| `payment_intent_payment_attempt_failed`                   | This code can appear in the [last_payment_error.code](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-last_payment_error-code) field of a PaymentIntent. Check the error message for a detailed failure reason and suggestion on error handling. |
| `payment_intent_redirect_confirmation_without_return_url` | Provide a `return_url` when confirming a PaymentIntent with Cash App Pay.                                                                                                                                                                                                    |


# 直接收款 API

> This is a 直接收款 API for when payment-ui is direct-api. View the full page at https://docs.stripe.com/payments/cash-app-pay/accept-a-payment?payment-ui=direct-api.

We recommend that you implement the [Elements](https://docs.stripe.com/payments/cash-app-pay/accept-a-payment.md?payment-ui=elements) integration. An Elements integration allows you to add Cash App Pay and other payment methods with significantly less effort than a Direct API integration. Accepting Cash App Pay using a Direct API integration consists of:

- Creating a [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) object to track a payment.
- Submitting the payment to Stripe for processing.
- Authenticating the payment (through a mobile application redirect or QR code).
- Handling post-payment events to redirect the customer after an order succeeds or fails.

## 设置 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'
```

## 创建 PaymentIntent [服务器端]

A [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) is an object that represents your intent to collect payment from a customer and tracks the lifecycle of the payment process through each stage.

To create a `PaymentIntent` on your server:

- Specify the amount to collect and the currency.
- Add `cashapp` to the list of [payment method types](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_types) for your `PaymentIntent`. Make sure Cash App Pay is enabled in the [Dashboard](https://dashboard.stripe.com/settings/payment_methods).

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=6000 \
  -d currency=usd \
  -d "payment_method_types[]=cashapp"
```

### 检索客户端私钥

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))，用于在客户端安全地完成支付流程。有不同的方法可以将客户端私钥传递到客户端。

#### 单页应用

使用浏览器的 `fetch` 功能，从您的服务器上的端点获取客户端私钥。如果您的客户端是单页应用，特别是用现代的前端框架（例如 React）搭建的情况，则该方法最为合适。创建服务于客户端私钥的服务器端点：

#### Ruby

```ruby
get '/secret' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end
```

然后在客户端用 JavaScript 获取客户端私钥：

```javascript
(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();
```

#### 服务端呈现

从服务器将客户端私钥传递到客户端。如果在将静态内容发送到浏览器之前，您的应用程序会在服务器上生成静态内容，则此种方法最有效。

在您的结账表单中添加 [client_secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret)。在您的服务器代码中，从 PaymentIntent 检索客户端密钥：

#### Ruby

```erb
<form id="payment-form" data-secret="<%= @intent.client_secret %>">
  <button id="submit">Submit</button>
</form>
```

```ruby
get '/checkout' do
  @intent = # ... Fetch or create the PaymentIntent
  erb :checkout
end
```

## Submit the payment to Stripe and authenticate transactions client-side

In this step, you’ll complete Cash App Pay payments on the client with [Stripe.js](https://docs.stripe.com/payments/elements.md). To authenticate a transaction, you must redirect the customer to Cash App.

Include the Stripe.js script on your checkout page by adding it to the `head` of your HTML file.

```html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/dahlia/stripe.js"></script>
</head>
```

Create an instance of Stripe.js with the following JavaScript on your checkout page:

```javascript
// Set your publishable key. Remember to change this to your live publishable key in production!
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');
```

Use `stripe.confirmCashappPayment` to confirm the PaymentIntent on the client side.

```javascript
const form = document.getElementById('payment-form');

form.addEventListener('submit', function(event) {
  event.preventDefault();

  // Pass the clientSecret obtained from the server in step 2 as the first argument
  stripe.confirmCashappPayment(
    clientSecret,
    {
      payment_method: {
        type: 'cashapp',
      },
      return_url: 'https://www.example.com/checkout/done',
    },
  );
});
```

> `confirmCashappPayment` only redirects mobile browsers to your `return_url`, it doesn’t redirect desktop browsers. You can manually redirect customers using desktop browsers to your return URL after the returned promise resolves.

Customers can authenticate Cash App Pay transactions with mobile or desktop apps. The client the customer is using determines the authentication method after calling `confirmCashappPayment`.

#### Mobile application authentication

After calling `confirmCashappPayment`, the customers are redirected to Cash App to approve or decline the payment. After the customers authorize the payment, they’re redirected to the Payment Intent’s `return_url`. Stripe adds `payment_intent`, `payment_intent_client_secret`, `redirect_pm_type`, and `redirect_status` as URL query parameters (along with any existing query parameters in the `return_url`).

An authentication session expires after 60 minutes, and the PaymentIntent’s status transitions back to `require_payment_method`. After the status transitions, the customer sees a payment error and must restart the payment process.

#### Desktop web app authentication

After calling `confirmCashappPayment`, a QR code displays on the webpage. Your customers can scan the QR code using either their mobile device’s camera or the Cash App mobile application and authenticate the payment. A few seconds after customers authenticate the payment successfully, the QR code modal closes automatically and you can fulfill the order.

An authentication session expires after 60 minutes. You can refresh the QR code up to 20 times before the PaymentIntent’s status transitions back to `require_payment_method`. After the status transitions, the customer sees a payment error and must restart the payment process.

## Optional: Handle redirect and authentication manually

We recommend using Stripe.js to handle redirects and authentication with `confirmCashappPayment`. However, you can also handle redirects and authentication manually on your server.

Specify `handleActions: false` in the `confirmCashappPayment` call.

```javascript
const form = document.getElementById('payment-form');

form.addEventListener('submit', function(event) {
  event.preventDefault();

  // Set the clientSecret here you got in Step 2
  stripe.confirmCashappPayment(
    clientSecret,
    {
      payment_method_data: {
        type: 'cashapp',
      },
      return_url: 'https://www.example.com/checkout/done',
    },
    {
      handleActions: false
    },
  ).then((result) => {
    if (result.error) {
      // Display error to your customer.
    } else if (result.paymentIntent.status === "requires_action") {
      const nextAction = result.paymentIntent.next_action.cashapp_handle_redirect_or_display_qr_code;
      const expiresAt = nextAction.qr_code.expires_at;
      if (IS_MOBILE) {
        // This URL redirects the customer to Cash App to approve or decline the payment.
        const mobileAuthUrl = nextAction.mobile_auth_url;
      } else if (IS_DESKTOP) {
        // Render the QR code and display it to the customer using the below image source.
        const imageUrlSvg = nextAction.qr_code.image_url_svg;
        const imageUrlPng = nextAction.qr_code.image_url_png;
      }
    }
  });
});
```

#### Mobile application authentication

If a customer is paying with Cash App Pay on a mobile device:

1. Redirect the customer to the URL set as the `result.paymentIntent.next_action.cashapp_handle_redirect_or_display_qr_code.mobile_auth_url` property. This redirects the customer to Cash App to approve or decline the payment.

1. After the customer authorizes the payment, they’re redirected to the Payment Intent’s `return_url`. Stripe adds `payment_intent`, `payment_intent_client_secret`, `redirect_pm_type`, and `redirect_status` as URL query parameters (along with any existing query parameters in the `return_url`).

1. Note that the `mobile_auth_url` expires after 30 seconds. In case the customer isn’t redirected to `mobile_auth_url` before expiration, call [stripe.retrievePaymentIntent](https://docs.stripe.com/js/payment_intents/retrieve_payment_intent) to get a new `mobile_auth_url`.

#### Desktop web app authentication

If a customer is paying with Cash App Pay from a desktop web app:

1. Render the QR code and display it to the customer. Use `result.paymentIntent.next_action.cashapp_handle_redirect_or_display_qr_code.qr_code.image_url_png` or `image_url_svg` as an image source. For example:

   ```html
   <img src="${result.paymentIntent.next_action.cashapp_handle_redirect_or_display_qr_code.qr_code.image_url_png}" />
   ```

1. The customer can scan the QR code using either their mobile device’s camera or the Cash App mobile application. They can then authenticate the payment.

1. Make the customer wait on the QR code page until Stripe fulfills the order and you know the outcome of the payment. Stripe sends the outcome in a [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) or a [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.payment_failed) webhook. You can either consume these payment intent webhooks server-side and return the results to the client (for example, with a persistent connection using web-socket) or implement client-side polling on your webpage to periodically fetch the status of the [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md).

1. The QR code expires after 30 seconds. On expiration, call [stripe.retrievePaymentIntent](https://docs.stripe.com/js/payment_intents/retrieve_payment_intent) to get a new QR code from `result.paymentIntent.next_action.cashapp_handle_redirect_or_display_qr_code.qr_code`.

An authentication session expires after 60 minutes. You can refresh the QR code up to 20 times before the PaymentIntent’s status transitions back to `require_payment_method`. After the status transitions, the customer sees a payment error and must restart the payment process.

## Optional: 单独授权和捕获

You can separate authorization and capture to create a charge now, but capture funds later. Stripe cancels the PaymentIntent and sends a [payment_intent.canceled](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.canceled) event if the payment isn’t captured during the 7-day window.

If you know that you can’t capture the payment, we recommend [canceling the PaymentIntent](https://docs.stripe.com/refunds.md#cancel-payment) instead of waiting for the 7-day window to elapse.

### 1. Tell Stripe to authorize only

To indicate that you want separate authorization and capture, set [capture_method](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-capture_method) to `manual` when creating the PaymentIntent. This parameter instructs Stripe to only authorize the amount on the customer’s Cash App Pay account.

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=6000 \
  -d confirm=true \
  -d currency=usd \
  -d "payment_method_types[]=cashapp" \
  -d "payment_method_data[type]=cashapp" \
  -d capture_method=manual \
  --data-urlencode "return_url=https://www.example.com/checkout/done"
```

### 2. Capture the funds

After the authorization succeeds, the PaymentIntent [status](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-status) transitions to `requires_capture`. To capture the authorized funds, make a PaymentIntent [capture](https://docs.stripe.com/api/payment_intents/capture.md) request.

```curl
curl -X POST https://api.stripe.com/v1/payment_intents/{PAYMENT_INTENT_ID}/capture \
  -u "<<YOUR_SECRET_KEY>>:"
```

The total authorized amount is captured by default. You can also specify `amount_to_capture` which can be less or equal to the total.

### (可选) Cancel the authorization

If you need to cancel an authorization, you can [cancel the PaymentIntent](https://docs.stripe.com/api/payment_intents/cancel.md).

## Optional: 处理付款后事件

付款完成时，Stripe 会发送一个 [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) 事件。使用管理平台、自定义 *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 或一个合作伙伴方案来接收这些事件并运行操作，例如，向客户发送订单确认邮件、在数据库中记录订单，或启动配送流程。

侦听这些事件，而不是等待客户端的回调。在客户端上，客户可以在执行回调之前关闭浏览器窗口或退出应用程序，而且恶意客户端可以操纵响应。将集成设置为侦听异步事件还有助于您在未来接受更多支付方式。了解[所有受支持的支付方式之间的差异](https://stripe.com/payments/payment-methods-guide)。

- **在管理平台中手动处理事件**

  [在管理平台中查看测试支付情况](https://dashboard.stripe.com/test/payments)，发送邮件收据，处理提现事宜，或重试失败的付款。

- **创建自定义 Webhook**

  [Build a custom webhook](https://docs.stripe.com/webhooks/handling-payment-events.md#build-your-own-webhook) handler to listen for events and build custom asynchronous payment flows. Test and debug your webhook integration locally with the Stripe CLI.

- **集成一个预构建的 App**

  通过集成合作伙伴的应用程序，处理常见的企业事件，如[自动化](https://stripe.partners/?f_category=automation) 或[市场营销和销售](https://stripe.partners/?f_category=marketing-and-sales)。

## 测试您的集成

#### Mobile web app testing

To test your integration, choose Cash App Pay as the payment method and tap **Pay**. While testing, this redirects you to a test payment page where you can approve or decline the payment.

In live mode, tapping **Pay** redirects you to the Cash App mobile application—you don’t have the option to approve or decline the payment within Cash App. The payment is automatically approved after the redirect.

#### Desktop web app testing

To test your integration, scan the QR code with a QR code scanning application on your mobile device. While testing, the QR code payload contains a URL that redirects you to a test payment page where you can approve or decline the test payment.

In live mode, scanning the QR code redirects you to the Cash App mobile application—you don’t have the option to approve or decline the payment within Cash App. The payment is automatically approved after you scan the QR code.

## Failed payments 

Cash App Pay uses multiple data points to decide when to decline a transaction (for example, their AI model detected high consumer fraud risk for the transaction, or the consumer has revoked your permission to charge them in Cash App).

In these cases, the [PaymentMethod](https://docs.stripe.com/api/payment_methods/object.md) is detached and the [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) object’s status automatically transitions to `requires_payment_method`.

Other than a payment being declined, for a Cash App Pay [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) with a status of `requires_action`, customers must complete the payment within 10 minutes after they’re redirected to Cash App. If no action is taken after 10 minutes, the [PaymentMethod](https://docs.stripe.com/api/payment_methods/object.md) is detached and the [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) object’s status automatically transitions to `requires_payment_method`.

When this happens, the Payment Element renders error messages and instructs your customer to retry using a different payment method.

## Error codes 

The following table details common error codes and recommended actions:

| 错误代码                                                      | 推荐操作                                                                                                                                                                                                                                                                         |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment_intent_invalid_currency`                         | Enter the appropriate currency. Cash App Pay only supports `usd`.                                                                                                                                                                                                            |
| `missing_required_parameter`                              | 查看错误消息以获取有关所需参数的详细信息。                                                                                                                                                                                                                                                        |
| `payment_intent_payment_attempt_failed`                   | This code can appear in the [last_payment_error.code](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-last_payment_error-code) field of a PaymentIntent. Check the error message for a detailed failure reason and suggestion on error handling. |
| `payment_intent_redirect_confirmation_without_return_url` | Provide a `return_url` when confirming a PaymentIntent with Cash App Pay.                                                                                                                                                                                                    |


# iOS

> This is a iOS for when payment-ui is mobile and platform is ios. View the full page at https://docs.stripe.com/payments/cash-app-pay/accept-a-payment?payment-ui=mobile&platform=ios.

We recommend you use the [Mobile Payment Element](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=ios), an embeddable payment form, to add Cash App Pay and other payment methods to your integration with the least amount of effort.

This guide covers how to accept Cash App Pay from your native mobile application using your own custom payment form.

If you’re accepting Cash App Pay from your native mobile application, your customers are redirected to the Cash App mobile application for authentication. The purchase is completed in the Cash App mobile application, and the customer is redirected back to your native mobile application.

## 设置 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'
```

### 客户端

[Stripe iOS SDK](https://github.com/stripe/stripe-ios) 是开源的，[有完整的文档](https://stripe.dev/stripe-ios/index.html)，并且与支持 iOS 13 或更高版本操作系统的应用程序兼容。

#### Swift Package Manager

要安装 SDK，按这些步骤进行：

1. 在 Xcode 中，选择**文件** > **添加工具包依赖…**并输入 `https://github.com/stripe/stripe-ios-spm` 作为仓库 URL。
1. 从我们的[发布页面](https://github.com/stripe/stripe-ios/releases)选择最新的版本号。
1. 将 **StripePaymentsUI** 产品添加到[您的目标应用程序](https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app)。

#### CocoaPods

1. 如果您还没有[CocoaPods](https://guides.cocoapods.org/using/getting-started.html)，请安装其最新版本。
1. 如果您目前没有 [Podfile](https://guides.cocoapods.org/syntax/podfile.html)，请运行以下命令创建一个：
   ```bash
   pod init
   ```
1. 将这一行代码添加到您的 `Podfile`：
   ```podfile
   pod 'StripePaymentsUI'
   ```
1. 运行以下命令：
   ```bash
   pod install
   ```
1. 今后，一定记得用 `.xcworkspace` 文件来打开您在 Xcode 中的项目，不要使用 `.xcodeproj` 文件。
1. 将来，要更新到 SDK 的最新版本，运行：
   ```bash
   pod update StripePaymentsUI
   ```

#### Carthage

1. 如果您还没有[Carthage](https://github.com/Carthage/Carthage#installing-carthage)，请安装其最新版本。
1. 将这一行代码添加到您的 `Cartfile`。
   ```cartfile
   github "stripe/stripe-ios"
   ```
1. 按照 [Carthage 安装说明](https://github.com/Carthage/Carthage#if-youre-building-for-ios-tvos-or-watchos)进行。确保嵌入[这里](https://github.com/stripe/stripe-ios/tree/master/StripePaymentsUI/README.md#manual-linking)所列的所有必要框架。
1. 将来，要更新到 SDK 的最新版本，运行以下命令即可：
   ```bash
   carthage update stripe-ios --platform ios
   ```

#### 手动框架

1. 前往我们的 [GitHub 发布页面](https://github.com/stripe/stripe-ios/releases/latest)，下载并解压缩 **Stripe.xcframework.zip**。
1. 将 **StripePaymentsUI.xcframework** 拖拽到您的 Xcode 项目中 **General**（常规）设置的 **Embedded Binaries**（嵌入式二进制文件）部分。一定要选择 **Copy items if needed**（需要时复制项目）。
1. 为[这里](https://github.com/stripe/stripe-ios/tree/master/StripePaymentsUI/README.md#manual-linking)所列的所有必要框架重复第 2 步。
1. 将来，要更新到 SDK 的最新版本，重复第 1-3 步。

> 有关最新 SDK 发布及过往版本的详细信息，请查看 GitHub 上的[发布](https://github.com/stripe/stripe-ios/releases)页面。要想在新版本发布时接收通知，请[查看仓库的发布](https://help.github.com/en/articles/watching-and-unwatching-releases-for-a-repository#watching-releases-for-a-repository)。

在应用程序启动时使用您的 Stripe [公钥](https://dashboard.stripe.com/test/apikeys) 配置 SDK。这样可使您的应用程序向 Stripe API 发出请求。

#### Swift

```swift
import UIKitimportStripePaymentsUI

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {StripeAPI.defaultPublishableKey = "<<YOUR_PUBLISHABLE_KEY>>"
        // do any other necessary launch configuration
        return true
    }
}
```

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

## 创建 PaymentIntent [服务器端] [客户端]

### 服务器端

A [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) is an object that represents your intent to collect payment from a customer and tracks the lifecycle of the payment process through each stage.

To create and confirm a `PaymentIntent` on your server:

- Specify the amount to collect and the currency.
- Add `cashapp` to the list of [payment method types](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_types) for your `PaymentIntent`. Make sure Cash App Pay is enabled in the [Dashboard](https://dashboard.stripe.com/settings/payment_methods).
- Set `payment_method_data[type]` to `cashapp` to create a *PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) and immediately use it with this PaymentIntent.

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=6000 \
  -d currency=usd \
  -d "payment_method_types[]=cashapp" \
  -d "payment_method_data[type]=cashapp" \
  --data-urlencode "return_url=payments-example://stripe-redirect"
```

The returned PaymentIntent includes a *client secret* (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)), that you’ll use to *confirm* (Confirming an intent indicates that the customer intends to use the current or provided payment method. Upon confirmation, the intent attempts to initiate the portions of the flow that have real-world side effects) the PaymentIntent. Send the client secret back to the client so you can use it in the next step.

### 客户端

在客户端，从您的服务器请求一个 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))：

#### Swift

```swift
class CheckoutViewController: UIViewController {
    var paymentIntentClientSecret: String?

    // ...continued from previous step

    override func viewDidLoad() {
        // ...continued from previous step
        startCheckout()
    }

    func startCheckout() {
        // Request a PaymentIntent from your server and store its client secret
        // Click View full sample to see a complete implementation
    }
}
```

## 向 Stripe 提交付款 [客户端]

When a customer taps to pay with Cash App Pay, confirm the `PaymentIntent` to complete the payment. Configure an `STPPaymentIntentParams` object with the `PaymentIntent` [client secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret).

The client secret is different from your API keys that authenticate Stripe API requests. Handle it carefully, as it can complete the charge. Don’t log it, embed it in URLs, or expose it to anyone but the customer.

### 设置返回页面

The iOS SDK presents a webview in your app to complete the Cash App Pay payment. When authentication is finished, the webview can automatically dismiss itself instead of having your customer close it. To enable this behavior, configure a custom URL scheme or universal link and set up your app delegate to forward the URL to the SDK.

#### Swift

```swift
// This method handles opening custom URL schemes (for example, "your-app://stripe-redirect")
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    let stripeHandled = StripeAPI.handleURLCallback(with: url)
    if (stripeHandled) {
        return true
    } else {
        // This was not a Stripe url – handle the URL normally as you would
    }
    return false
}

// This method handles opening universal link URLs (for example, "https://example.com/stripe_ios_callback")
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    if userActivity.activityType == NSUserActivityTypeBrowsingWeb {
        if let url = userActivity.webpageURL {
            let stripeHandled = StripeAPI.handleURLCallback(with: url)
            if (stripeHandled) {
                return true
            } else {
                // This was not a Stripe url – handle the URL normally as you would
            }
        }
    }
    return false
}
```

Pass the URL as the `return_url` when you confirm the PaymentIntent. After webview-based authentication finishes, Stripe redirects the user to the `return_url`.

### Confirm Cash App Pay payment

Complete the payment by calling `STPPaymentHandler confirmPayment`. This presents a webview where the customer can complete the payment with Cash App Pay. Upon completion, the completion block is called with the result of the payment.

#### Swift

```swift
let paymentIntentParams = STPPaymentIntentParams(clientSecret: paymentIntentClientSecret)

// Cash App Pay doesn't require additional parameters so we only need to pass the initialized
// STPPaymentMethodCashAppParams instance to STPPaymentMethodParams
let cashApp = STPPaymentMethodCashAppParams()
let paymentMethodParams = STPPaymentMethodParams(cashApp: cashApp, billingDetails: nil, metadata: nil)

paymentIntentParams.paymentMethodParams = paymentMethodParams
paymentIntentParams.returnURL = "payments-example://stripe-redirect"

STPPaymentHandler.shared().confirmPayment(paymentIntentParams,
                                          with: self)
{ (handlerStatus, paymentIntent, error) in
    switch handlerStatus {
    case .succeeded:
        // Payment succeeded
        // ...

    case .canceled:
        // Payment canceled
        // ...

    case .failed:
        // Payment failed
        // ...

    @unknown default:
        fatalError()
    }
}
```

## Optional: 单独授权和捕获

You can separate authorization and capture to create a charge now, but capture funds later. Stripe cancels the PaymentIntent and sends a [payment_intent.canceled](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.canceled) event if the payment isn’t captured during the 7-day window.

If you know that you can’t capture the payment, we recommend [canceling the PaymentIntent](https://docs.stripe.com/refunds.md#cancel-payment) instead of waiting for the 7-day window to elapse.

### 1. Tell Stripe to authorize only

To indicate that you want separate authorization and capture, set [capture_method](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-capture_method) to `manual` when creating the PaymentIntent. This parameter instructs Stripe to only authorize the amount on the customer’s Cash App Pay account.

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=6000 \
  -d confirm=true \
  -d currency=usd \
  -d "payment_method_types[]=cashapp" \
  -d "payment_method_data[type]=cashapp" \
  -d capture_method=manual \
  --data-urlencode "return_url=https://www.example.com/checkout/done"
```

### 2. Capture the funds

After the authorization succeeds, the PaymentIntent [status](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-status) transitions to `requires_capture`. To capture the authorized funds, make a PaymentIntent [capture](https://docs.stripe.com/api/payment_intents/capture.md) request.

```curl
curl -X POST https://api.stripe.com/v1/payment_intents/{PAYMENT_INTENT_ID}/capture \
  -u "<<YOUR_SECRET_KEY>>:"
```

The total authorized amount is captured by default. You can also specify `amount_to_capture` which can be less or equal to the total.

### (可选) Cancel the authorization

If you need to cancel an authorization, you can [cancel the PaymentIntent](https://docs.stripe.com/api/payment_intents/cancel.md).

## Optional: 处理付款后事件

付款完成时，Stripe 会发送一个 [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) 事件。使用管理平台、自定义 *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 或一个合作伙伴方案来接收这些事件并运行操作，例如，向客户发送订单确认邮件、在数据库中记录订单，或启动配送流程。

侦听这些事件，而不是等待客户端的回调。在客户端上，客户可以在执行回调之前关闭浏览器窗口或退出应用程序，而且恶意客户端可以操纵响应。将集成设置为侦听异步事件还有助于您在未来接受更多支付方式。了解[所有受支持的支付方式之间的差异](https://stripe.com/payments/payment-methods-guide)。

- **在管理平台中手动处理事件**

  [在管理平台中查看测试支付情况](https://dashboard.stripe.com/test/payments)，发送邮件收据，处理提现事宜，或重试失败的付款。

- **创建自定义 Webhook**

  [Build a custom webhook](https://docs.stripe.com/webhooks/handling-payment-events.md#build-your-own-webhook) handler to listen for events and build custom asynchronous payment flows. Test and debug your webhook integration locally with the Stripe CLI.

- **集成一个预构建的 App**

  通过集成合作伙伴的应用程序，处理常见的企业事件，如[自动化](https://stripe.partners/?f_category=automation) 或[市场营销和销售](https://stripe.partners/?f_category=marketing-and-sales)。

## 测试您的集成

Test your Cash App Pay integration with your test API keys by viewing the redirect page. You can test the successful payment case by authenticating the payment on the redirect page. The [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) transitions from `requires_action` to `succeeded`.

To test the case where the user fails to authenticate, use your test API keys and view the redirect page. On the redirect page, click **Fail test payment**. The [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) transitions from `requires_action` to `requires_payment_method`.

For test manual capture PaymentIntents, the uncaptured [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) auto-expires 7 days after successful authorization.

In live mode, tapping **Pay** redirects you to the Cash App mobile application—you don’t have the option to approve or decline the payment within Cash App. The payment is automatically approved after the redirect.

## Failed payments 

Cash App Pay uses multiple data points to decide when to decline a transaction (for example, their AI model detected high consumer fraud risk for the transaction, or the consumer has revoked your permission to charge them in Cash App).

In these cases, the [PaymentMethod](https://docs.stripe.com/api/payment_methods/object.md) is detached and the [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) object’s status automatically transitions to `requires_payment_method`.

Other than a payment being declined, for a Cash App Pay [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) with a status of `requires_action`, customers must complete the payment within 10 minutes after they’re redirected to Cash App. If no action is taken after 10 minutes, the [PaymentMethod](https://docs.stripe.com/api/payment_methods/object.md) is detached and the [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) object’s status automatically transitions to `requires_payment_method`.

When this happens, the Payment Element renders error messages and instructs your customer to retry using a different payment method.

## Error codes 

The following table details common error codes and recommended actions:

| 错误代码                                                      | 推荐操作                                                                                                                                                                                                                                                                         |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment_intent_invalid_currency`                         | Enter the appropriate currency. Cash App Pay only supports `usd`.                                                                                                                                                                                                            |
| `missing_required_parameter`                              | 查看错误消息以获取有关所需参数的详细信息。                                                                                                                                                                                                                                                        |
| `payment_intent_payment_attempt_failed`                   | This code can appear in the [last_payment_error.code](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-last_payment_error-code) field of a PaymentIntent. Check the error message for a detailed failure reason and suggestion on error handling. |
| `payment_intent_redirect_confirmation_without_return_url` | Provide a `return_url` when confirming a PaymentIntent with Cash App Pay.                                                                                                                                                                                                    |


# Android

> This is a Android for when payment-ui is mobile and platform is android. View the full page at https://docs.stripe.com/payments/cash-app-pay/accept-a-payment?payment-ui=mobile&platform=android.

We recommend you use the [Mobile Payment Element](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=android), an embeddable payment form, to add Cash App Pay and other payment methods to your integration with the least amount of effort.

This guide covers how to accept Cash App Pay from your native mobile application using your own custom payment form.

If you’re accepting Cash App Pay from your native mobile application, your customers are redirected to the Cash App mobile application for authentication. The purchase is completed in the Cash App mobile application, and the customer is redirected back to your native mobile application.

## 设置 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'
```

### 客户端

[Stripe Android SDK](https://github.com/stripe/stripe-android) 是开源的，且[有完整的文档](https://stripe.dev/stripe-android/)。

安装 SDK 时，将 `stripe-android` 添加到您的 [app/build.gradle](https://developer.android.com/studio/build/dependencies) 文件的 `dependencies` 块中：

#### Kotlin

```kotlin
plugins {
    id("com.android.application")
}

android { ... }

dependencies {
  // ...

  // Stripe Android SDK
  implementation("com.stripe:stripe-android:23.2.0")
  // Include the financial connections SDK to support US bank account as a payment method
  implementation("com.stripe:financial-connections:23.2.0")
}
```

> 有关最新 SDK 发布及过往版本的详细信息，请查看 GitHub 上的[发布](https://github.com/stripe/stripe-android/releases)页面。要想在新版本发布时接收通知，请[查看仓库的发布情况](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository)。

用您的 Stripe [公钥](https://dashboard.stripe.com/apikeys)配置 SDK，以便它可以向 Stripe API 发送请求，例如在您的 `Application` 子类中：

#### Kotlin

```kotlin
import com.stripe.android.PaymentConfiguration

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        PaymentConfiguration.init(
            applicationContext,
            "<<YOUR_PUBLISHABLE_KEY>>"
        )
    }
}
```

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

Stripe 的示例还用 [OkHttp](https://github.com/square/okhttp) 和 [GSON](https://github.com/google/gson) 向服务器发送了 HTTP 请求。

## 创建 PaymentIntent [服务器端] [客户端]

### 服务器端

A [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) is an object that represents your intent to collect payment from a customer and tracks the lifecycle of the payment process through each stage.

To create and confirm a `PaymentIntent` on your server:

- Specify the amount to collect and the currency.
- Add `cashapp` to the list of [payment method types](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_types) for your `PaymentIntent`. Make sure Cash App Pay is enabled in the [Dashboard](https://dashboard.stripe.com/settings/payment_methods).
- Set `payment_method_data[type]` to `cashapp` to create a *PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) and immediately use it with this PaymentIntent.

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=6000 \
  -d currency=usd \
  -d "payment_method_types[]=cashapp" \
  -d "payment_method_data[type]=cashapp" \
  --data-urlencode "return_url=payments-example://stripe-redirect"
```

The returned PaymentIntent includes a *client secret* (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)), that you’ll use to *confirm* (Confirming an intent indicates that the customer intends to use the current or provided payment method. Upon confirmation, the intent attempts to initiate the portions of the flow that have real-world side effects) the PaymentIntent. Send the client secret back to the client so you can use it in the next step.

### 客户端

在客户端，从您的服务器请求一个 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))：

#### Kotlin

```kotlin
class CheckoutActivity : AppCompatActivity() {

  private lateinit var paymentIntentClientSecret: String

  override fun onCreate(savedInstanceState: Bundle?) {
      super.onCreate(savedInstanceState)
      // ...
      startCheckout()
  }

  private fun startCheckout() {
      // Request a PaymentIntent from your server and store its client secret in paymentIntentClientSecret
      // Click View full sample to see a complete implementation
  }
}
```

## 向 Stripe 提交付款 [客户端]

When a customer taps to pay with Cash App Pay, confirm the `PaymentIntent` to complete the payment. Configure a `ConfirmPaymentIntentParams` object with the `PaymentIntent` [client secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret).

The client secret is different from your API keys that authenticate Stripe API requests. Handle it carefully, as it can complete the charge. Don’t log it, embed it in URLs, or expose it to anyone but the customer.

### Confirm Cash App Pay payment

Complete the payment by calling [PaymentLauncher confirm](https://stripe.dev/stripe-android/payments-core/com.stripe.android.payments.paymentlauncher/-payment-launcher/confirm.html). This presents a webview where the customer can complete the payment with Cash App Pay. Upon completion, the provided `PaymentResultCallback` is called with the result of the payment.

#### Kotlin

```kotlin
class CheckoutActivity : AppCompatActivity() {

    // ...

    private val paymentLauncher: PaymentLauncher by lazy {
        val paymentConfiguration = PaymentConfiguration.getInstance(applicationContext)
        PaymentLauncher.create(
            activity = this,
            publishableKey = paymentConfiguration.publishableKey,
            stripeAccountId = paymentConfiguration.stripeAccountId,
            callback = ::onPaymentResult,
        )
    }

    // …

    private fun startCheckout() {
        // ...

        val cashAppPayParams = PaymentMethodCreateParams.createCashAppPay()

        val confirmParams = ConfirmPaymentIntentParams
            .createWithPaymentMethodCreateParams(
                paymentMethodCreateParams = cashAppPayParams,
                clientSecret = paymentIntentClientSecret,
                // Add a mandate ID or MandateDataParams if you
                // want to set this up for future use…
            )

        paymentLauncher.confirm(confirmParams)
    }

    private fun onPaymentResult(paymentResult: PaymentResult) {
        // Handle the payment result…
    }
}
```

## Optional: 单独授权和捕获

You can separate authorization and capture to create a charge now, but capture funds later. Stripe cancels the PaymentIntent and sends a [payment_intent.canceled](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.canceled) event if the payment isn’t captured during the 7-day window.

If you know that you can’t capture the payment, we recommend [canceling the PaymentIntent](https://docs.stripe.com/refunds.md#cancel-payment) instead of waiting for the 7-day window to elapse.

### 1. Tell Stripe to authorize only

To indicate that you want separate authorization and capture, set [capture_method](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-capture_method) to `manual` when creating the PaymentIntent. This parameter instructs Stripe to only authorize the amount on the customer’s Cash App Pay account.

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=6000 \
  -d confirm=true \
  -d currency=usd \
  -d "payment_method_types[]=cashapp" \
  -d "payment_method_data[type]=cashapp" \
  -d capture_method=manual \
  --data-urlencode "return_url=https://www.example.com/checkout/done"
```

### 2. Capture the funds

After the authorization succeeds, the PaymentIntent [status](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-status) transitions to `requires_capture`. To capture the authorized funds, make a PaymentIntent [capture](https://docs.stripe.com/api/payment_intents/capture.md) request.

```curl
curl -X POST https://api.stripe.com/v1/payment_intents/{PAYMENT_INTENT_ID}/capture \
  -u "<<YOUR_SECRET_KEY>>:"
```

The total authorized amount is captured by default. You can also specify `amount_to_capture` which can be less or equal to the total.

### (可选) Cancel the authorization

If you need to cancel an authorization, you can [cancel the PaymentIntent](https://docs.stripe.com/api/payment_intents/cancel.md).

## Optional: 处理付款后事件

付款完成时，Stripe 会发送一个 [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) 事件。使用管理平台、自定义 *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 或一个合作伙伴方案来接收这些事件并运行操作，例如，向客户发送订单确认邮件、在数据库中记录订单，或启动配送流程。

侦听这些事件，而不是等待客户端的回调。在客户端上，客户可以在执行回调之前关闭浏览器窗口或退出应用程序，而且恶意客户端可以操纵响应。将集成设置为侦听异步事件还有助于您在未来接受更多支付方式。了解[所有受支持的支付方式之间的差异](https://stripe.com/payments/payment-methods-guide)。

- **在管理平台中手动处理事件**

  [在管理平台中查看测试支付情况](https://dashboard.stripe.com/test/payments)，发送邮件收据，处理提现事宜，或重试失败的付款。

- **创建自定义 Webhook**

  [Build a custom webhook](https://docs.stripe.com/webhooks/handling-payment-events.md#build-your-own-webhook) handler to listen for events and build custom asynchronous payment flows. Test and debug your webhook integration locally with the Stripe CLI.

- **集成一个预构建的 App**

  通过集成合作伙伴的应用程序，处理常见的企业事件，如[自动化](https://stripe.partners/?f_category=automation) 或[市场营销和销售](https://stripe.partners/?f_category=marketing-and-sales)。

## 测试您的集成

Test your Cash App Pay integration with your test API keys by viewing the redirect page. You can test the successful payment case by authenticating the payment on the redirect page. The [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) transitions from `requires_action` to `succeeded`.

To test the case where the user fails to authenticate, use your test API keys and view the redirect page. On the redirect page, click **Fail test payment**. The [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) transitions from `requires_action` to `requires_payment_method`.

For test manual capture PaymentIntents, the uncaptured [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) auto-expires 7 days after successful authorization.

There are some differences between how *sandbox* (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) and live mode payments work. For example, in live mode, tapping **Pay** redirects you to the Cash App mobile application. Within Cash App, you don’t have the option to approve or decline the payment within Cash App. The payment is automatically approved after the redirect.

## Failed payments 

Cash App Pay uses multiple data points to decide when to decline a transaction (for example, their AI model detected high consumer fraud risk for the transaction, or the consumer has revoked your permission to charge them in Cash App).

In these cases, the [PaymentMethod](https://docs.stripe.com/api/payment_methods/object.md) is detached and the [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) object’s status automatically transitions to `requires_payment_method`.

Other than a payment being declined, for a Cash App Pay [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) with a status of `requires_action`, customers must complete the payment within 10 minutes after they’re redirected to Cash App. If no action is taken after 10 minutes, the [PaymentMethod](https://docs.stripe.com/api/payment_methods/object.md) is detached and the [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) object’s status automatically transitions to `requires_payment_method`.

When this happens, the Payment Element renders error messages and instructs your customer to retry using a different payment method.

## Error codes 

The following table details common error codes and recommended actions:

| 错误代码                                                      | 推荐操作                                                                                                                                                                                                                                                                         |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment_intent_invalid_currency`                         | Enter the appropriate currency. Cash App Pay only supports `usd`.                                                                                                                                                                                                            |
| `missing_required_parameter`                              | 查看错误消息以获取有关所需参数的详细信息。                                                                                                                                                                                                                                                        |
| `payment_intent_payment_attempt_failed`                   | This code can appear in the [last_payment_error.code](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-last_payment_error-code) field of a PaymentIntent. Check the error message for a detailed failure reason and suggestion on error handling. |
| `payment_intent_redirect_confirmation_without_return_url` | Provide a `return_url` when confirming a PaymentIntent with Cash App Pay.                                                                                                                                                                                                    |


# React Native

> This is a React Native for when payment-ui is mobile and platform is react-native. View the full page at https://docs.stripe.com/payments/cash-app-pay/accept-a-payment?payment-ui=mobile&platform=react-native.

Cash App Pay is a payment method available to all Cash App customers for single use and recurring payments to businesses. Cash App Pay uses the customer’s stored balance or linked debit card to fund the payment. The customer can confirm the payment in one of two ways:

- During checkout from a mobile device, your site redirects customers to the Cash App mobile application for authentication. The payment is authenticated during the redirect. No additional action is needed in the Cash App mobile application to complete the purchase. The customer is then redirected back to your site.
- During checkout from a desktop web application, the customer scans a QR code with their mobile device to authenticate the transaction.

Customers can also authorize the use of Cash App Pay for future, on-file payments.

## 设置 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)密钥。

## 创建 PaymentIntent [服务器端] [客户端]

### 服务器端

A [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) is an object that represents your intent to collect payment from a customer and tracks the lifecycle of the payment process through each stage.

To create and confirm a `PaymentIntent` on your server:

- Specify the amount to collect and the currency.
- Add `cashapp` to the list of [payment method types](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_types) for your `PaymentIntent`. Make sure Cash App Pay is enabled in the [Dashboard](https://dashboard.stripe.com/settings/payment_methods).

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=6000 \
  -d currency=usd \
  -d "payment_method_types[]=cashapp" \
  --data-urlencode "return_url=payments-example://stripe-redirect"
```

The returned PaymentIntent includes a *client secret* (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)), that you’ll use to *confirm* (Confirming an intent indicates that the customer intends to use the current or provided payment method. Upon confirmation, the intent attempts to initiate the portions of the flow that have real-world side effects) the PaymentIntent. Send the client secret back to the client so you can use it in the next step.

### 客户端

在客户端，从您的服务器请求一个 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))：

```javascript
function PaymentScreen() {
  const fetchPaymentIntentClientSecret = async () => {
    const response = await fetch(`${API_URL}/create-payment-intent`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        currency: 'usd',
      }),
    });
    const {clientSecret} = await response.json();

    return clientSecret;
  };

  const handlePayPress = async () => {
    // See below
  };

  return (
    <View>
      <Button onPress={handlePayPress} title="Pay" />
    </View>
  );
}
```

The client secret is different from your API keys that authenticate Stripe API requests. Handle it carefully because it can complete the charge. Don’t log it, embed it in URLs, or expose it to anyone but the customer.

## 设置返回页面（仅限 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。不支持通用链接。
1. [配置](https://reactnative.dev/docs/linking) 您的自定义 URL。
1. 设置您的根组件，将 URL 转发到 Stripe SDK，如下所示。

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

```jsx
import { useEffect, useCallback } from 'react';
import { Linking } 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>
  );
}
```

有关 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) 文档。

## Confirm Cash App Pay payment [客户端]

When a customer taps to pay with CashApp, complete the payment by calling [confirmPayment](https://stripe.dev/stripe-react-native/api-reference/index.html#confirmPayment). This presents a webview where the customer can complete the payment with CashApp. Upon completion, the promise resolves with an object containing either a `paymentIntent` field, or an `error` field if an error occurred with the payment.

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

function PaymentScreen() {
  const {confirmPayment, loading} = useConfirmPayment();

  const fetchPaymentIntentClientSecret = async () => {
    // See above
  };

  const handlePayPress = async () => {
    // Fetch the client secret from the backend.
    const clientSecret = await fetchPaymentIntentClientSecret();

    const {error, paymentIntent} = await confirmPayment(clientSecret, {
      paymentMethodType: 'CashApp',
    });

    if (error) {
      console.log('Payment confirmation error: ', error);
    } else if (paymentIntent) {
      console.log('Successfully confirmed payment: ', paymentIntent);
    }
  };

  return (
    <View>
      <Button onPress={handlePayPress} title="Pay" disabled={loading} />
    </View>
  );
}
```

## Optional: 单独授权和捕获

You can separate authorization and capture to create a charge now, but capture funds later. Stripe cancels the PaymentIntent and sends a [payment_intent.canceled](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.canceled) event if the payment isn’t captured during the 7-day window.

If you know that you can’t capture the payment, we recommend [canceling the PaymentIntent](https://docs.stripe.com/refunds.md#cancel-payment) instead of waiting for the 7-day window to elapse.

### 1. Tell Stripe to authorize only

To indicate that you want separate authorization and capture, set [capture_method](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-capture_method) to `manual` when creating the PaymentIntent. This parameter instructs Stripe to only authorize the amount on the customer’s Cash App Pay account.

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=6000 \
  -d confirm=true \
  -d currency=usd \
  -d "payment_method_types[]=cashapp" \
  -d "payment_method_data[type]=cashapp" \
  -d capture_method=manual \
  --data-urlencode "return_url=https://www.example.com/checkout/done"
```

### 2. Capture the funds

After the authorization succeeds, the PaymentIntent [status](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-status) transitions to `requires_capture`. To capture the authorized funds, make a PaymentIntent [capture](https://docs.stripe.com/api/payment_intents/capture.md) request.

```curl
curl -X POST https://api.stripe.com/v1/payment_intents/{PAYMENT_INTENT_ID}/capture \
  -u "<<YOUR_SECRET_KEY>>:"
```

The total authorized amount is captured by default. You can also specify `amount_to_capture` which can be less or equal to the total.

### (可选) Cancel the authorization

If you need to cancel an authorization, you can [cancel the PaymentIntent](https://docs.stripe.com/api/payment_intents/cancel.md).

## Optional: 处理付款后事件

付款完成时，Stripe 会发送一个 [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) 事件。使用管理平台、自定义 *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 或一个合作伙伴方案来接收这些事件并运行操作，例如，向客户发送订单确认邮件、在数据库中记录订单，或启动配送流程。

侦听这些事件，而不是等待客户端的回调。在客户端上，客户可以在执行回调之前关闭浏览器窗口或退出应用程序，而且恶意客户端可以操纵响应。将集成设置为侦听异步事件还有助于您在未来接受更多支付方式。了解[所有受支持的支付方式之间的差异](https://stripe.com/payments/payment-methods-guide)。

- **在管理平台中手动处理事件**

  [在管理平台中查看测试支付情况](https://dashboard.stripe.com/test/payments)，发送邮件收据，处理提现事宜，或重试失败的付款。

- **创建自定义 Webhook**

  [Build a custom webhook](https://docs.stripe.com/webhooks/handling-payment-events.md#build-your-own-webhook) handler to listen for events and build custom asynchronous payment flows. Test and debug your webhook integration locally with the Stripe CLI.

- **集成一个预构建的 App**

  通过集成合作伙伴的应用程序，处理常见的企业事件，如[自动化](https://stripe.partners/?f_category=automation) 或[市场营销和销售](https://stripe.partners/?f_category=marketing-and-sales)。

## 测试您的集成

Test your Cash App Pay integration with your test API keys by viewing the redirect page. You can test the successful payment case by authenticating the payment on the redirect page. The [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) transitions from `requires_action` to `succeeded`.

To test the case where the user fails to authenticate, use your test API keys and view the redirect page. On the redirect page, click **Fail test payment**. The [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) transitions from `requires_action` to `requires_payment_method`.

For test [manual capture](https://docs.stripe.com/payments/cash-app-pay/accept-a-payment.md#manual-capture) PaymentIntents, the uncaptured PaymentIntent auto-expires 60 minutes after successful authorization.

In live mode, confirming the [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) redirects you to Cash App. As a best practice, test it in live mode with a real Cash App account before releasing it to your customers. In live mode, you don’t have the option to approve or decline the payment within Cash App. The payment is automatically approved after your customers are redirected to Cash App.

## Failed payments 

Cash App Pay uses multiple data points to decide when to decline a transaction (for example, their AI model detected high consumer fraud risk for the transaction, or the consumer has revoked your permission to charge them in Cash App).

In these cases, the [PaymentMethod](https://docs.stripe.com/api/payment_methods/object.md) is detached and the [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) object’s status automatically transitions to `requires_payment_method`.

Other than a payment being declined, for a Cash App Pay [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) with a status of `requires_action`, customers must complete the payment within 10 minutes after they’re redirected to Cash App. If no action is taken after 10 minutes, the [PaymentMethod](https://docs.stripe.com/api/payment_methods/object.md) is detached and the [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) object’s status automatically transitions to `requires_payment_method`.

When this happens, the Payment Element renders error messages and instructs your customer to retry using a different payment method.

## Error codes 

The following table details common error codes and recommended actions:

| 错误代码                                                      | 推荐操作                                                                                                                                                                                                                                                                         |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment_intent_invalid_currency`                         | Enter the appropriate currency. Cash App Pay only supports `usd`.                                                                                                                                                                                                            |
| `missing_required_parameter`                              | 查看错误消息以获取有关所需参数的详细信息。                                                                                                                                                                                                                                                        |
| `payment_intent_payment_attempt_failed`                   | This code can appear in the [last_payment_error.code](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-last_payment_error-code) field of a PaymentIntent. Check the error message for a detailed failure reason and suggestion on error handling. |
| `payment_intent_redirect_confirmation_without_return_url` | Provide a `return_url` when confirming a PaymentIntent with Cash App Pay.                                                                                                                                                                                                    |