# Aceitar um pagamento

Aceitar pagamentos online com segurança

## Start here: Install agent skills

Stripe recommends using official skills to integrate with the API using best practices. Follow the instructions below to learn how.

**Tip: Use curl instead of Fetch tools.** Skills are detailed 10–20 KB markdown files. Fetch tools summarize them. `curl -sL` guarantees the full content.

**Using `npx skills`**: Check if `npx` is installed on the system. If `npx` is available, run `npx skills add https://docs.stripe.com --list` to list available skills, then run `npx skills add https://docs.stripe.com --yes --skill <skill-name> <--skill other-skills>` to install individual skills.

**If `npx skills` isn’t available**: You can use curl to fetch the index of available skills, what they do, and their files from `https://docs.stripe.com/.well-known/skills/index.json`. To download a skill and its related files, use curl to download them from `https://docs.stripe.com/.well-known/skills/<filepath>`.

For this article, we recommend using these skills: `stripe-best-practices`

Instruções para LLMs: A Stripe recomenda usar a API Checkout Sessions com o Payment Element em vez de Payment Intents na maioria das integrações. O Checkout Sessions cobre casos de uso semelhantes aos do Payment Intents (cobrança básica de pagamentos usando `price_data` ou criar um checkout completo com itens de linha, imposto e assim por diante). Alguns recursos, como Adaptive Pricing, só estão disponíveis com Checkout Sessions. Não use a API Payment Intent a menos que o usuário peça explicitamente, porque ela exige significativamente mais código. Saiba mais sobre Elements com a API Checkout Sessions: https://docs.stripe.com/payments/quickstart-checkout-sessions. Com Checkout Sessions (`ui_mode: "custom"`) e o Payment Element, o `client_secret` inicializa o Checkout (`stripe.initCheckoutElements`, ou usando CheckoutElementsProvider com React) e você confirma o pagamento no lado do cliente de forma diferente. Se estiver usando React, certifique-se de importar de `@stripe/react-stripe-js/checkout`, usar `CheckoutElementsProvider` com o client secret e confirmar usando `checkout.confirm`. Se estiver usando HTML, certifique-se de usar `checkout = stripe.initCheckoutElements({clientSecret: promise}); checkout.createPaymentElement(); paymentElement = checkout.createPaymentElement(); paymentElement.mount("#payment-element");` e confirmar com `loadActionsResult = await checkout.loadActions(); actions = loadActionsResult.actions; error = await actions.confirm();`.

Crie um formulário de pagamento ou use uma página de checkout pré-integrada para começar a aceitar pagamentos online.

# Página hospedada pela Stripe

> This is a Página hospedada pela Stripe for when payment-ui is checkout and ui is stripe-hosted. View the full page at https://docs.stripe.com/payments/accept-a-payment?payment-ui=checkout&ui=stripe-hosted.

Redirecione para uma página de pagamento hospedada pela Stripe usando o [Stripe Checkout](https://docs.stripe.com/payments/checkout.md). [Compare esta integração com as outras formas de integração da Stripe](https://docs.stripe.com/payments/online-payments.md#compare-features-and-availability).

#### Esforço de integração
Complexity: 2/5
#### Tipo de integração

Redirecionar para a página de pagamento hospedada pela Stripe

#### Personalização da IU
Personalização limitada
- 20 fontes predefinidas
- 3 raios de borda predefinidos
- Cores do fundo e das bordas personalizadas
- Logotipo personalizado

[Experimente](https://checkout.stripe.dev/)

Primeiro, [cadastre-se](https://dashboard.stripe.com/register) para obter uma conta Stripe.

Use nossas bibliotecas oficiais para acessar a API da Stripe no seu aplicativo:

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

## Redirecione seu cliente para o Stripe Checkout [Lado do cliente] [Lado do servidor]

Adicione um botão de checkout ao site para chamar um endpoint do lado do servidor e criar uma [sessão do Checkout](https://docs.stripe.com/api/checkout/sessions/create.md).

Também é possível criar uma sessão do Checkout para um [cliente existente](https://docs.stripe.com/payments/existing-customers.md?platform=web&ui=stripe-hosted), permitindo preencher campos do Checkout com dados de contato conhecidos e unificar o histórico de compras desse cliente.

```html
<html>
  <head>
    <title>Buy cool new product</title>
  </head>
  <body>
    <!-- Use action="/create-checkout-session.php" if your server is PHP based. -->
    <form action="/create-checkout-session" method="POST">
      <button type="submit">Checkout</button>
    </form>
  </body>
</html>
```

A Sessão de Checkout a representação programática do que seu cliente vê ao ser redirecionado a um formulário de pagamento. Você pode configurá-lo com opções como:

- [Itens de linha](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items) a ser cobrado
- Moedas a usar

O campo `success_url` deve ser preenchido com o URL de uma página do seu site para onde o Checkout retornará o cliente após a conclusão do pagamento.

> As Sessões do Checkout expiram 24 horas após a criação por padrão.

Depois de criar uma Sessão do Checkout, redirecione o cliente ao [URL](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-url) retornado na resposta.

#### Ruby

```ruby
# This example sets up an endpoint using the Sinatra framework.


require 'json'
require 'sinatra'
require 'stripe'

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
Stripe.api_key = '<<YOUR_SECRET_KEY>>'

post '/create-checkout-session' dosession = Stripe::Checkout::Session.create({
    line_items: [{
      price_data: {
        currency: 'usd',
        product_data: {
          name: 'T-shirt',
        },
        unit_amount: 2000,
      },
      quantity: 1,
    }],
    mode: 'payment',
    # These placeholder URLs will be replaced in a following step.
    success_url: 'https://example.com/success',
  })

  redirect session.url, 303
end
```

### formas de pagamento

Por padrão, a Stripe habilita cartões e outras formas de pagamento comuns. É possível ativar ou desativar formas de pagamento individuais no [Stripe Dashboard](https://dashboard.stripe.com/settings/payment_methods). No Checkout, a Stripe avalia a moeda e as restrições e apresenta dinamicamente as formas de pagamento aceitas ao cliente.

Para ver como as formas de pagamento aparecem para os clientes, informe um ID de transação ou defina um valor e moeda de pedido no Dashboard.

Você pode ativar Apple Pay e Google Pay nas [configurações de formas de pagamento](https://dashboard.stripe.com/settings/payment_methods). Por padrão, o Apple Pay fica ativado, e o Google Pay, desativado. No entanto, em alguns casos, a Stripe remove-os mesmo quando estão ativados. Removemos o Google Pay se você [ativar o imposto automático](https://docs.stripe.com/tax/checkout.md) sem coletar um endereço de entrega.

As páginas hospedadas na Stripe do Checkout não precisam de mudanças na integração para habilitar Apple Pay ou Google Pay. A Stripe trata esses pagamentos da mesma forma que os outros pagamentos com cartão.

### Confirme seu endpoint

Confirme se o endpoint pode ser acessado iniciando seu servidor web (por exemplo, `localhost:4242`) e executando o seguinte comando:

```bash
curl -X POST -is "http://localhost:4242/create-checkout-session" -d ""
```

Você deve ver uma resposta no seu terminal assim:

```bash
HTTP/1.1 303 See Other
Location: https://checkout.stripe.com/c/pay/cs_test_...
...
```

### Testes

Agora o botão de checkout já deve estar pronto para redirecionar seu cliente para o Stripe Checkout.

1. Clique no botão de checkout.
1. Você será redirecionado para o formulário de pagamento do Stripe Checkout.

Se a sua integração não estiver funcionando:

1. Abra a guia Rede nas ferramentas de desenvolvedor do navegador.
1. Clique no botão de checkout e confirme se uma solicitação de XHR foi enviada para o endpoint no lado do servidor (`POST /create-checkout-session`).
1. Verifique se a solicitação retorna um status 200.
1. Use `console.log(session)` dentro de seu ouvinte de clique do botão para confirmar se os dados corretos são retornados.

## Mostrar uma página de finalização [Lado do cliente] [Lado do servidor]

É importante que o cliente veja uma página de finalização depois de enviar o formulário de pagamento corretamente. Hospede essa página de finalização no seu site.

Criar uma página de finalização mínima:

```html
<html>
  <head><title>Thanks for your order!</title></head>
  <body>
    <h1>Thanks for your order!</h1>
    <p>
      We appreciate your business!
      If you have any questions, please email
      <a href="mailto:orders@example.com">orders@example.com</a>.
    </p>
  </body>
</html>
```

Em seguida, atualize o endpoint de criação da sessão do Checkout para usar essa nova página:

```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 \
  --data-urlencode "success_url=http://localhost:4242/success.html"
```

> Se quiser personalizar a página de finalização, leia o guia sobre a [página de finalização personalizada](https://docs.stripe.com/payments/checkout/custom-success-page.md).

### Testes

1. Clique no botão do checkout.
1. Preencha os dados de pagamento com os dados do cartão de teste:
   - Informe o número do cartão `4242 4242 4242 4242`.
   - Informe uma data futura qualquer como validade do cartão.
   - Informe qualquer número de 3 dígitos como CVC.
   - Informe qualquer código postal de cobrança.
1. Clique em **Pagar**.
1. Você será redirecionado para a nova página de finalização.

Em seguida, encontre o novo pagamento no Stripe Dashboard. Os pagamentos bem-sucedidos aparecem na [lista de pagamentos](https://dashboard.stripe.com/payments). Quando você clicar em um pagamento, ele leva você até a página de detalhes do pagamento. A seção **Resumo do checkout** contém os dados de cobrança e a lista de itens comprados, que você pode usar para processar manualmente o pedido.

## Processar eventos pós-pagamento

A Stripe envia um evento [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) quando um cliente conclui o pagamento de uma sessão do Checkout. Use a [ferramenta Dashboard webhook](https://dashboard.stripe.com/webhooks) ou siga o [guia de webhooks](https://docs.stripe.com/webhooks/quickstart.md) para receber e processar esses eventos, que podem levar você a:

- Envie um e-mail de confirmação do pedido ao cliente.
- Registre a venda em banco de dados.
- Inicie um fluxo de trabalho de envio.

Escute esses eventos em vez de esperar que o cliente seja redirecionado de volta ao seu site. Acionar a execução apenas na página inicial do Checkout não é confiável. Configurar sua integração para escutar eventos assíncronos permite aceitar [diferentes tipos de formas de pagamento](https://stripe.com/payments/payment-methods-guide) com uma única integração.

Saiba mais no nosso [guia de execução para o Checkout](https://docs.stripe.com/checkout/fulfillment.md).

Gerencie os seguintes eventos ao coletar pagamentos com o Checkout:

| Evento                                                                                                                                       | Descrição                                                                                                                | Ação                                                                                                                                                                                           |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed)                             | Enviado quando um cliente conclui uma sessão do Checkout.                                                                | Envie ao cliente uma confirmação de pedido e *execute* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) o pedido. |
| [checkout.session.async_payment_succeeded](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.async_payment_succeeded) | Enviado quando um pagamento feito com uma forma de pagamento postergada, como débito automático ACH, é bem-sucedido.     | Envie ao cliente uma confirmação de pedido e *execute* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) o pedido. |
| [checkout.session.async_payment_failed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.async_payment_failed)       | Enviado quando ocorre uma falha em um pagamento feito com uma forma de pagamento postergada, como débito automático ACH. | Notifique o cliente sobre a falha e traga-o de volta à sessão para tentar pagar novamente.                                                                                                     |

## Teste sua integração

Para testar a integração do formulário de pagamento hospedado pela Stripe:

1. Crie uma Sessão do Checkout.
1. Preencha os dados de pagamento com um método da tabela a seguir.
   - Informe uma data futura qualquer como validade do cartão.
   - Informe qualquer número de 3 dígitos como CVC.
   - Informe qualquer código postal de cobrança.
1. Clique em **Pagar**. Você será redirecionado para `success_url`.
1. Acesse o Dashboard e procure o pagamento na [página Transações](https://dashboard.stripe.com/test/payments?status%5B0%5D=successful). Se o seu pagamento for bem-sucedido, ele aparecerá na lista.
1. Clique no pagamento para ver mais detalhes, como um resumo do Checkout com dados de faturamento e a lista de itens comprados. Você pode usar esses dados para executar o pedido.

Saiba como [testar sua integração](https://docs.stripe.com/testing.md).

#### Cartões

| Número do cartão    | Cenário                                                                                                                                                                                                                                                                                             | Como testar                                                                                                                 |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| 4242424242424242    | O pagamento com cartão é bem-sucedido e não precisa de autenticação.                                                                                                                                                                                                                                | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000002500003155    | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000000000009995    | O cartão é recusado com um código de recusa como `insufficient_funds`.                                                                                                                                                                                                                              | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 6205500000000000004 | O cartão UnionPay tem um comprimento variável de 13 a 19 dígitos.                                                                                                                                                                                                                                   | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |

#### Carteiras

| Forma de pagamento | Cenário                                                                                                                                                                   | Como testar                                                                                                                                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alipay             | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação imediata](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento. |

#### Débito bancário autenticado

| Forma de pagamento                   | Cenário                                                                                                                                                                                                | Como testar                                                                                                                                                                                                |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático BECS               | O cliente paga com débito automático BECS.                                                                                                                                                             | Preencha o formulário usando o número de conta `900123456` e BSB `000000`. Inicialmente, o status do PaymentIntent muda para `processing` e, 3 minutos depois, para `succeeded`.                           |
| Débito automático BECS               | O pagamento do cliente falha com um código de erro `account_closed`.                                                                                                                                   | Preencha o formulário usando o número da conta `111111113` e BSB `000000`.                                                                                                                                 |
| Bancontact, EPS, iDEAL, e Przelewy24 | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação imediata.                                                         | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar pagamento de teste** na página de redirecionamento. |
| Pay by Bank                          | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification).                             | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento.                                |
| Pay by Bank                          | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação posterior.                                                        | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar o pagamento de teste** na página de redirecionamento.                                  |
| BLIK                                 | Os pagamentos BLIK falham de várias formas: falhas imediatas (por exemplo, o código está vencido ou inválido), erros atrasados (o banco recusa) ou limites de tempo (o cliente não respondeu a tempo). | Use padrões de e-mail para [simular as diferentes falhas.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures)                                                                    |

#### Débitos bancários

| Forma de pagamento     | Cenário                                                                                           | Como testar                                                                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático SEPA | O cliente paga com débito automático SEPA.                                                        | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processando e, três minutos depois, para bem-sucedido. |
| Débito automático SEPA | O status da intenção de pagamento do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`.                                                                                                          |

#### Boletos

| Forma de pagamento | Cenário                                          | Como testar                                                                                    |
| ------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| Boleto, OXXO       | Seu cliente paga com um boleto ou uma guia OXXO. | Selecione boleto ou OXXO como forma de pagamento e envie o pagamento. Feche o diálogo exibido. |

Consulte [Testes](https://docs.stripe.com/testing.md) para obter mais informações sobre como testar sua integração.

### Cartões de teste

| Número              | Descrição                                                      |
| ------------------- | -------------------------------------------------------------- |
| 4242 4242 4242 4242 | Finaliza e processa o pagamento imediatamente.                 |
| 4000 0000 0000 3220 | Exige autenticação 3D Secure 2 para um pagamento bem-sucedido. |
| 4000 0000 0000 9995 | Sempre falha, com o código de recusa `insufficient_funds`.     |

## Optional: Criar produtos e preços

Antes de criar uma Sessão do Checkout, você pode criar *Produtos* (Products represent what your business sells—whether that's a good or a service) e *Preços* (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) antecipadamente. Use produtos para representar diferentes bens físicos ou níveis de serviço, e *Preços* (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) para representar o preço de cada produto. Você também pode [configurar sua Checkout Session](https://docs.stripe.com/payments/checkout/pay-what-you-want.md) para aceitar gorjetas e doações ou vender produtos e serviços com preço definido pelo cliente.

Por exemplo, você pode criar uma camiseta como produto com um preço de 20&nbsp;USD. Isso permite que você atualize e adicione preços sem precisar alterar os detalhes dos produtos correspondentes. Você pode criar produtos e preços com o Stripe Dashboard ou a API. Saiba mais sobre [como funcionam produtos e preços](https://docs.stripe.com/products-prices/how-products-and-prices-work.md).

#### API

A API precisa apenas de um `name` para criar um [produto](https://docs.stripe.com/api/products.md). O Checkout exibe os atributos `name`, `description` e `images` informados para o produto.

```curl
curl https://api.stripe.com/v1/products \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d name=T-shirt
```

Depois crie um [preço](https://docs.stripe.com/api/prices.md) para definir quanto cobrar pelo produto. Isso inclui quanto custa o produto e qual moeda usar.

```curl
curl https://api.stripe.com/v1/prices \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "product={{PRODUCT_ID}}" \
  -d unit_amount=2000 \
  -d currency=usd
```

#### Dashboard

> Copie produtos criados em uma área restrita para o modo de produção para não precisar recriá-los. Na visualização de detalhes do produto no Dashboard, clique em **Copiar para o modo de produção** no canto superior direito. Isso só pode ser feito uma vez para cada produto criado em uma área restrita. As atualizações subsequentes do produto de teste não serão refletidas no produto no modo de produção.

Para saber se você está em uma área restrita, clique em **Áreas restritas** no seletor de contas do Dashboard. Em seguida, defina os itens que deseja vender. Para criar um novo produto e preço:

- Acesse a seção [Produtos](https://dashboard.stripe.com/test/products) no Dashboard.
- Clique em **Adicionar produto**.
- Selecione **Uma vez** ao definir o preço.

O Checkout exibe o nome, a descrição e as imagens fornecidas para o produto.

Cada preço que você cria tem um ID. Quando você criar uma Checkout Session, faça referência ao ID e à quantidade do preço. Se estiver vendendo em várias moedas, crie seu Price *multimoedas*. O Checkout automaticamente [determina a moeda local do cliente](https://docs.stripe.com/payments/checkout/localize-prices/manual-currency-prices.md) e apresenta essa moeda se o Price aceitar.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  --data-urlencode "success_url=https://example.com/success?session_id={CHECKOUT_SESSION_ID}"
```

## Optional: Preencher dados do cliente [Lado do servidor]

Se você já coletou o e-mail do cliente e quer preenchê-lo antecipadamente na sessão de checkout, passe [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_email) ao criar uma sessão de checkout.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "customer_email=customer@example.com" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success"
```

## Optional: Salvar dados da forma de pagamento [Lado do servidor]

Por padrão, as formas de pagamento usadas para fazer um pagamento avulso com o Checkout não estão disponíveis para uso futuro.

### Salve formas de pagamento para cobrá-las fora de sessão

Você pode configurar o Checkout para salvar formas de pagamento usadas para fazer um pagamento avulso passando o argumento [payment_intent_data.setup_future_usage](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_intent_data-setup_future_usage). Isso é útil quando você precisa capturar uma forma de pagamento registrada para usar em tarifas futuras, como tarifas de cancelamento ou não comparecimento.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d customer_creation=always \
  -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 \
  --data-urlencode "success_url=https://example.com/success.html" \
  -d "payment_intent_data[setup_future_usage]=off_session"
```

If you use Checkout in `subscription` mode, Stripe automatically saves the payment method to charge it for subsequent payments. Card payment methods saved to customers using either `setup_future_usage` or `subscription` mode don’t appear for return purchases in Checkout (more on this below). We recommend using [custom text](https://docs.stripe.com/payments/checkout/custom-components.md#customize-text) to link out to any relevant terms regarding the usage of saved payment information.

> As leis globais de privacidade são complicadas e variadas. Recomendamos entrar em contato com a equipe jurídica ou de privacidade antes de implementar o [setup_future_usage](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_intent_data-setup_future_usage), porque isso pode afetar a estrutura de conformidade com requisitos de privacidade. Consulte [as orientações do Conselho de Proteção Europeu](https://edpb.europa.eu/system/files/2021-05/recommendations022021_on_storage_of_credit_card_data_en_1.pdf) para saber mais sobre como salvar dados de pagamento.

### Salvar formas de pagamento para preenchê-las no Checkout

Por padrão, o Checkout usa [Link](https://docs.stripe.com/payments/link/checkout-link.md) para oferecer aos seus clientes a opção de salvar e reutilizar com segurança suas informações de pagamento. Se preferir gerenciar as formas de pagamento por conta própria, use [saved_payment_method_options.payment_method_save](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-saved_payment_method_options-payment_method_save) ao criar uma Checkout Session para permitir que seus clientes salvem suas formas de pagamento para compras futuras no Checkout.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d customer_creation=always \
  -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 \
  --data-urlencode "success_url=https://example.com/success.html" \
  -d "saved_payment_method_options[payment_method_save]=enabled"
```

Passar esse parâmetro no modo de [pagamento](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-mode) ou [assinatura](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-mode) exibe uma caixa de seleção opcional para permitir que os clientes salvem explicitamente suas formas de pagamento para compras futuras. Quando os clientes marcam essa caixa de seleção, o Checkout salva a forma de pagamento com [allow_redisplay: always](https://docs.stripe.com/api/payment_methods/object.md#payment_method_object-allow_redisplay). O Checkout usa esse parâmetro para determinar se uma forma de pagamento pode ser preenchida antecipadamente em compras futuras. Ao usar `saved_payment_method_options.payment_method_save`, você não precisa passar `setup_future_usage` para salvar a forma de pagamento.

Se a sua plataforma Connect utiliza [Contas configuradas pelo cliente](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), utilize o nosso [guia](https://docs.stripe.com/connect/use-accounts-as-customers.md) para substituir as referências a `Cliente` e eventos no seu código pelas referências equivalentes da API Accounts v2.

O uso de [saved_payment_method_options.payment_method_save](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-saved_payment_method_options-payment_method_save) exige um `Customer`. Para salvar um novo cliente, defina o [customer_creation](https://docs.stripe.com/api/checkout/sessions/create.md) da sessão do Checkout como `always`. Caso contrário, a sessão não salva o cliente ou a forma de pagamento.

Se `payment_method_save` não for passado ou se o cliente não concordar em salvar a forma de pagamento, o Checkout ainda salvará as formas de pagamento criadas no modo `subscription` ou usando `setup_future_usage`. Essas formas de pagamento têm o valor `allow_redisplay` de `limited`, o que evita que sejam preenchidas para devolução de compras e permite que você cumpra as regras das bandeiras de cartão e os regulamentos de proteção de dados. Saiba como [alterar o comportamento padrão habilitado por esses modos](https://support.stripe.com/questions/prefilling-saved-cards-in-checkout) e como alterar ou sobrepor o comportamento do `allow_redisplay`.

> Você pode usar o Checkout para salvar cartões e outras formas de pagamento para cobrá-los fora da sessão, mas o Checkout preenche automaticamente os cartões salvos. Saiba como [preencher previamente cartões salvos](https://support.stripe.com/questions/prefilling-saved-cards-in-checkout). Para salvar uma forma de pagamento sem um pagamento inicial, [use o Checkout no modo de configuração](https://docs.stripe.com/payments/save-and-reuse.md?platform=checkout).

### Permitir que os clientes removam formas de pagamento salvas

Para permitir que os clientes removam uma forma de pagamento salva para que ela não volte a aparecer em pagamentos futuros, use [saved_payment_method_options.payment_method_remove](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-saved_payment_method_options-payment_method_remove) ao criar uma sessão do Checkout.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d customer={{CUSTOMER_ID}} \
  -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 \
  --data-urlencode "success_url=https://example.com/success.html" \
  -d "saved_payment_method_options[payment_method_remove]=enabled"
```

O cliente não pode remover uma forma de pagamento se ela estiver vinculada a uma assinatura ativa e o cliente não tiver uma forma de pagamento padrão salva para pagamentos de faturas e assinaturas.

## Optional: Separar autorização e captura [Lado do servidor]

A Stripe é compatível com pagamento com cartão em dois passos, então você pode primeiro autorizar um cartão e depois captura os fundos posteriormente. Quando a Stripe autoriza um pagamento, o cartão emissor garante os fundos e bloqueia o valor do pagamento no cartão do cliente. Em seguida, você tem um certo tempo para capturar os fundos,[dependendo do cartão](https://docs.stripe.com/payments/place-a-hold-on-a-payment-method.md#auth-capture-limitations)). Se você não captura o pagamento antes do vencimento da autorização, o pagamento é cancelado e o emissor libera os fundos retidos.

Separar a autorização da captura é útil para quem precisa realizar outros procedimentos entre a confirmação de que o cliente pode pagar e a cobrança do pagamento. Por exemplo, se você estiver vendendo itens com estoque limitado, pode ser necessário confirmar que o item comprado pelo cliente usando o Checkout ainda está disponível antes de capturar o pagamento e concluir a compra. Faça isso usando o seguinte fluxo de trabalho:

1. Confirme se a Stripe autorizou a forma de pagamento do cliente.
1. Consulte seu sistema de gestão de inventário para saber se o item ainda está disponível.
1. Atualize seu sistema de gestão de inventário para indicar que o cliente comprou o item.
1. Capture o pagamento do cliente.
1. Informe ao cliente se a compra foi finalizada em sua página de confirmação.

Para indicar que você quer separar a autorização da captura, defina [payment_intent_data.capture_method](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_intent_data-capture_method) como `manual` quando criar a sessão do Checkout. Isso instrui a Stripe a autorizar somente o valor no cartão do cliente.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=payment \
  -d "payment_intent_data[capture_method]=manual" \
  --data-urlencode "success_url=https://example.com/success.html"
```

Para capturar um pagamento pendente, você pode usar o [Dashboard](https://dashboard.stripe.com/test/payments?status%5B%5D=uncaptured) ou o endpoint [capture](https://docs.stripe.com/api/payment_intents/capture.md). Para capturar automaticamente os pagamentos, é preciso ter acesso ao PaymentIntent criado durante a sessão do Checkout, que você pode obter pelo objeto [Session](https://docs.stripe.com/api/payment_intents/capture.md).

## Optional: Gerenciamento de contas de clientes [Sem código]

Permita que seus clientes [gerenciem](https://docs.stripe.com/customer-management.md) as próprias contas, compartilhando um link para o seu *portal do cliente* (The customer portal is a secure, Stripe-hosted page that lets your customers manage their subscriptions and billing details). O portal do cliente permite que os clientes façam login com o próprio e-mail para gerenciar assinaturas, atualizar formas de pagamento e muito mais.

## See also

- [Adicionar descontos](https://docs.stripe.com/payments/checkout/discounts.md)
- [Recolher impostos](https://docs.stripe.com/payments/checkout/taxes.md)
- [Coletar IDs fiscais](https://docs.stripe.com/tax/checkout/tax-ids.md)
- [Adicionar envio](https://docs.stripe.com/payments/collect-addresses.md?payment-ui=checkout)
- [Personalize sua marca](https://docs.stripe.com/payments/checkout/customization.md)


# Formulário integrado

> This is a Formulário integrado for when payment-ui is checkout and ui is embedded-form. View the full page at https://docs.stripe.com/payments/accept-a-payment?payment-ui=checkout&ui=embedded-form.

Incorporar um formulário de pagamento pré-integrado ao seu site usando o [Stripe Checkout](https://docs.stripe.com/payments/checkout.md). Veja a comparação dessa integração [om outros tipos de integração da Stripe](https://docs.stripe.com/payments/online-payments.md#compare-features-and-availability).

#### Esforço de integração
Complexity: 2/5
#### Tipo de integração

Integre um formulário de pagamento pré-configurado ao seu site

#### Personalização da IU
Personalização limitada
- 20 fontes predefinidas
- 3 raios de borda predefinidos
- Cores do fundo e das bordas personalizadas
- Logotipo personalizado

Use as [configurações de marca](https://dashboard.stripe.com/settings/branding/checkout) no Stripe Dashboard para corresponder o Checkout ao design do seu site.

Primeiro, [cadastre-se](https://dashboard.stripe.com/register) para obter uma conta Stripe.

Use nossas bibliotecas oficiais para acessar a API da Stripe no seu aplicativo:

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

## Criar uma sessão do Checkout [Lado do servidor]

From your server, create a *Checkout Session* (A Checkout Session represents your customer's session as they pay for one-time purchases or subscriptions through Checkout. After a successful payment, the Checkout Session contains a reference to the Customer, and either the successful PaymentIntent or an active Subscription) and set the [ui_mode](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-ui_mode) to `embedded_page`. You can configure the [Checkout Session](https://docs.stripe.com/api/checkout/sessions/create.md) with [line items](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items) to include and options such as [currency](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-currency).

Também é possível criar uma sessão do Checkout para um [cliente existente](https://docs.stripe.com/payments/existing-customers.md?platform=web&ui=stripe-hosted), permitindo preencher campos do Checkout com dados de contato conhecidos e unificar o histórico de compras desse cliente.

Para retornar os clientes para uma página personalizada hospedada em seu site, especifique o URL da página no parâmetro [return_url](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-return_url). Inclua a variável de modelo `{CHECKOUT_SESSION_ID}` no URL para recuperar o status da sessão na página de retorno. O Checkout substitui automaticamente a variável pelo ID da Sessão do Checkout antes de fazer o redirecionamento.

Leia mais sobre a [configuração da página de retorno](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=checkout&ui=embedded-form#return-page) e outras opções para [personalizar o comportamento de redirecionamento](https://docs.stripe.com/payments/checkout/custom-success-page.md?payment-ui=embedded-form).

Depois de criar a sessão do Checkout, use o `client_secret` retornado na resposta para [montar o Checkout](https://docs.stripe.com/payments/accept-a-payment.md#mount-checkout).

#### Ruby

```ruby
# This example sets up an endpoint using the Sinatra framework.
require 'json'
require 'sinatra'
require 'stripe'

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
Stripe.api_key = '<<YOUR_SECRET_KEY>>'

post '/create-checkout-session' do
  session = Stripe::Checkout::Session.create({
    line_items: [{
      price_data: {
        currency: 'usd',
        product_data: {
          name: 'T-shirt',
        },
        unit_amount: 2000,
      },
      quantity: 1,
    }],
    mode: 'payment',ui_mode: 'embedded_page',return_url: 'https://example.com/checkout/return?session_id={CHECKOUT_SESSION_ID}'
  })

  {clientSecret: session.client_secret}.to_json
end
```

## Montar Checkout [Do lado do cliente]

#### HTML + JS

O Checkout está disponível como parte do [Stripe.js](https://docs.stripe.com/js.md). Inclua o script Stripe.js na página, adicionando-o ao cabeçalho do arquivo HTML. Em seguida, crie um nó DOM vazio (contêiner) para usar na montagem.

```html
<head>
  <script src="https://js.stripe.com/dahlia/stripe.js"></script>
</head>
<body>
  <div id="checkout">
    <!-- Checkout will insert the payment form here -->
  </div>
</body>
```

Inicialize o Stripe.js com sua chave de API publicável.

Crie uma função assíncrona `fetchClientSecret` que faz uma solicitação ao seu servidor para criar a Sessão do Checkout e recuperar o segredo do cliente. Passe essa função para `options` quando criar a instância do Checkout:

```javascript
// Initialize Stripe.js
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');

initialize();

// Fetch Checkout Session and retrieve the client secret
async function initialize() {
  const fetchClientSecret = async () => {
    const response = await fetch("/create-checkout-session", {
      method: "POST",
    });
    const { clientSecret } = await response.json();
    return clientSecret;
  };

  // Initialize Checkout
  const checkout = await stripe.createEmbeddedCheckoutPage({
    fetchClientSecret,
  });

  // Mount Checkout
  checkout.mount('#checkout');
}
```

#### React

Instale o [react-stripe-js](https://docs.stripe.com/sdks/stripejs-react.md) e o carregador Stripe.js do npm:

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

Para usar o componente Embedded Checkout, crie um `EmbeddedCheckoutProvider`. Chame `loadStripe` com sua chave de API publicável e passe a `Promise` retornada ao provedor.

Crie uma função assíncrona `fetchClientSecret` que faz uma solicitação ao seu servidor para criar a Sessão do Checkout e recuperar o segredo do cliente. Passe esta função para a propriedade `options` aceita pelo provedor.

```jsx
import * as React from 'react';
import {loadStripe} from '@stripe/stripe-js';
import {
  EmbeddedCheckoutProvider,
  EmbeddedCheckout
} from '@stripe/react-stripe-js';

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

const App = () => {
  const fetchClientSecret = React.useCallback(() => {
    // Create a Checkout Session
    return fetch("/create-checkout-session", {
      method: "POST",
    })
      .then((res) => res.json())
      .then((data) => data.clientSecret);
  }, []);

  const options = {fetchClientSecret};

  return (
    <div id="checkout">
      <EmbeddedCheckoutProvider
        stripe={stripePromise}
        options={options}
      >
        <EmbeddedCheckout />
      </EmbeddedCheckoutProvider>
    </div>
  )
}
```

O Checkout renderiza em um iframe que envia dados de pagamento com segurança para a Stripe por uma conexão HTTPS.

> Evite colocar o Checkout dentro de outro iframe porque algumas formas de pagamento exigem redirecionamento a outra página para confirmação do pagamento.

### Personalizar a aparência

Personalize o Checkout para corresponder ao design do seu site, definindo a cor de fundo, a cor do botão, o raio da borda e as fontes nas [configurações de marca](https://dashboard.stripe.com/settings/branding) da sua conta.

Por padrão, o Checkout é renderizado sem preenchimento ou margem externa. Recomendamos usar um elemento de contêiner, como um div para aplicar a margem desejada (for example, 16px em todos os lados).

## Exibir uma página de devolução

Depois que o cliente tenta fazer o pagamento, a Stripe o redireciona para uma página de devolução hospedada por você no seu site. Quando criou a sessão do Checkout, você especificou o URL da página de retorno no parâmetro [return_url](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-return_url). Leia mais sobre outras opções para [personalizar o comportamento de redirecionamento](https://docs.stripe.com/payments/checkout/custom-success-page.md?payment-ui=embedded-form).

Ao renderizar sua página de retorno, recupere o status da Sessão do Checkout usando o ID da Sessão do Checkout no URL. Trate o resultado de acordo com o status da sessão da seguinte forma:

- `complete`: o pagamento foi bem-sucedido. Use as informações da sessão do Checkout para renderizar uma página de sucesso.
- `open`: o pagamento falhou ou foi cancelado. Remonte o Checkout para que seu cliente possa tentar novamente.

#### Ruby

```ruby
get '/session-status' do
  session = Stripe::Checkout::Session.retrieve(params[:session_id])

  {status: session.status, customer_email:  session.customer_details.email}.to_json
end
```

```javascript
const session = await fetch(`/session_status?session_id=${session_id}`)
if (session.status == 'open') {
  // Remount embedded Checkout
} else if (session.status == 'complete') {
  // Show success page
  // Optionally use session.payment_status or session.customer_email
  // to customize the success page
}
```

#### Formas de pagamento baseadas em redirecionamento

Durante o pagamento, algumas formas de pagamento redirecionam o cliente para uma página intermediária, como uma página de autorização bancária. Quando concluem essa página, a Stripe os redireciona para sua página de retorno.

Saiba mais sobre as [formas de pagamento baseadas em redirecionamento e comportamento de redirecionamento](https://docs.stripe.com/payments/checkout/custom-success-page.md?payment-ui=embedded-form#redirect-based-payment-methods).

## Gerenciar eventos pós-pagamento

A Stripe envia um evento [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) quando um cliente conclui o pagamento de uma sessão do Checkout. Use a [ferramenta Dashboard webhook](https://dashboard.stripe.com/webhooks) ou siga o [guia de webhooks](https://docs.stripe.com/webhooks/quickstart.md) para receber e processar esses eventos, que podem levar você a:

- Envie um e-mail de confirmação do pedido ao cliente.
- Registre a venda em banco de dados.
- Inicie um fluxo de trabalho de envio.

Escute esses eventos em vez de esperar que o cliente seja redirecionado de volta ao seu site. Acionar a execução apenas na página inicial do Checkout não é confiável. Configurar sua integração para escutar eventos assíncronos permite aceitar [diferentes tipos de formas de pagamento](https://stripe.com/payments/payment-methods-guide) com uma única integração.

Saiba mais no nosso [guia de execução para o Checkout](https://docs.stripe.com/checkout/fulfillment.md).

Gerencie os seguintes eventos ao coletar pagamentos com o Checkout:

| Evento                                                                                                                                       | Descrição                                                                                                                | Ação                                                                                                                                                                                           |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed)                             | Enviado quando um cliente conclui uma sessão do Checkout.                                                                | Envie ao cliente uma confirmação de pedido e *execute* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) o pedido. |
| [checkout.session.async_payment_succeeded](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.async_payment_succeeded) | Enviado quando um pagamento feito com uma forma de pagamento postergada, como débito automático ACH, é bem-sucedido.     | Envie ao cliente uma confirmação de pedido e *execute* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) o pedido. |
| [checkout.session.async_payment_failed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.async_payment_failed)       | Enviado quando ocorre uma falha em um pagamento feito com uma forma de pagamento postergada, como débito automático ACH. | Notifique o cliente sobre a falha e traga-o de volta à sessão para tentar pagar novamente.                                                                                                     |

## Teste sua integração

Para testar a integração do seu formulário de pagamento integrado:

1. Crie uma Checkout Session integrada e incorpore o formulário de pagamento à sua página.
1. Preencha os dados de pagamento com um método da tabela abaixo.
   - Insira qualquer data futura para a validade do cartão.
   - Insira qualquer número de 3 dígitos para o CVC.
   - Insira qualquer código postal de faturamento.
1. Clique em **Pagar**. Você será redirecionado para o seu `return_url`.
1. Acesse o Dashboard e procure o pagamento na [página de Transações](https://dashboard.stripe.com/test/payments?status%5B0%5D=successful). Se o pagamento tiver sido realizado com sucesso, ele aparecerá nessa lista.
1. Clique no pagamento para ver mais detalhes, como um resumo do Checkout com as informações de faturamento e a lista de itens comprados. Você pode usar essas informações para executar o pedido.

Saiba mais sobre como [testar sua integração](https://docs.stripe.com/testing.md).

#### Cartões

| Número do cartão    | Cenário                                                                                                                                                                                                                                                                                             | Como testar                                                                                                                 |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| 4242424242424242    | O pagamento com cartão é bem-sucedido e não precisa de autenticação.                                                                                                                                                                                                                                | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000002500003155    | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000000000009995    | O cartão é recusado com um código de recusa como `insufficient_funds`.                                                                                                                                                                                                                              | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 6205500000000000004 | O cartão UnionPay tem um comprimento variável de 13 a 19 dígitos.                                                                                                                                                                                                                                   | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |

#### Carteiras

| Forma de pagamento | Cenário                                                                                                                                                                   | Como testar                                                                                                                                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alipay             | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação imediata](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento. |

#### Débito bancário autenticado

| Forma de pagamento                   | Cenário                                                                                                                                                                                                | Como testar                                                                                                                                                                                                |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático BECS               | O cliente paga com débito automático BECS.                                                                                                                                                             | Preencha o formulário usando o número de conta `900123456` e BSB `000000`. Inicialmente, o status do PaymentIntent muda para `processing` e, 3 minutos depois, para `succeeded`.                           |
| Débito automático BECS               | O pagamento do cliente falha com um código de erro `account_closed`.                                                                                                                                   | Preencha o formulário usando o número da conta `111111113` e BSB `000000`.                                                                                                                                 |
| Bancontact, EPS, iDEAL, e Przelewy24 | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação imediata.                                                         | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar pagamento de teste** na página de redirecionamento. |
| Pay by Bank                          | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification).                             | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento.                                |
| Pay by Bank                          | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação posterior.                                                        | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar o pagamento de teste** na página de redirecionamento.                                  |
| BLIK                                 | Os pagamentos BLIK falham de várias formas: falhas imediatas (por exemplo, o código está vencido ou inválido), erros atrasados (o banco recusa) ou limites de tempo (o cliente não respondeu a tempo). | Use padrões de e-mail para [simular as diferentes falhas.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures)                                                                    |

#### Débitos bancários

| Forma de pagamento     | Cenário                                                                                           | Como testar                                                                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático SEPA | O cliente paga com débito automático SEPA.                                                        | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processando e, três minutos depois, para bem-sucedido. |
| Débito automático SEPA | O status da intenção de pagamento do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`.                                                                                                          |

#### Boletos

| Forma de pagamento | Cenário                                          | Como testar                                                                                    |
| ------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| Boleto, OXXO       | Seu cliente paga com um boleto ou uma guia OXXO. | Selecione boleto ou OXXO como forma de pagamento e envie o pagamento. Feche o diálogo exibido. |

Consulte [Testes](https://docs.stripe.com/testing.md) para obter mais informações sobre como testar sua integração.

## Optional: Adicionar formas de pagamento

Por padrão, o Checkout [aceita várias formas de pagamento](https://docs.stripe.com/payments/payment-methods/integration-options.md#choose-how-to-add-payment-methods). Você precisa realizar etapas adicionais para habilitar e exibir algumas formas de pagamento, como Apple Pay, Google Pay e métodos do tipo compre agora e pague depois.

### Apple Pay e Google Pay

Para aceitar pagamentos do Apple Pay e do Google Pay, é preciso:

- Habilitá-las nas [configurações de formas de pagamento](https://dashboard.stripe.com/settings/payment_methods). O Apple Pay é habilitado por padrão.
- Opere seu aplicativo por HTTPS em desenvolvimento e produção.
- [Registre seu domínio](https://docs.stripe.com/payments/payment-methods/pmd-registration.md).
- Opere seu aplicativo por HTTPS em desenvolvimento e produção. Você pode usar um serviço como o [ngrok](https://ngrok.com/) para enviar seu aplicativo para testes locais.

Além disso, uma Sessão do Checkout só exibe o botão Apple Pay para os clientes quando *todas* as condições a seguir são verdadeiras:

- O dispositivo do cliente está executando macOS versão 17 ou posterior ou iOS versão 17 ou posterior.
- O cliente usa o navegador Safari.
- O cliente tem um cartão válido registrado no Apple Pay.

Uma Sessão do Checkout só exibe o botão Google Pay para os clientes quando *todas* as condições a seguir são verdadeiras:

- O dispositivo do cliente está executando o Chrome&nbsp;61 ou mais recente.
- O cliente tem um cartão válido registrado no Google Pay.

> #### Testes regionais
> 
> O Stripe Checkout não aceita Apple Pay ou Google Pay para contas ou clientes Stripe na Índia. Se o seu endereço IP estiver na Índia, não será possível testar o Apple Pay ou a integração do Google Pay, mesmo que a conta Stripe esteja fora da Índia.

## Optional: Criar produtos e preços

Antes de criar uma Sessão do Checkout, você pode criar *Produtos* (Products represent what your business sells—whether that's a good or a service) e *Preços* (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) antecipadamente. Use produtos para representar diferentes bens físicos ou níveis de serviço, e *Preços* (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) para representar o preço de cada produto. Você também pode [configurar sua Checkout Session](https://docs.stripe.com/payments/checkout/pay-what-you-want.md) para aceitar gorjetas e doações ou vender produtos e serviços com preço definido pelo cliente.

Por exemplo, você pode criar uma camiseta como produto com um preço de 20&nbsp;USD. Isso permite que você atualize e adicione preços sem precisar alterar os detalhes dos produtos correspondentes. Você pode criar produtos e preços com o Stripe Dashboard ou a API. Saiba mais sobre [como funcionam produtos e preços](https://docs.stripe.com/products-prices/how-products-and-prices-work.md).

#### API

A API precisa apenas de um `name` para criar um [produto](https://docs.stripe.com/api/products.md). O Checkout exibe os atributos `name`, `description` e `images` informados para o produto.

```curl
curl https://api.stripe.com/v1/products \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d name=T-shirt
```

Depois crie um [preço](https://docs.stripe.com/api/prices.md) para definir quanto cobrar pelo produto. Isso inclui quanto custa o produto e qual moeda usar.

```curl
curl https://api.stripe.com/v1/prices \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "product={{PRODUCT_ID}}" \
  -d unit_amount=2000 \
  -d currency=usd
```

#### Dashboard

> Copie produtos criados em uma área restrita para o modo de produção para não precisar recriá-los. Na visualização de detalhes do produto no Dashboard, clique em **Copiar para o modo de produção** no canto superior direito. Isso só pode ser feito uma vez para cada produto criado em uma área restrita. As atualizações subsequentes do produto de teste não serão refletidas no produto no modo de produção.

Para saber se você está em uma área restrita, clique em **Áreas restritas** no seletor de contas do Dashboard. Em seguida, defina os itens que deseja vender. Para criar um novo produto e preço:

- Acesse a seção [Produtos](https://dashboard.stripe.com/test/products) no Dashboard.
- Clique em **Adicionar produto**.
- Selecione **Uma vez** ao definir o preço.

O Checkout exibe o nome, a descrição e as imagens fornecidas para o produto.

Cada preço que você cria tem um ID. Quando você criar uma Checkout Session, faça referência ao ID e à quantidade do preço. Se estiver vendendo em várias moedas, crie seu Price *multimoedas*. O Checkout automaticamente [determina a moeda local do cliente](https://docs.stripe.com/payments/checkout/localize-prices/manual-currency-prices.md) e apresenta essa moeda se o Price aceitar.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return"
```

## Optional: Preencher dados do cliente [Lado do servidor]

Se você já coletou o e-mail do cliente e quer preenchê-lo antecipadamente na sessão de checkout, passe [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_email) ao criar uma sessão de checkout.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "customer_email=customer@example.com" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=payment \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return"
```

## Optional: Salvar dados da forma de pagamento [Lado do servidor]

Por padrão, as formas de pagamento usadas para fazer um pagamento avulso com o Checkout não estão disponíveis para uso futuro.

### Salve formas de pagamento para cobrá-las fora de sessão

Você pode configurar o Checkout para salvar formas de pagamento usadas para fazer um pagamento avulso passando o argumento [payment_intent_data.setup_future_usage](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_intent_data-setup_future_usage). Isso é útil quando você precisa capturar uma forma de pagamento registrada para usar em tarifas futuras, como tarifas de cancelamento ou não comparecimento.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d customer_creation=always \
  -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 ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return" \
  -d "payment_intent_data[setup_future_usage]=off_session"
```

If you use Checkout in `subscription` mode, Stripe automatically saves the payment method to charge it for subsequent payments. Card payment methods saved to customers using either `setup_future_usage` or `subscription` mode don’t appear for return purchases in Checkout (more on this below). We recommend using [custom text](https://docs.stripe.com/payments/checkout/custom-components.md#customize-text) to link out to any relevant terms regarding the usage of saved payment information.

> As leis globais de privacidade são complicadas e variadas. Recomendamos entrar em contato com a equipe jurídica ou de privacidade antes de implementar o [setup_future_usage](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_intent_data-setup_future_usage), porque isso pode afetar a estrutura de conformidade com requisitos de privacidade. Consulte [as orientações do Conselho de Proteção Europeu](https://edpb.europa.eu/system/files/2021-05/recommendations022021_on_storage_of_credit_card_data_en_1.pdf) para saber mais sobre como salvar dados de pagamento.

### Salvar formas de pagamento para preenchê-las no Checkout

Por padrão, o Checkout usa [Link](https://docs.stripe.com/payments/link/checkout-link.md) para oferecer aos seus clientes a opção de salvar e reutilizar com segurança suas informações de pagamento. Se preferir gerenciar as formas de pagamento por conta própria, use [saved_payment_method_options.payment_method_save](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-saved_payment_method_options-payment_method_save) ao criar uma Checkout Session para permitir que seus clientes salvem suas formas de pagamento para compras futuras no Checkout.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d customer_creation=always \
  -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 ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return" \
  -d "saved_payment_method_options[payment_method_save]=enabled"
```

Passar esse parâmetro no modo de [pagamento](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-mode) ou [assinatura](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-mode) exibe uma caixa de seleção opcional para permitir que os clientes salvem explicitamente suas formas de pagamento para compras futuras. Quando os clientes marcam essa caixa de seleção, o Checkout salva a forma de pagamento com [allow_redisplay: always](https://docs.stripe.com/api/payment_methods/object.md#payment_method_object-allow_redisplay). O Checkout usa esse parâmetro para determinar se uma forma de pagamento pode ser preenchida antecipadamente em compras futuras. Ao usar `saved_payment_method_options.payment_method_save`, você não precisa passar `setup_future_usage` para salvar a forma de pagamento.

Se a sua plataforma Connect utiliza [Contas configuradas pelo cliente](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), utilize o nosso [guia](https://docs.stripe.com/connect/use-accounts-as-customers.md) para substituir as referências a `Cliente` e eventos no seu código pelas referências equivalentes da API Accounts v2.

O uso de [saved_payment_method_options.payment_method_save](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-saved_payment_method_options-payment_method_save) exige um `Customer`. Para salvar um novo cliente, defina o [customer_creation](https://docs.stripe.com/api/checkout/sessions/create.md) da sessão do Checkout como `always`. Caso contrário, a sessão não salva o cliente ou a forma de pagamento.

Se `payment_method_save` não for passado ou se o cliente não concordar em salvar a forma de pagamento, o Checkout ainda salvará as formas de pagamento criadas no modo `subscription` ou usando `setup_future_usage`. Essas formas de pagamento têm o valor `allow_redisplay` de `limited`, o que evita que sejam preenchidas para devolução de compras e permite que você cumpra as regras das bandeiras de cartão e os regulamentos de proteção de dados. Saiba como [alterar o comportamento padrão habilitado por esses modos](https://support.stripe.com/questions/prefilling-saved-cards-in-checkout) e como alterar ou sobrepor o comportamento do `allow_redisplay`.

> Você pode usar o Checkout para salvar cartões e outras formas de pagamento para cobrá-los fora da sessão, mas o Checkout preenche automaticamente os cartões salvos. Saiba como [preencher previamente cartões salvos](https://support.stripe.com/questions/prefilling-saved-cards-in-checkout). Para salvar uma forma de pagamento sem um pagamento inicial, [use o Checkout no modo de configuração](https://docs.stripe.com/payments/save-and-reuse.md?platform=checkout).

### Permitir que os clientes removam formas de pagamento salvas

Para permitir que os clientes removam uma forma de pagamento salva para que ela não volte a aparecer em pagamentos futuros, use [saved_payment_method_options.payment_method_remove](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-saved_payment_method_options-payment_method_remove) ao criar uma sessão do Checkout.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d customer={{CUSTOMER_ID}} \
  -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 ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return" \
  -d "saved_payment_method_options[payment_method_remove]=enabled"
```

O cliente não pode remover uma forma de pagamento se ela estiver vinculada a uma assinatura ativa e o cliente não tiver uma forma de pagamento padrão salva para pagamentos de faturas e assinaturas.

## Optional: Gerenciamento de contas de clientes [Sem código]

Permita que seus clientes [gerenciem](https://docs.stripe.com/customer-management.md) as próprias contas, compartilhando um link para o seu *portal do cliente* (The customer portal is a secure, Stripe-hosted page that lets your customers manage their subscriptions and billing details). O portal do cliente permite que os clientes façam login com o próprio e-mail para gerenciar assinaturas, atualizar formas de pagamento e muito mais.

## Optional: Separar autorização e captura [Lado do servidor]

A Stripe é compatível com pagamento com cartão em dois passos, então você pode primeiro autorizar um cartão e depois captura os fundos posteriormente. Quando a Stripe autoriza um pagamento, o cartão emissor garante os fundos e bloqueia o valor do pagamento no cartão do cliente. Em seguida, você tem um certo tempo para capturar os fundos,[dependendo do cartão](https://docs.stripe.com/payments/place-a-hold-on-a-payment-method.md#auth-capture-limitations)). Se você não captura o pagamento antes do vencimento da autorização, o pagamento é cancelado e o emissor libera os fundos retidos.

Separar a autorização da captura é útil para quem precisa realizar outros procedimentos entre a confirmação de que o cliente pode pagar e a cobrança do pagamento. Por exemplo, se você estiver vendendo itens com estoque limitado, pode ser necessário confirmar que o item comprado pelo cliente usando o Checkout ainda está disponível antes de capturar o pagamento e concluir a compra. Faça isso usando o seguinte fluxo de trabalho:

1. Confirme se a Stripe autorizou a forma de pagamento do cliente.
1. Consulte seu sistema de gestão de inventário para saber se o item ainda está disponível.
1. Atualize seu sistema de gestão de inventário para indicar que o cliente comprou o item.
1. Capture o pagamento do cliente.
1. Informe ao cliente se a compra foi finalizada em sua página de confirmação.

Para indicar que você quer separar a autorização da captura, defina [payment_intent_data.capture_method](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_intent_data-capture_method) como `manual` quando criar a sessão do Checkout. Isso instrui a Stripe a autorizar somente o valor no cartão do cliente.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=payment \
  -d "payment_intent_data[capture_method]=manual" \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/return"
```

Para capturar um pagamento pendente, você pode usar o [Dashboard](https://dashboard.stripe.com/test/payments?status%5B%5D=uncaptured) ou o endpoint [capture](https://docs.stripe.com/api/payment_intents/capture.md). Para capturar automaticamente os pagamentos, é preciso ter acesso ao PaymentIntent criado durante a sessão do Checkout, que você pode obter pelo objeto [Session](https://docs.stripe.com/api/payment_intents/capture.md).

## Optional: Execução de pedidos

Saiba como [receber uma notificação automaticamente](https://docs.stripe.com/checkout/fulfillment.md) sempre que um cliente pagar.

## See also

- [Adicionar descontos](https://docs.stripe.com/payments/checkout/discounts.md)
- [Recolher impostos](https://docs.stripe.com/payments/checkout/taxes.md)
- [Coletar IDs fiscais](https://docs.stripe.com/tax/checkout/tax-ids.md)
- [Adicionar envio](https://docs.stripe.com/payments/collect-addresses.md?payment-ui=checkout)
- [Personalize sua marca](https://docs.stripe.com/payments/checkout/customization.md)


# API de Checkout Sessions

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

Crie um formulário de pagamento personalizado usando o [Stripe Elements](https://docs.stripe.com/payments/elements.md) e a API de [Checkout Sessions](https://docs.stripe.com/api/checkout/sessions.md). Veja como essa integração [se compara aos outros tipos de integração](https://docs.stripe.com/payments/online-payments.md#compare-features-and-availability) da Stripe.

A API de Checkout Sessions fornece suporte integrado para cálculo tributário, descontos, envio e conversão de moedas, reduzindo a quantidade de código personalizado que você precisa escrever. Essa é a abordagem recomendada para a maioria das integrações. Saiba mais sobre [quando usar Checkout Sessions em vez de PaymentIntents](https://docs.stripe.com/payments/checkout-sessions-and-payment-intents-comparison.md).

O código do lado do cliente e do lado do servidor cria um formulário de Checkout que aceita várias formas de pagamento.

#### Esforço de integração
Complexity: 3/5
#### Tipo de integração

Combine componentes de IU em um fluxo de pagamento personalizado

#### Personalização da IU

Personalização no nível de CSS com a [API Appearance](https://docs.stripe.com/elements/appearance-api.md)

## Configure o servidor [Lado do servidor]

Antes de começar, você precisa [se cadastrar](https://dashboard.stripe.com/register) para uma conta Stripe.

Use as bibliotecas Stripe oficiais para acessar o API do seu aplicativo.

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

## Criar uma sessão do Checkout [Lado do servidor]

Adicione um endpoint no seu servidor que crie uma [Sessão de Checkout](https://docs.stripe.com/api/checkout/sessions/create.md) e retorne seu [`client_secret`](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-client_secret) para o seu front-end. Uma Sessão de Checkout representa a sessão do seu cliente enquanto ele paga por compras únicas ou assinaturas. As sessões de checkout vencem 24 horas após sua criação.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d ui_mode=elements \
  -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 \
  --data-urlencode "return_url=https://example.com/return?session_id={CHECKOUT_SESSION_ID}"
```

## Configurar o frontend [Lado do cliente]

#### HTML + JS

Inclua o script Stripe.js na página de checkout, adicionando-o ao `head` do seu arquivo HTML. Sempre carregue o Stripe.js diretamente a partir do js.stripe.com para manter a conformidade com PCI. Não insira o script em um pacote nem hospede sua própria cópia.

Certifique-se de estar usando a versão mais recente de Stripe.js. Saiba mais sobre o [versionamento de Stripe.js](https://docs.stripe.com/sdks/stripejs-versioning.md).

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

> A Stripe fornece um pacote npm que você pode usar para carregar o Stripe.js como um módulo. Veja o [projeto no GitHub](https://github.com/stripe/stripe-js). A versão [7.0.0](https://www.npmjs.com/package/%40stripe/stripe-js/v/7.0.0) ou posterior é necessária.

Inicialize o 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

Instale o [React Stripe.js](https://www.npmjs.com/package/@stripe/react-stripe-js) e o[carregador Stripe.js](https://www.npmjs.com/package/@stripe/stripe-js) do registro público do npm. Você precisa de pelo menos a versão 5.0.0 do React Stripe.js e a versão 8.0.0 do carregador Stripe.js.

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

Inicialize uma instância de `stripe` no frontend com sua chave publicável.

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

## Inicializar o Checkout [Lado do cliente]

#### HTML + JS

Chame [initCheckoutElementsSdk](https://docs.stripe.com/js/custom_checkout/init), passando o `clientSecret`.

`initCheckoutElementsSdk` retorna um objeto [Checkout](https://docs.stripe.com/js/custom_checkout) que contém dados da Checkout Session e métodos para atualizá-lo.

Leia o `total` e `lineItems` de [actions.getSession()](https://docs.stripe.com/js/custom_checkout/session), e exibi-os na sua IU. Isso permite ativar novos recursos com mínimas alterações no código. Por exemplo, somando [preços de moeda manual](https://docs.stripe.com/payments/custom/localize-prices/manual-currency-prices.md) não requer alterações na IU se você exibir o `total`.

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

Envolva seu aplicativo com o componente [CheckoutElementsProvider](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider), passando `clientSecret` e a instância `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;
```

Acesse o objeto do [Checkout](https://docs.stripe.com/js/custom_checkout) no seu componente do formulário de checkout usando o hook `useCheckout()`. O objeto do `Checkout` contém dados da sessão de checkout e métodos para atualizá-lo.

Leia o `total` e `lineItems` do objeto do `Checkout` e exibi-lo na sua IU. Isso permite que você ative recursos com mudanças mínimas no código. Por exemplo, somando [preços de moeda manualmente](https://docs.stripe.com/payments/custom/localize-prices/manual-currency-prices.md) não requer alterações na IU se você exibir o `total`.

```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>
  );
};
```

## Coletar e-mail do cliente [Lado do cliente]

#### HTML + JS

Ao concluir uma sessão do Checkout, é necessário fornecer um e-mail válido do cliente.

Essas instruções criam um campo de entrada de e‑mail e utilizam o método [updateEmail](https://docs.stripe.com/js/custom_checkout/update_email) do objeto `Checkout`.

Ou, você pode:

- Informe o [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_email) ou o [customer](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer) ao criar a sessão do Checkout. A Stripe valida os e-mails fornecidos dessa forma.
- Informe um e‑mail que você já tenha validado no [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

Ao concluir uma sessão do Checkout, é necessário fornecer um e-mail válido do cliente.

Essas instruções criam um campo de entrada de e‑mail e utilizam o método [updateEmail](https://docs.stripe.com/js/react_stripe_js/checkout/update_email) do objeto `Checkout`.

Ou, você pode:

- Informe o [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_email) ou o [customer](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer) ao criar a sessão do Checkout. A Stripe valida os e-mails fornecidos dessa forma.
- Informe um e‑mail que você já tenha validado no [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;
```

## Coletar dados de pagamento [Lado do cliente]

Colete dados de pagamento no cliente com o [Payment Element](https://docs.stripe.com/payments/payment-element.md). O Payment Element é um componente de IU que simplifica a coleta de dados de pagamento para diversas formas de pagamento.

O Payment Element contém um iframe que envia dados de pagamento com segurança à Stripe por uma conexão HTTPS. Evite colocar o Payment Element dentro de outro iframe porque algumas formas de pagamento exigem o redirecionamento para outra página para confirmação do pagamento.

Se você optar por usar um iframe e quiser aceitar Apple Pay ou Google Pay, o iframe deve ter o atributo [permitir](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#attr-allowpaymentrequest) definido como igual a `"pagamento *"`.

O endereço da página de Checkout deve começar com `https://` rather em vez de `http://` for para que sua integração funcione corretamente. Você pode testar sua integração sem usar HTTPS, mas lembre-se de [habilitá-lo](https://docs.stripe.com/security/guide.md#tls) quando estiver pronto para aceitar pagamentos em tempo real.

#### HTML + JS

Primeiro, crie um elemento DOM de contêiner para montar o [Payment Element](https://docs.stripe.com/payments/payment-element.md). Em seguida, crie uma instância do `Payment Element` usando [checkout.createPaymentElement](https://docs.stripe.com/js/custom_checkout/create_payment_element) e monte-a chamando [element.mount](https://docs.stripe.com/js/element/mount), fornecendo um seletor CSS ou o elemento DOM do contêiner.

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

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

Veja as opções disponíveis na documentação da [Stripe.js](https://docs.stripe.com/js/custom_checkout/create_payment_element#custom_checkout_create_payment_element-options).

Você pode [personalizar a aparência](https://docs.stripe.com/payments/checkout/customization/appearance.md) de todos os Elements passando [elementsOptions.appearance](https://docs.stripe.com/js/custom_checkout/init#custom_checkout_init-options-elementsOptions-appearance) ao inicializar o Checkout no frontend.

#### React

Monte o componente [Payment Element](https://docs.stripe.com/payments/payment-element.md) dentro do [CheckoutElementsProvider](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider).

```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;
```

Veja as opções disponíveis na documentação da [Stripe.js](https://docs.stripe.com/js/custom_checkout/create_payment_element#custom_checkout_create_payment_element-options).

Você pode [personalizar a aparência](https://docs.stripe.com/payments/checkout/customization/appearance.md) de todos os Elements passando [elementsOptions.appearance](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider#react_checkout_provider-options-elementsOptions-appearance) para o [CheckoutElementsProvider](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider).

## Envie o pagamento [Lado do cliente]

#### HTML + JS

Renderize um botão **Pagar** que chame a [confirmação](https://docs.stripe.com/js/custom_checkout/confirm) da instância `Checkout` para enviar o pagamento.

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

Renderize um botão **Pagar** que chame [confirm](https://docs.stripe.com/js/custom_checkout/confirm) do [useCheckout](https://docs.stripe.com/js/react_stripe_js/checkout/use_checkout) para submeter o pagamento.

```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;
```

## Teste a integração

1. Acesse a página de checkout.
1. Preencha os dados de pagamento com uma forma de pagamento da tabela a seguir. Para pagamentos com cartão:
   - Informe uma data futura qualquer como validade do cartão.
   - Informe qualquer número de 3 dígitos como CVC.
   - Informe qualquer código postal de cobrança.
1. Envie o pagamento para a Stripe.
1. Acesse o Dashboard e procure o pagamento na [página Transações](https://dashboard.stripe.com/test/payments?status%5B0%5D=successful). Se o seu pagamento for bem-sucedido, ele aparecerá na lista.
1. Clique no pagamento para ver mais detalhes, como dados de cobrança e a lista de itens comprados. Você pode usar essas informações para [executar o pedido](https://docs.stripe.com/checkout/fulfillment.md).

#### Cartões

| Número do cartão    | Cenário                                                                                                                                                                                                                                                                                             | Como testar                                                                                                                 |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| 4242424242424242    | O pagamento com cartão é bem-sucedido e não precisa de autenticação.                                                                                                                                                                                                                                | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000002500003155    | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000000000009995    | O cartão é recusado com um código de recusa como `insufficient_funds`.                                                                                                                                                                                                                              | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 6205500000000000004 | O cartão UnionPay tem um comprimento variável de 13 a 19 dígitos.                                                                                                                                                                                                                                   | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |

#### Carteiras

| Forma de pagamento | Cenário                                                                                                                                                                   | Como testar                                                                                                                                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alipay             | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação imediata](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento. |

#### Débito bancário autenticado

| Forma de pagamento                   | Cenário                                                                                                                                                                                                | Como testar                                                                                                                                                                                                |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático BECS               | O cliente paga com débito automático BECS.                                                                                                                                                             | Preencha o formulário usando o número de conta `900123456` e BSB `000000`. Inicialmente, o status do PaymentIntent muda para `processing` e, 3 minutos depois, para `succeeded`.                           |
| Débito automático BECS               | O pagamento do cliente falha com um código de erro `account_closed`.                                                                                                                                   | Preencha o formulário usando o número da conta `111111113` e BSB `000000`.                                                                                                                                 |
| Bancontact, EPS, iDEAL, e Przelewy24 | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação imediata.                                                         | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar pagamento de teste** na página de redirecionamento. |
| Pay by Bank                          | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification).                             | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento.                                |
| Pay by Bank                          | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação posterior.                                                        | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar o pagamento de teste** na página de redirecionamento.                                  |
| BLIK                                 | Os pagamentos BLIK falham de várias formas: falhas imediatas (por exemplo, o código está vencido ou inválido), erros atrasados (o banco recusa) ou limites de tempo (o cliente não respondeu a tempo). | Use padrões de e-mail para [simular as diferentes falhas.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures)                                                                    |

#### Débitos bancários

| Forma de pagamento     | Cenário                                                                                           | Como testar                                                                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático SEPA | O cliente paga com débito automático SEPA.                                                        | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processando e, três minutos depois, para bem-sucedido. |
| Débito automático SEPA | O status da intenção de pagamento do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`.                                                                                                          |

#### Boletos

| Forma de pagamento | Cenário                                          | Como testar                                                                                    |
| ------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| Boleto, OXXO       | Seu cliente paga com um boleto ou uma guia OXXO. | Selecione boleto ou OXXO como forma de pagamento e envie o pagamento. Feche o diálogo exibido. |

Consulte [Testes](https://docs.stripe.com/testing.md) para obter mais informações sobre como testar sua integração.

## Optional: Criar produtos e preços

Antes de criar uma Sessão do Checkout, você pode criar *Produtos* (Products represent what your business sells—whether that's a good or a service) e *Preços* (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) antecipadamente. Use produtos para representar diferentes bens físicos ou níveis de serviço, e *Preços* (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) para representar o preço de cada produto. Você também pode [configurar sua Checkout Session](https://docs.stripe.com/payments/checkout/pay-what-you-want.md) para aceitar gorjetas e doações ou vender produtos e serviços com preço definido pelo cliente.

Por exemplo, você pode criar uma camiseta como produto com um preço de 20&nbsp;USD. Isso permite que você atualize e adicione preços sem precisar alterar os detalhes dos produtos correspondentes. Você pode criar produtos e preços com o Stripe Dashboard ou a API. Saiba mais sobre [como funcionam produtos e preços](https://docs.stripe.com/products-prices/how-products-and-prices-work.md).

#### API

A API precisa apenas de um `name` para criar um [produto](https://docs.stripe.com/api/products.md). O Checkout exibe os atributos `name`, `description` e `images` informados para o produto.

```curl
curl https://api.stripe.com/v1/products \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d name=T-shirt
```

Depois crie um [preço](https://docs.stripe.com/api/prices.md) para definir quanto cobrar pelo produto. Isso inclui quanto custa o produto e qual moeda usar.

```curl
curl https://api.stripe.com/v1/prices \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "product={{PRODUCT_ID}}" \
  -d unit_amount=2000 \
  -d currency=usd
```

#### Dashboard

> Copie produtos criados em uma área restrita para o modo de produção para não precisar recriá-los. Na visualização de detalhes do produto no Dashboard, clique em **Copiar para o modo de produção** no canto superior direito. Isso só pode ser feito uma vez para cada produto criado em uma área restrita. As atualizações subsequentes do produto de teste não serão refletidas no produto no modo de produção.

Para saber se você está em uma área restrita, clique em **Áreas restritas** no seletor de contas do Dashboard. Em seguida, defina os itens que deseja vender. Para criar um novo produto e preço:

- Acesse a seção [Produtos](https://dashboard.stripe.com/test/products) no Dashboard.
- Clique em **Adicionar produto**.
- Selecione **Uma vez** ao definir o preço.

O Checkout exibe o nome, a descrição e as imagens fornecidas para o produto.

Cada preço que você cria tem um ID. Quando você criar uma Checkout Session, faça referência ao ID e à quantidade do preço. Se estiver vendendo em várias moedas, crie seu Price *multimoedas*. O Checkout automaticamente [determina a moeda local do cliente](https://docs.stripe.com/payments/checkout/localize-prices/manual-currency-prices.md) e apresenta essa moeda se o Price aceitar.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d ui_mode=elements \
  -d mode=payment \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  --data-urlencode "return_url=https://example.com/return?session_id={CHECKOUT_SESSION_ID}"
```

## Optional: Preencher dados do cliente [Lado do servidor]

Se você já coletou o e-mail do cliente e quer preenchê-lo antecipadamente na sessão de checkout, passe [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_email) ao criar uma sessão de checkout.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "customer_email=customer@example.com" \
  -d ui_mode=elements \
  -d mode=payment \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  --data-urlencode "return_url=https://example.com/return?session_id={CHECKOUT_SESSION_ID}"
```

## Optional: Salvar dados da forma de pagamento

Saiba como [aceitar um pagamento e salvar os dados de pagamento](https://docs.stripe.com/payments/save-during-payment.md) do seu cliente para futuras compras.

## Optional: Escutar mudanças na sessão do Checkout

### Escutar mudanças na sessão do Checkout

Você pode escutar mudanças na [sessão do Checkout](https://docs.stripe.com/api/checkout/sessions.md) adicionando um ouvinte no evento `change` com [checkout.on](https://docs.stripe.com/js/custom_checkout/change_event).

#### HTML + JS

```javascript
checkout = stripe.initCheckoutElementsSdk({
  clientSecret: promise,
  elementsOptions: { appearance },
});

checkout.on('change', (session) => {
  // Handle changes to the checkout session
});
```

#### React

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

const CheckoutForm = () => {
  const checkoutState = useCheckout();
  if (checkoutState.type === 'success') {
    checkoutState.checkout.on('change', (session) => {
      // Handle changes to the checkout session
    });
  }
};
```

## Optional: Coletar endereços de cobrança e envio

## Coletar um endereço de cobrança

Por padrão, uma sessão do Checkout coleta os dados mínimos de cobrança necessários para pagamento por meio do Payment Element.

### Usar o Billing Address Element

Você pode coletar endereços de cobrança completos usando o Billing Address Element.

Primeiro, passe [billing_address_collection=required](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-billing_address_collection) ao criar a sessão do Checkout.

#### HTML + JS

Crie um elemento DOM de contêiner para montar o Billing Address Element. Em seguida, crie uma instância do Billing Address Element usando [checkout.createBillingAddressElement](https://docs.stripe.com/js/custom_checkout/create_billing_address_element) e monte-a chamando [element.mount](https://docs.stripe.com/js/element/mount), fornecendo um seletor CSS ou o elemento DOM do contêiner.

```html
<div id="billing-address"></div>
```

```javascript
const billingAddressElement = checkout.createBillingAddressElement();
billingAddressElement.mount('#billing-address');
```

O Billing Address Element aceita as seguintes opções:

- [contacts](https://docs.stripe.com/js/custom_checkout/create_billing_address_element#custom_checkout_create_billing_address_element-options-contacts)
- [display](https://docs.stripe.com/js/custom_checkout/create_billing_address_element#custom_checkout_create_billing_address_element-options-display)

#### React

Monte o componente `BillingAddressElement` dentro do `CheckoutElementsProvider`.

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

const CheckoutForm = () => {
  return (
    <form>
      <BillingAddressElement/>
    </form>
  )
};
```

O Billing Address Element aceita os seguintes elementos:

- [contacts](https://docs.stripe.com/js/custom_checkout/create_billing_address_element#custom_checkout_create_billing_address_element-options-contacts)
- [display](https://docs.stripe.com/js/custom_checkout/create_billing_address_element#custom_checkout_create_billing_address_element-options-display)

### Usar um formulário personalizado

Você pode criar seu próprio formulário para coletar endereços de cobrança.

- Se sua página de checkout tiver uma etapa distinta de coleta de endereço antes da confirmação, chame [updateBillingAddress](https://docs.stripe.com/js/react_stripe_js/checkout/update_billing_address) quando seu cliente enviar o endereço.
- Caso contrário, você pode enviar o endereço quando o cliente clicar no botão “Pagar”, passando [billingAddress](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-billingAddress) para [confirm](https://docs.stripe.com/js/custom_checkout/confirm).

### Coletar endereços de cobrança parciais

Para coletar endereços de cobrança parciais, como apenas o país e o código postal, passe [billing_address_collection=auto](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-billing_address_collection).

Ao coletar endereços de cobrança parciais, você deve [coletar endereços manualmente](https://docs.stripe.com/payments/accept-a-payment.md#collect-billing-addresses-manually). Por padrão, o Payment Element coleta automaticamente os dados mínimos de cobrança necessários para o pagamento. Para evitar a coleta dupla de dados de cobrança, passe [fields.billingDetails=never](https://docs.stripe.com/js/custom_checkout/create_payment_element#custom_checkout_create_payment_element-options-fields-billingDetails) quando criar o Payment Element. Se você pretende coletar apenas um subconjunto de dados de cobrança (como o nome do cliente), passe `never` apenas para os campos que você pretende coletar por conta própria.

## Coletar um endereço de entrega

Para coletar o endereço de entrega de um cliente, passe o parâmetro [shipping_address_collection](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-shipping_address_collection) ao criar a sessão do Checkout.

Quando você coleta um endereço de entrega, também precisa especificar para quais países deseja efetuar entregas. Configure a propriedade [allowed_countries](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-shipping_address_collection-allowed_countries) com uma matriz de [códigos de país ISO de duas letras](https://www.nationsonline.org/oneworld/country_code_list.htm).

### Como usar o Shipping Address Element

Você pode coletar endereços de entrega completos com o Shipping Address Element.

#### HTML + JS

Crie um elemento DOM de contêiner para montar o Shipping Address Element. Em seguida, crie uma instância do Shipping Address Element usando [checkout.createShippingAddressElement](https://docs.stripe.com/js/custom_checkout/create_shipping_address_element) e monte-a chamando [element.mount](https://docs.stripe.com/js/element/mount), fornecendo um seletor CSS ou o elemento DOM do contêiner.

```html
<div id="shipping-address"></div>
```

```javascript
const shippingAddressElement = checkout.createShippingAddressElement();
shippingAddressElement.mount('#shipping-address');
```

O Shipping Address Element aceita as seguintes opções:

- [contacts](https://docs.stripe.com/js/custom_checkout/create_shipping_address_element#custom_checkout_create_shipping_address_element-options-contacts)
- [display](https://docs.stripe.com/js/custom_checkout/create_shipping_address_element#custom_checkout_create_shipping_address_element-options-display)

#### React

Monte o componente `ShippingAddressElement` dentro do `CheckoutElementsProvider`.

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

const CheckoutForm = () => {
  return (
    <form>
      <ShippingAddressElement/>
    </form>
  )
};
```

O Shipping Address Element aceita os seguintes elementos:

- [contacts](https://docs.stripe.com/js/custom_checkout/create_shipping_address_element#custom_checkout_create_shipping_address_element-options-contacts)
- [display](https://docs.stripe.com/js/custom_checkout/create_shipping_address_element#custom_checkout_create_shipping_address_element-options-display)

### Escutar mudanças na sessão do Checkout

Você pode escutar alterações na [sessão do Checkout](https://docs.stripe.com/api/checkout/sessions.md) adicionando um ouvinte de eventos para gerenciar alterações relacionadas ao endereço.

#### HTML + JS

Use o [objeto Session](https://docs.stripe.com/js/custom_checkout/session_object) para processar o valor do envio no formulário de checkout.

```html
<div>
  <h3> Totals </h3>
  <div id="subtotal" ></div>
  <div id="shipping" ></div>
  <div id="total" ></div>
</div>
```

```javascript
const checkout = stripe.initCheckoutElementsSdk({clientSecret});
const subtotal = document.getElementById('subtotal');
const shipping = document.getElementById('shipping');
const total = document.getElementById('total');

checkout.on('change', (session) => {
  subtotal.textContent = `Subtotal: ${session.total.subtotal.amount}`;
  shipping.textContent = `Shipping: ${session.total.shippingRate.amount}`;
  total.textContent = `Total: ${session.total.total.amount}`;
});

```

#### React

Use [useCheckout](https://docs.stripe.com/js/react_stripe_js/checkout/use_checkout) para exibir o custo de envio no seu formulário de checkout.

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

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

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

  return (
    <div>
      <div>
        <form>
          <ShippingAddressElement />
        </form>
      </div>
      <div>
        <h2>Checkout Summary</h2>
        {checkoutState.type === 'success' && (
          <>
            <pre>
              {JSON.stringify(checkoutState.checkout.lineItems, null, 2)}
            </pre>
            <h3>Totals</h3>
            <pre>
              Subtotal: {checkoutState.checkout.total.subtotal.amount}
              Shipping: {checkoutState.checkout.total.shippingRate.amount}
              Total: {checkoutState.checkout.total.total.amount}
            </pre>
          </>
        )}
      </div>
    </div>
  )
};
```

### Sincronizar endereços de faturamento e entrega

Ao usar o Billing Address Element e Shipping Address Element, você pode exibir uma caixa de seleção que permite aos clientes sincronizar os endereços de cobrança e entrega.

#### HTML + JS

Passe a opção [syncAddressCheckbox](https://docs.stripe.com/js/custom_checkout/init#custom_checkout_init-options-elementsOptions-syncAddressCheckbox) em `elementsOptions` ao inicializar o Checkout para configurar qual Address Element exibe a caixa de seleção.

```javascript
const checkout = stripe.initCheckoutElementsSdk({
  clientSecret,
  elementsOptions: {
    syncAddressCheckbox: 'shipping',
  },
});
```

#### React

Passe a opção [syncAddressCheckbox](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider#react_checkout_provider-options-elementsOptions-syncAddressCheckbox) em `elementsOptions` para o `CheckoutElementsProvider` para configurar qual Address Element mostra a caixa de seleção.

```jsx
<CheckoutElementsProvider
  stripe={stripePromise}
  options={{
    fetchClientSecret: () => promise,
    elementsOptions: {
      syncAddressCheckbox: 'shipping',
    },
  }}
>
  <CheckoutForm />
</CheckoutElementsProvider>
```

Defina o valor como `'billing'` ou `'shipping'` para escolher qual Address Element exibe a caixa de seleção. Defina como `'none'` para ocultar a caixa de seleção, ou deixe em branco para usar o valor padrão (`'billing'`).

### Usar um formulário personalizado

Você pode criar seu próprio formulário para coletar endereços de entrega.

- Se sua página de checkout tiver uma etapa distinta de coleta de endereço antes da confirmação, chame [updateShippingAddress](https://docs.stripe.com/js/react_stripe_js/checkout/update_shipping_address) quando seu cliente enviar o endereço.
- Caso contrário, você pode enviar o endereço quando o cliente clicar no botão “Pagar”, passando [shippingAddress](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-shippingAddress) para [confirm](https://docs.stripe.com/js/custom_checkout/confirm).

## Optional: Separar autorização e captura [Lado do servidor]

A Stripe é compatível com pagamento com cartão em dois passos, então você pode primeiro autorizar um cartão e depois captura os fundos posteriormente. Quando a Stripe autoriza um pagamento, o cartão emissor garante os fundos e bloqueia o valor do pagamento no cartão do cliente. Em seguida, você tem um certo tempo para capturar os fundos,[dependendo do cartão](https://docs.stripe.com/payments/place-a-hold-on-a-payment-method.md#auth-capture-limitations)). Se você não captura o pagamento antes do vencimento da autorização, o pagamento é cancelado e o emissor libera os fundos retidos.

Separar a autorização da captura é útil para quem precisa realizar outros procedimentos entre a confirmação de que o cliente pode pagar e a cobrança do pagamento. Por exemplo, se você estiver vendendo itens com estoque limitado, pode ser necessário confirmar que o item comprado pelo cliente usando o Checkout ainda está disponível antes de capturar o pagamento e concluir a compra. Faça isso usando o seguinte fluxo de trabalho:

1. Confirme se a Stripe autorizou a forma de pagamento do cliente.
1. Consulte seu sistema de gestão de inventário para saber se o item ainda está disponível.
1. Atualize seu sistema de gestão de inventário para indicar que o cliente comprou o item.
1. Capture o pagamento do cliente.
1. Informe ao cliente se a compra foi finalizada em sua página de confirmação.

Para indicar que você quer separar a autorização da captura, defina [payment_intent_data.capture_method](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_intent_data-capture_method) como `manual` quando criar a sessão do Checkout. Isso instrui a Stripe a autorizar somente o valor no cartão do cliente.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=payment \
  -d "payment_intent_data[capture_method]=manual" \
  -d return_url={{RETURN_URL}} \
  -d ui_mode=elements
```

Para capturar um pagamento pendente, você pode usar o [Dashboard](https://dashboard.stripe.com/test/payments?status%5B%5D=uncaptured) ou o endpoint [capture](https://docs.stripe.com/api/payment_intents/capture.md). Para capturar automaticamente os pagamentos, é preciso ter acesso ao PaymentIntent criado durante a sessão do Checkout, que você pode obter pelo objeto [Session](https://docs.stripe.com/api/payment_intents/capture.md).

## Optional: Gerenciamento de contas de clientes [Sem código]

Permita que seus clientes [gerenciem](https://docs.stripe.com/customer-management.md) as próprias contas, compartilhando um link para o seu *portal do cliente* (The customer portal is a secure, Stripe-hosted page that lets your customers manage their subscriptions and billing details). O portal do cliente permite que os clientes façam login com o próprio e-mail para gerenciar assinaturas, atualizar formas de pagamento e muito mais.

## Optional: Execução de pedidos

Saiba como [receber uma notificação automaticamente](https://docs.stripe.com/checkout/fulfillment.md?payment-ui=embedded-components) quando um cliente paga.

## See also

- [Adicionar descontos a pagamentos avulsos](https://docs.stripe.com/payments/checkout/discounts.md?payment-ui=embedded-components)
- [Recolher impostos](https://docs.stripe.com/payments/checkout/taxes.md?payment-ui=embedded-components)
- [Ativar quantidades ajustáveis de item de linha](https://docs.stripe.com/payments/checkout/adjustable-quantity.md?payment-ui=embedded-components)
- [Adicionar botões de um clique](https://docs.stripe.com/elements/express-checkout-element/accept-a-payment.md?payment-ui=embedded-components)


# API Payment Intents

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

Crie um formulário de pagamento personalizado usando o [Stripe Elements](https://docs.stripe.com/payments/elements.md) e a [API Payment Intents](https://docs.stripe.com/api/payment_intents.md). Veja como essa integração [se compara aos outros tipos de integração](https://docs.stripe.com/payments/online-payments.md#compare-features-and-availability) da Stripe.

A API Payment Intents é uma API de nível inferior que você pode usar para criar seu próprio fluxo de checkout ou pagamentos, mas exige significativamente mais código e manutenção contínua. Recomendamos o [Payment Element com Checkout Sessions](https://docs.stripe.com/payments/quickstart-checkout-sessions.md) para a maioria das integrações porque abrange fluxos de pagamento semelhantes aos Payment Intents. Saiba mais sobre [quando usar Checkout Sessions em vez de Payment Intents](https://docs.stripe.com/payments/checkout-sessions-and-payment-intents-comparison.md).

O código do lado do cliente e do lado do servidor cria um formulário de checkout que aceita várias formas de pagamento.

#### Esforço de integração
Complexity: 4/5
#### Tipo de integração

Combine componentes de IU em um fluxo de pagamento personalizado

#### Personalização da IU

Personalização em nível de CSS com a [API Appearance](https://docs.stripe.com/elements/appearance-api.md)

> #### Você tem interesse em usar o Stripe Tax, descontos, envio ou conversão de moedas?
> 
> A Stripe tem uma integração do Payment Element que gerencia tributos, descontos, envio e conversão de moedas para você. Consulte [ criando uma página de checkout](https://docs.stripe.com/payments/quickstart-checkout-sessions.md) para saber mais.

## Configurar a Stripe [Lado do servidor]

Primeiro, [crie uma conta Stripe](https://dashboard.stripe.com/register) ou [entre](https://dashboard.stripe.com/login).

Use nossas bibliotecas oficiais para acessar a API da Stripe no seu aplicativo:

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

## Criar um PaymentIntent [Lado do servidor]

> Se quiser renderizar o Payment Element antes de criar um PaymentIntent, consulte [Coletar detalhes do pagamento antes de criar um Intent](https://docs.stripe.com/payments/accept-a-payment-deferred.md?type=payment).

O objeto [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) representa sua intenção de recolher o pagamento de um cliente e rastreia tentativas de cobrança e alterações de estado ao longo do processo de pagamento.
Uma visão geral resumida da integração de pagamentos descrita neste documento. (See full diagram at https://docs.stripe.com/payments/accept-a-payment)
### Criar o PaymentIntent

Crie um PaymentIntent no servidor com um [valor](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-amount) e uma [moeda](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-currency). Na versão mais recente da API, especificar o parâmetro `automatic_payment_methods` é opcional porque a Stripe habilita sua funcionalidade por padrão. Você pode gerenciar formas de pagamento no [Dashboard](https://dashboard.stripe.com/settings/payment_methods). A Stripe processa a devolução de formas de pagamento qualificadas com base em fatores como valor, moeda e fluxo de pagamento da transação.

A Stripe usa suas [formas de pagamento](https://dashboard.stripe.com/settings/payment_methods) para exibir as formas de pagamento habilitadas por você. Para ver como as formas de pagamento aparecem para os clientes, insira um ID de transação ou defina o valor e a moedas dos pedidos no [Dashboard](https://dashboard.stripe.com/settings/payment_methods/review). Para sobreposição de formas de pagamento, liste manualmente as que quiser ativar usando o atributo [payment_method_types](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-payment_method_types).

```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"
```

> Sempre decida o valor a ser cobrado no lado do servidor, um ambiente confiável, e não no lado do cliente. Isso evita que clientes mal-intencionados escolham os próprios preços.

### Recuperar o segredo do cliente

O PaymentIntent inclui um *segredo do cliente* (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)) que o lado do cliente usa para concluir com segurança o processo de pagamento. Você pode usar abordagens diferentes para enviar a senha do cliente ao lado do cliente.

#### Aplicativo de página única

Recupere o segredo do cliente de um endpoint do servidor usando a função `fetch` do navegador. Essa abordagem é melhor quando o lado do cliente é um aplicativo com uma única página, principalmente se criado com uma estrutura de front-end moderna como o React. Crie o endpoint do servidor que envia o segredo do cliente:

#### Ruby

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

Em seguida, obtenha o segredo do cliente com JavaScript no lado do cliente:

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

#### Renderização do lado do servidor

Passe o segredo do cliente do servidor ao cliente. Essa abordagem funciona melhor quando o aplicativo gera conteúdo estático no servidor antes de enviá-lo ao navegador.

Adicione o [client_secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) ao formulário de checkout. No código do lado do servidor, recupere o segredo do cliente do 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
```

## Coletar dados de pagamento [Lado do cliente]

Colete dados de pagamento no cliente com o [Payment Element](https://docs.stripe.com/payments/payment-element.md). O Payment Element é um componente de IU que simplifica a coleta de dados de pagamento para diversas formas de pagamento.

O Payment Element contém um iframe que envia dados de pagamento com segurança à Stripe por uma conexão HTTPS. Evite colocar o Payment Element dentro de outro iframe porque algumas formas de pagamento exigem o redirecionamento para outra página para confirmação do pagamento.

Se você optar por usar um iframe e quiser aceitar Apple Pay ou Google Pay, o iframe deve ter o atributo [permitir](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#attr-allowpaymentrequest) definido como igual a `"pagamento *"`.

O endereço da página de Checkout deve começar com `https://` rather em vez de `http://` for para que sua integração funcione corretamente. Você pode testar sua integração sem usar HTTPS, mas lembre-se de [habilitá-lo](https://docs.stripe.com/security/guide.md#tls) quando estiver pronto para aceitar pagamentos em tempo real.

#### HTML + JS

### Configurar o Stripe.js

O Payment Element está automaticamente disponível como um recurso do Stripe.js. Inclua o script Stripe.js em sua página de checkout adicionando-o ao `head` do arquivo HTML. Sempre carregue Stripe.js diretamente de js.stripe.com para manter a conformidade com PCI. Não inclua o script em um pacote nem hospede pessoalmente uma cópia dele.

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

Crie uma instância de Stripe com o seguinte JavaScript em sua página de checkout:

```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>>');
```

### Adicione o Element Pagamento à sua página de pagamentos

O Payment Element precisa de um lugar para residir na sua página de pagamentos. Crie um node DOM vazio (contêiner) com um ID único no seu formulário de pagamento:

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

Quando o formulário anterior for carregado, crie uma instância do Payment Element e monte-a no nó DOM do contêiner. Passe o [segredo do cliente](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) da etapa anterior em `options` quando criar a instância do [Elements](https://docs.stripe.com/js/elements_object/create):

Administre cuidadosamente o segredo do cliente, pois ele pode finalizar a cobrança. Não registre em log, incorpore em URLs nem exponha esse segredo a ninguém, exceto para o próprio cliente.

```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);

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

```

#### React

### Configurar o Stripe.js

Instale o [React Stripe.js](https://www.npmjs.com/package/@stripe/react-stripe-js) e o [carregador Stripe.js](https://www.npmjs.com/package/@stripe/stripe-js) do registro público npm:

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

### Adicione e configure o provedor do Elements à sua página de pagamento

Para usar o componente Payment Element, encapsule o componente da página de checkout em um [provedor do Elements](https://docs.stripe.com/sdks/stripejs-react.md#elements-provider). Chame `loadStripe` com sua chave publicável e passe a `Promise` retornada para o provedor `Elements`. Além disso, passe o [segredo do cliente](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) da etapa anterior como `options` ao fornecedor do `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'));
```

### Adicione o componente do Element Pagamento

Use o componente `PaymentElement` para criar seu formulário:

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

const CheckoutForm = () => {
  return (
    <form><PaymentElement />
      <button>Submit</button>
    </form>
  );
};

export default CheckoutForm;
```

O Stripe Elements é uma coleção de componentes drop-in de IU. Para personalizar ainda mais o formulário ou coletar outros dados do cliente, consulte a [documentação do Elements](https://docs.stripe.com/payments/elements.md).

O Payment Element renderiza um formulário dinâmico que permite ao cliente escolher uma forma de pagamento. Para cada forma de pagamento, o formulário solicita automaticamente que o cliente preencha todos os dados de pagamento necessários.

### Personalizar a aparência

Personalize o Payment Element para corresponder ao design do seu site, passando o [objeto appearance](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-appearance) para `options` ao criar o provedor do `Elements`.

### Solicitar endereços

Por padrão, o Payment Element só recolhe os detalhes necessários do endereço de faturamento. Alguns comportamentos, como [calcular impostos](https://docs.stripe.com/api/tax/calculations/create.md) ou inserir detalhes de entrega, exigem o endereço completo do cliente. Você pode:

- Use o [Address Element](https://docs.stripe.com/elements/address-element.md) para aproveitar os recursos de autocompletar e traduzir para recolher o endereço completo do cliente. Isso ajuda a garantir um cálculo tributário mais preciso.
- Obtenha os detalhes do endereço usando seu próprio formulário personalizado.

### Solicitar token de comerciante do Apple Pay

Se você configurou sua integração para [aceitar pagamentos com o Apple Pay](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=elements&api-integration=checkout), recomendamos configurar a interface do Apple Pay para retornar um token do comerciante, a fim de habilitar transações iniciadas pelo comerciante (MIT). [Solicite o tipo de token do comerciante pertinente](https://docs.stripe.com/apple-pay/merchant-tokens.md?pay-element=web-pe) no Payment Element.

## Optional: Salvar e recuperar formas de pagamento do cliente

Você pode configurar o Payment Element para salvar as formas de pagamento do seu cliente para uso futuro. Esta seção mostra como integrar o [recurso de formas de pagamento salvas](https://docs.stripe.com/payments/save-customer-payment-methods.md), que permite que o Payment Element:

- Solicitar consentimento dos compradores para salvar uma forma de pagamento
- Salvar formas de pagamento quando os compradores derem consentimento
- Exibir formas de pagamento salvas aos compradores para compras futuras
- [Atualize automaticamente cartões perdidos ou vencidos](https://docs.stripe.com/payments/cards/overview.md#automatic-card-updates) quando são substituídos pelos compradores
![O Payment Element e uma caixa de seleção forma de pagamento salva](https://b.stripecdn.com/docs-statics-srv/assets/spm-save.fe0b24afd0f0a06e0cf4eecb0ce2403a.png)

Salve formas de pagamento.
![O Payment Element com uma forma de pagamento salva selecionada](https://b.stripecdn.com/docs-statics-srv/assets/spm-saved.5dba5a8a190a9a0e9f1a99271bed3f4b.png)

Reutilize uma forma de pagamento salva anteriormente.

### Habilite o salvamento da forma de pagamento no Payment Element

Ao criar uma [PaymentIntent](https://docs.stripe.com/api/payment_intents/.md) no servidor, crie também uma [CustomerSession](https://docs.stripe.com/api/customer_sessions/.md) informando o [ID do cliente](https://docs.stripe.com/api/customers/object.md#customer_object-id) e habilitando o componente [payment_element](https://docs.stripe.com/api/customer_sessions/object.md#customer_session_object-components-payment_element) na sessão. Configure quais [recursos](https://docs.stripe.com/api/customer_sessions/create.md#create_customer_session-components-payment_element-features) de forma de pagamento salva você deseja habilitar. Por exemplo, habilitar [payment_method_save](https://docs.stripe.com/api/customer_sessions/create.md#create_customer_session-components-payment_element-features-payment_method_save) exibe uma caixa de seleção e permite que os clientes salvem os dados de pagamento para uso futuro.

Você pode especificar `setup_future_usage` em um PaymentIntent ou sessão do Checkout para substituir o comportamento padrão de salvar formas de pagamento. Isso garante que você salve automaticamente a forma de pagamento para uso futuro, mesmo que o cliente não opte por salvá-la explicitamente.

> Se você pretende especificar `setup_future_usage`, evite definir `payment_method_save_usage` na mesma transação de pagamento, pois isso causa um erro de integração.

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
Stripe.api_key = '<<YOUR_SECRET_KEY>>'

post '/create-intent-and-customer-session' do
  intent = Stripe::PaymentIntent.create({
    amount: 1099,
    currency: 'usd',
    # In the latest version of the API, specifying the `automatic_payment_methods` parameter
    # is optional because Stripe enables its functionality by default.
    automatic_payment_methods: {enabled: true},
    customer: {{CUSTOMER_ID}},
  })
  customer_session = Stripe::CustomerSession.create({
    customer: {{CUSTOMER_ID}},
    components: {
      payment_element: {
          enabled: true,
          features: {
            payment_method_redisplay: 'enabled',
            payment_method_save: 'enabled',
            payment_method_save_usage: 'off_session',
            payment_method_remove: 'enabled',
          },
        },
    },
  })
  {
    client_secret: intent.client_secret,
    customer_session_client_secret: customer_session.client_secret
  }.to_json
end
```

Sua instância do Elements usa o *segredo do cliente* (A client secret is used with your publishable key to authenticate a request for a single object. Each client secret is unique to the object it's associated with) da CustomerSession para acessar as formas de pagamento salvas desse cliente. [Gerencie erros](https://docs.stripe.com/error-handling.md) corretamente ao criar a CustomerSession. Se ocorrer um erro, você não precisará fornecer o segredo do cliente da CustomerSession para a instância do Elements, pois é opcional.

Crie a instância do Elements usando os segredos do cliente para PaymentIntent e CustomerSession. Em seguida, use essa instância do Elements para criar um Payment Element.

```javascript
// Create the CustomerSession and obtain its clientSecret
const res = await fetch("/create-intent-and-customer-session", {
  method: "POST"
});

const {
  customer_session_client_secret: customerSessionClientSecret
} = await res.json();

const elementsOptions = {
  clientSecret: '{{CLIENT_SECRET}}',customerSessionClientSecret,
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in checkout form, passing the client secret
// and CustomerSession's client secret obtained in a previous step
const elements = stripe.elements(elementsOptions);

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

> Se você permitir que os compradores removam formas de pagamento salvas habilitando [payment_method_remove](https://docs.stripe.com/api/customer_sessions/create.md#create_customer_session-components-payment_element-features-payment_method_remove), isso afetará as assinaturas que dependem dessa forma de pagamento. A remoção da forma de pagamento desvincula o [PaymentMethod](https://docs.stripe.com/api/payment_methods.md) desse [Cliente](https://docs.stripe.com/api/customers.md).

Quando você confirma o PaymentIntent, o Stripe.js controla automaticamente a definição de [setup_future_usage](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-setup_future_usage) no PaymentIntent e [allow_redisplay](https://docs.stripe.com/api/payment_methods/object.md#payment_method_object-allow_redisplay) no PaymentMethod, dependendo de o cliente ter marcado a caixa para salvar os dados de pagamento.

### Impor nova coleta de CVC

Opcionalmente, especifique `require_cvc_recollection` [ao criar o PaymentIntent](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-card-require_cvc_recollection) para impor coleta de CVC quando um cliente estiver pagando com cartão.

### Detectar a seleção de uma forma de pagamento salva

Para controlar o conteúdo dinâmico quando uma forma de pagamento salva é selecionada, ouça o evento `change` do Payment Element, que é preenchido com a forma de pagamento selecionada.

```javascript
paymentElement.on('change', function(event) {
  if (event.value.payment_method) {
    // Control dynamic content if a saved payment method is selected
  }
})
```

## Optional: Link na sua página de checkout [Lado do cliente]

Permita que seu cliente faça checkout mais rápido usando [Link](https://docs.stripe.com/payments/link.md) no [Payment Element](https://docs.stripe.com/payments/payment-element.md). Você pode preencher automaticamente os dados de qualquer cliente conectado que já usa Link, independentemente de ter salvado os dados inicialmente em Link com outra empresa. A integração padrão do Payment Element inclui uma solicitação Link no cartão. Para gerenciar Link no Payment Element, acesse as configurações da sua [forma de pagamento](https://dashboard.stripe.com/settings/payment_methods).
![Autentique ou inscreva-se no Link diretamente no Payment Element durante o checkout](https://b.stripecdn.com/docs-statics-srv/assets/link-in-pe.2efb5138a4708b781b8a913ebddd9aba.png)

Recolher um endereço de e-mail do cliente para autenticação ou inscrição no Link

### Opções de integração

Há duas formas de integrar o Link com o Payment Element. A Stripe recomenda passar um endereço de e-mail do cliente para o Payment Element, se disponível. Lembre-se de considerar o fluxo de checkout da sua compra ao escolher entre essas opções:

| Opção de integração                                                             | Fluxo de checkout                                                                                                                                                                                      | Descrição                                                                                                                                                                                                                                                                         |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Transfira um endereço de e-mail do cliente para o Payment Element (Recommended) | - Seu cliente insere o endereço de e-mail antes de chegar à página de checkout (em uma etapa anterior de criação de conta, por exemplo).
  - Você prefere usar seu próprio campo de entrada de e-mail. | Passe automaticamente um endereço de e-mail do cliente para o Payment Element. Nesse cenário, um cliente autentica-se no Link diretamente no formulário de pagamento, em vez de um componente de IU separado.                                                                     |
| Recolher um endereço de e-mail do cliente no Payment Element                    | - Seus clientes podem optar por inserir o e-mail e se autenticar ou se cadastrar com o Link diretamente no Payment Element durante o checkout.
  - Não é necessária nenhuma alteração no código.       | Se um cliente ainda não tiver se cadastrado no Link e escolher uma forma de pagamento compatível no Payment Element, ele será solicitado a salvar seus dados usando o Link. Para aqueles que já estão cadastrados, o Link preenche automaticamente suas informações de pagamento. |

Use [defaultValues](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-defaultValues) para transferir um endereço de e-mail de cliente para o Payment Element.

```javascript
const paymentElement = elements.create('payment', {
  defaultValues: {
    billingDetails: {
      email: 'foo@bar.com',
    }
  },
  // Other options
});
```

Para obter mais informações, leia como [criar uma página de checkout personalizada que inclua o Link](https://docs.stripe.com/payments/link/add-link-elements-integration.md).

## Optional: Obter atualizações do servidor [Lado do cliente]

Você pode atualizar atributos no PaymentIntent após a renderização do Payment Element, como o [valor](https://docs.stripe.com/api/payment_intents/update.md#update_payment_intent-amount) (por exemplo, códigos de desconto ou custos de envio). Você pode [atualizar o PaymentIntent](https://docs.stripe.com/api/payment_intents/update.md) no servidor e chamar [elements.fetchUpdates](https://docs.stripe.com/js/elements_object/fetch_updates) para ver o novo valor refletido no Payment Element. Este exemplo mostra como criar o endpoint do servidor que atualiza o valor na PaymentIntent:

#### Ruby

```ruby
get '/update' do
  intent = Stripe::PaymentIntent.update(
    '{{PAYMENT_INTENT_ID}}',
    {amount: 1499},
  )
  {status: intent.status}.to_json
end
```

Este exemplo demonstra como atualizar a IU para refletir as alterações no lado do cliente:

```javascript
(async () => {
  const response = await fetch('/update');
  if (response.status === 'requires_payment_method') {
    const {error} = await elements.fetchUpdates();
  }
})();
```

## Enviar o pagamento para a Stripe [Lado do cliente]

Use [stripe.confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment) para concluir o pagamento utilizando os detalhes do Payment Element. Forneça um [return_url](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-return_url) a essa função para indicar para onde a Stripe deve redirecionar o usuário após a conclusão do pagamento. Seu usuário pode ser redirecionado primeiro para um site intermediário, como uma página de autorização bancária, antes de ser redirecionado para o `return_url`. Os pagamentos com cartão são redirecionados imediatamente para o `return_url` quando um pagamento é finalizado.

Se não quiser redirecionar pagamentos com cartão após a conclusão do pagamento, defina [redirecionar](https://docs.stripe.com/js/payment_intents/confirm_payment#confirm_payment_intent-options-redirect) como `if_required`. Isso somente redireciona os clientes que fazem checkout com formas de pagamento baseadas em redirecionamento.

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

Para chamar [stripe.confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment) do seu componente de formulário de pagamento, use os hooks [useStripe](https://docs.stripe.com/sdks/stripejs-react.md#usestripe-hook) e [useElements](https://docs.stripe.com/sdks/stripejs-react.md#useelements-hook).

Se preferir componentes de classe tradicionais em vez de hooks, use um [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;
```

Verifique se o `return_url` corresponde a uma página no seu site que fornece o status do pagamento. Quando a Stripe redireciona o cliente para o `return_url`, nós fornecemos os seguintes parâmetros de consulta de URL:

| Parâmetro                      | Descrição                                                                                                                                    |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment_intent`               | O identificador único do `PaymentIntent`.                                                                                                    |
| `payment_intent_client_secret` | O [segredo do cliente](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) do objeto `PaymentIntent`. |

> Se você tiver ferramentas que rastreiam a sessão do cliente no navegador, pode ser necessário adicionar o domínio `stripe.com` à lista de exclusão de referenciadores. Os redirecionamentos fazem com que algumas ferramentas criem novas sessões, o que impede que você rastreie a sessão completa.

Use um dos parâmetros de consulta para recuperar o PaymentIntent. Inspecione o [status do PaymentIntent](https://docs.stripe.com/payments/paymentintents/lifecycle.md) para decidir o que mostrar aos clientes. Você também pode anexar seus próprios parâmetros de consulta ao fornecer o `return_url`, que persiste durante o processo de redirecionamento.

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

## Processar eventos pós-pagamento [Lado do servidor]

Stripe envia um evento [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) quando o pagamento é concluído. Use a [ferramenta Dashboard webhook](https://dashboard.stripe.com/webhooks) ou siga o [guia de webhooks](https://docs.stripe.com/webhooks/quickstart.md) para receber esses eventos e executar ações, como enviar um e-mail de confirmação do pedido ao cliente, registrar a venda em um banco de dados ou iniciar um fluxo de trabalho de envio.

Escute esses eventos em vez de aguardar um retorno de chamada do cliente. No cliente, o consumidor pode fechar a janela do navegador ou sair do aplicativo antes da execução do retorno de chamada, o que permite que clientes mal-intencionados manipulem a resposta. Configurar sua integração para escutar eventos assíncronos é o que permite a você aceitar [diferentes tipos de formas de pagamento](https://stripe.com/payments/payment-methods-guide) com uma única integração.

Além de gerenciar o evento `payment_intent.succeeded`, recomendamos gerenciar esses outros eventos ao coletar pagamentos com o Element Pagamento:

| Evento                                                                                                                          | Descrição                                                                                                                                                                                                                                                                     | Ação                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.succeeded)           | Enviado quando um cliente conclui um pagamento com êxito.                                                                                                                                                                                                                     | Envie ao cliente uma confirmação de pedido e *processe* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) o pedido. |
| [payment_intent.processing](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.processing)         | Enviado quando um cliente inicia um pagamento, mas o pagamento ainda precisa ser concluído. Esse evento costuma ser enviado quando um cliente inicia um débito bancário. Ele é seguido por um evento `payment_intent.succeeded` ou `payment_intent.payment_failed` no futuro. | Envie ao cliente uma confirmação do pedido que indica que o pagamento está pendente. Para produtos digitais, pode ser necessário executar o pedido antes de aguardar a conclusão do pagamento.  |
| [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.payment_failed) | Enviado quando um cliente tenta fazer um pagamento, mas o pagamento falha.                                                                                                                                                                                                    | Se um pagamento passa de `processing` para `payment_failed`, ofereça ao cliente outra tentativa para pagar.                                                                                     |

## Teste sua integração

Para testar sua integração de pagamentos personalizada:

1. Crie um Payment Intent e recupere o segredo do cliente.
1. Preencha os dados de pagamento com um método da tabela a seguir.
   - Informe uma data futura qualquer como validade do cartão.
   - Informe qualquer número de 3 dígitos como CVC.
   - Informe qualquer código postal de cobrança.
1. Envie o pagamento para a Stripe. Você será redirecionado para `return_url`.
1. Acesse o Dashboard e procure o pagamento na [página Transações](https://dashboard.stripe.com/test/payments?status%5B0%5D=successful). Se o seu pagamento for bem-sucedido, ele aparecerá na lista.
1. Clique no pagamento para ver mais detalhes, como dados de faturamento e a lista de itens comprados. Você pode usar esses dados para executar o pedido.

Saiba como [testar sua integração](https://docs.stripe.com/testing.md).

#### Cartões

| Número do cartão    | Cenário                                                                                                                                                                                                                                                                                             | Como testar                                                                                                                 |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| 4242424242424242    | O pagamento com cartão é bem-sucedido e não precisa de autenticação.                                                                                                                                                                                                                                | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000002500003155    | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000000000009995    | O cartão é recusado com um código de recusa como `insufficient_funds`.                                                                                                                                                                                                                              | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 6205500000000000004 | O cartão UnionPay tem um comprimento variável de 13 a 19 dígitos.                                                                                                                                                                                                                                   | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |

#### Carteiras

| Forma de pagamento | Cenário                                                                                                                                                                   | Como testar                                                                                                                                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alipay             | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação imediata](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento. |

#### Débito bancário autenticado

| Forma de pagamento                   | Cenário                                                                                                                                                                                                | Como testar                                                                                                                                                                                                |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático BECS               | O cliente paga com débito automático BECS.                                                                                                                                                             | Preencha o formulário usando o número de conta `900123456` e BSB `000000`. Inicialmente, o status do PaymentIntent muda para `processing` e, 3 minutos depois, para `succeeded`.                           |
| Débito automático BECS               | O pagamento do cliente falha com um código de erro `account_closed`.                                                                                                                                   | Preencha o formulário usando o número da conta `111111113` e BSB `000000`.                                                                                                                                 |
| Bancontact, EPS, iDEAL, e Przelewy24 | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação imediata.                                                         | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar pagamento de teste** na página de redirecionamento. |
| Pay by Bank                          | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification).                             | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento.                                |
| Pay by Bank                          | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação posterior.                                                        | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar o pagamento de teste** na página de redirecionamento.                                  |
| BLIK                                 | Os pagamentos BLIK falham de várias formas: falhas imediatas (por exemplo, o código está vencido ou inválido), erros atrasados (o banco recusa) ou limites de tempo (o cliente não respondeu a tempo). | Use padrões de e-mail para [simular as diferentes falhas.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures)                                                                    |

#### Débitos bancários

| Forma de pagamento     | Cenário                                                                                           | Como testar                                                                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático SEPA | O cliente paga com débito automático SEPA.                                                        | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processando e, três minutos depois, para bem-sucedido. |
| Débito automático SEPA | O status da intenção de pagamento do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`.                                                                                                          |

#### Boletos

| Forma de pagamento | Cenário                                          | Como testar                                                                                    |
| ------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| Boleto, OXXO       | Seu cliente paga com um boleto ou uma guia OXXO. | Selecione boleto ou OXXO como forma de pagamento e envie o pagamento. Feche o diálogo exibido. |

Consulte [Testes](https://docs.stripe.com/testing.md) para obter mais informações sobre como testar sua integração.

## Optional: Adicionar formas de pagamento

O Payment Element [aceita várias formas de pagamento](https://docs.stripe.com/payments/payment-methods/integration-options.md#choose-how-to-add-payment-methods) por padrão. Você precisa executar etapas adicionais e exibir algumas formas de pagamento.

### Affirm

Para começar a usar o Affirm, você deve habilitá-lo no [Dashboard](https://dashboard.stripe.com/settings/payment_methods). Quando você cria um PaymentIntent com a forma de pagamento Affirm, é preciso incluir um [endereço de entrega](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-shipping). Este exemplo sugere passar as informações de envio no cliente depois que ele [seleciona a forma de pagamento](https://docs.stripe.com/payments/accept-a-payment.md#web-create-intent). Saiba mais sobre como usar o [Affirm](https://docs.stripe.com/payments/affirm.md) com a Stripe.

#### 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://my-site.com/order/123/complete',shipping: {
        name: 'Jenny Rosen',
        address: {
          line1: '1 Street',
          city: 'Seattle',
          state: 'WA',
          postal_code: '95123',
          country: 'US'
        }
      },

    }
  });

  if (error) {
    // This point is reached if there's 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 is redirected to your `return_url`. For some payment
    // methods like iDEAL, your customer is redirected to an intermediate
    // site first to authorize the payment, then redirected to the `return_url`.
  }
});
```

#### React

```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://my-site.com/order/123/complete',shipping: {
          name: 'Jenny Rosen',
          address: {
            line1: '1 Street',
            city: 'Seattle',
            state: 'WA',
            postal_code: '95123',
            country: 'US'
          }
        },

      }
    });


    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;
```

#### Testar Affirm

Saiba como testar diferentes cenários usando a tabela a seguir:

| Cenário                                                                     | Como testar                                                                                    |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Seu cliente paga com o Affirm.                                              | Preencha o formulário (não deixe de incluir um endereço de entrega) e autentique o pagamento.  |
| Seu cliente não faz a autenticação na página de redirecionamento do Affirm. | Preencha o formulário e clique em **Falhar pagamento de teste** na página de redirecionamento. |

### Afterpay (Clearpay)

Quando você cria um PaymentIntent com a forma de pagamento Affirm, é necessário incluir um [endereço de entrega](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-shipping). Saiba mais sobre como usar o [Afterpay](https://docs.stripe.com/payments/afterpay-clearpay.md) com a Stripe.

Você pode gerenciar formas de pagamento no [Dashboard](https://dashboard.stripe.com/settings/payment_methods). A Stripe processa a devolução de formas de pagamento qualificadas com base em fatores como valor, moeda e fluxo de pagamento da transação. O exemplo abaixo usa o atributo [automatic_payment_methods](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-automatic_payment_methods-enabled), mas você pode listar `afterpay_clearpay` com [tipos de forma de pagamento](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_types). Na versão mais recente da API, especificar o parâmetro `automatic_payment_methods` é opcional porque a Stripe habilita sua funcionalidade por padrão. Qualquer que seja a opção escolhida, ative o Afterpay Clearpay no [Dashboard](https://dashboard.stripe.com/settings/payment_methods).

```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" \
  -d "shipping[name]=Jenny Rosen" \
  -d "shipping[address][line1]=1234 Main Street" \
  -d "shipping[address][city]=San Francisco" \
  -d "shipping[address][state]=CA" \
  -d "shipping[address][country]=US" \
  -d "shipping[address][postal_code]=94111"
```

#### Teste Afterpay (Clearpay)

Saiba como testar diferentes cenários usando a tabela a seguir:

| Cenário                                                                       | Como testar                                                                                    |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Seu cliente paga com o Afterpay.                                              | Preencha o formulário (não deixe de incluir um endereço de entrega) e autentique o pagamento.  |
| Seu cliente não faz a autenticação na página de redirecionamento do Afterpay. | Preencha o formulário e clique em **Falhar pagamento de teste** na página de redirecionamento. |

### Apple Pay e Google Pay

Quando você [habilita pagamentos com cartão](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=elements&api-integration=paymentintents#create-the-paymentintent), exibimos o Apple Pay e o Google Pay para clientes cujo ambiente atende às [condições de exibição da carteira](https://docs.stripe.com/testing/wallets.md). Para aceitar pagamentos com essas carteiras, você também deve:

- Habilitá-las nas [configurações de formas de pagamento](https://dashboard.stripe.com/settings/payment_methods). O Apple Pay é habilitado por padrão.
- Opere seu aplicativo por HTTPS em desenvolvimento e produção.
- [Registre seu domínio](https://docs.stripe.com/payments/payment-methods/pmd-registration.md).
- [Acessar atualizações do servidor](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=elements&api-integration=paymentintents#fetch-updates) se você atualizar o valor de um [PaymentIntent](https://docs.stripe.com/api/payment_intents.md), para manter o modal de pagamento da carteira sincronizado.

> #### Testes regionais
> 
> O Stripe Elements não aceita o Google Pay ou Apple Pay para contas e clientes da Stripe na Índia. Portanto, não é possível testar sua integração do Google Pay ou Apple Pay se o endereço IP do testador estiver na Índia, mesmo que a conta Stripe esteja localizada fora da Índia.

Saiba como usar [Apple Pay](https://docs.stripe.com/apple-pay.md) e [Google Pay](https://docs.stripe.com/google-pay.md) com a Stripe.

### Débito automático ACH

Para usar o Payment Element com a forma de pagamento Débito automático ACH, siga estas instruções:

1. Crie um [objeto Customer](https://docs.stripe.com/api/customers.md).

   ```curl
   curl -X POST https://api.stripe.com/v1/customers \
     -u "<<YOUR_SECRET_KEY>>:"
   ```

1. Especifique o ID do cliente ao criar o `PaymentIntent`.

   ```curl
   curl https://api.stripe.com/v1/payment_intents \
     -u "<<YOUR_SECRET_KEY>>:" \
     -d amount=1099 \
     -d currency=usd \
     -d setup_future_usage=off_session \
     -d customer={{CUSTOMER_ID}} \
     -d "payment_method_types[]=us_bank_account"
   ```

1. Selecione um [método de verificação](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-payment_method_options-us_bank_account-verification_method).

Ao usar a forma de pagamento débito automático ACH com o Payment Element, você só pode selecionar `automatic` ou `instant`.

Saiba mais sobre como usar o [débito automático ACH](https://docs.stripe.com/payments/ach-direct-debit.md) com a Stripe.

#### Testar débito automático ACH

| Cenário                                                                         | Como testar                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Seu cliente paga com uma conta bancária dos EUA usando verificação instantânea. | Selecione **Conta bancária dos EUA** e preencha o formulário. Clique na instituição de teste. Siga as instruções do modal para vincular sua conta bancária. Clique no botão do pagamento.                                                                                                                                                                                |
| Seu cliente paga com uma conta bancária dos EUA usando microdepósitos.          | Selecione **Conta bancária dos EUA** e preencha o formulário. Clique em **Inserir dados bancários manualmente**. Siga as instruções na janela para vincular sua conta bancária. Você pode usar estes [números de conta de teste](https://docs.stripe.com/payments/ach-direct-debit/accept-a-payment.md?platform=web#test-account-numbers). Clique no botão de pagamento. |
| Seu cliente não conclui o processo de vinculação de conta bancária.             | Selecione **Conta bancária dos EUA** e clique na instituição de teste ou em **Inserir os dados bancários manualmente**. Feche o modal sem preenchê-lo.                                                                                                                                                                                                                   |

### BLIK

Ao usar o Payment Element com BLIK, o usuário pode fechar o modal que solicita autorização para pagamento no aplicativo bancário. Isso aciona um redirecionamento para seu `return_url` e não retorna o usuário para a página de checkout. Saiba mais sobre como usar o [BLIK](https://docs.stripe.com/payments/blik.md) com a Stripe.

Para gerenciar os usuários fechando o modal, no gerenciador do lado do servidor do seu `return_url`, inspecione o `status` do Payment Intent para ver se ele é `succeeded` ou ainda `requires_action` (significando que o usuário fechou o modal sem autorização), lidando com cada caso conforme a necessidade.

### Formas de pagamento com código QR

Ao usar o Payment Element com uma forma de pagamento que usa código QR (WeChat Pay, PayNow, Pix, PromptPay ou Cash App Pay), o usuário pode fechar o modal de código QR. Isso aciona um redirecionamento para seu `return_url` e não retorna o usuário para a página de checkout.

Para gerenciar usuários que fecham os modais de código QR, no gerenciador no lado do servidor do seu `return_url`, inspecione o `status` do Payment Intent para ver se é `succeeded` ou se ainda é `requires_action` (significando que o usuário fechou o modal sem pagar), e trate cada caso conforme for necessário.

Como alternativa, evite o redirecionamento automático para o seu `return_url` passando o parâmetro opcional avançado [`redirect=if_required`](https://docs.stripe.com/js/payment_intents/confirm_payment#confirm_payment_intent-options-redirect), que evita o redirecionamento quando um modal de código QR é fechado.

### Cash App Pay

O Payment Element renderiza um formulário dinâmico de forma diferente na web para desktop ou para dispositivos móveis, pois usa diferentes métodos de autenticação do cliente. Saiba mais sobre como usar o [Cash App Pay](https://docs.stripe.com/payments/cash-app-pay.md) com a Stripe.

#### Elemento de aplicativo da web para dispositivos móveis

O Cash App Pay é uma forma de pagamento baseada em redirecionamento na web para dispositivos móveis. Ele redireciona seu cliente para o Cash App no modo de produção ou uma página de pagamento de teste em um ambiente de teste. Após a conclusão do pagamento, eles são redirecionados para o `return_url`, independentemente de você ter definido `redirect=if_required` ou não.

#### Elemento de aplicativo da web para desktop

Cash App Pay é uma forma de pagamento com QR code na web para desktop, em que o Payment Element renderiza um modal com QR code. Seu cliente precisa ler o QR code com um aplicativo de leitura de QR code ou o aplicativo móvel Cash App.

No modo de produção, ele redireciona o cliente para o `return_url` assim que for redirecionado para o Cash App. Em ambientes de teste, eles podem aprovar ou recusar o pagamento antes de serem redirecionados para o `return_url`. Os clientes também podem fechar o modal com código QR antes de concluir o pagamento, o que aciona um redirecionamento para o seu `return_url`.

Verifique se o `return_url` corresponde a uma página no seu site para inspecionar o `status` do Payment Intent. O `status` do Payment Intent pode ser `succeeded`, `failed` ou `requires_action` (por exemplo, o cliente fechou o modal sem ler o QR code).

Como alternativa, evite o redirecionamento automático para o seu `return_url` passando o parâmetro opcional avançado `redirect=if_required`, que evita o redirecionamento quando um modal de código QR é fechado.

### PayPal

Para usar o PayPal, verifique se você está em um [domínio registrado](https://docs.stripe.com/payments/payment-methods/pmd-registration.md).

## Divulgue a Stripe para seus clientes

A Stripe coleta informações sobre interações do cliente com o Elements para fornecer serviços a você, evitar fraudes e melhorar os serviços. Isso inclui o uso de cookies e endereços IP para identificar quais Elements o cliente visualizou durante uma única sessão de checkout. Você é responsável por divulgar e obter todos os direitos e consentimentos necessários para que a Stripe use os dados dessas maneiras. Para saber mais, acesse nossa [central de privacidade](https://stripe.com/legal/privacy-center#as-a-business-user-what-notice-do-i-provide-to-my-end-customers-about-stripe).

## See also

- [Stripe Elements](https://docs.stripe.com/payments/elements.md)
- [Configurar pagamentos futuros](https://docs.stripe.com/payments/save-and-reuse.md)
- [Salvar dados de pagamento durante o pagamento](https://docs.stripe.com/payments/save-during-payment.md)
- [Calcule imposto sobre vendas, GST e IVA em seu fluxo de pagamento](https://docs.stripe.com/tax/custom.md)


# Integração no aplicativo para iOS

> This is a Integração no aplicativo para iOS for when payment-ui is mobile and platform is ios. View the full page at https://docs.stripe.com/payments/accept-a-payment?payment-ui=mobile&platform=ios.
![](https://b.stripecdn.com/docs-statics-srv/assets/ios-overview.9e0d68d009dc005f73a6f5df69e00458.png)

Integre a IU de pagamento pré-criada da Stripe no checkout do seu aplicativo iOS com a classe [PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html). Veja nosso exemplo de integração [no GitHub](https://github.com/stripe/stripe-ios/tree/master/Example/PaymentSheet%20Example).

## Configurar a Stripe [Lado do servidor] [Lado do cliente]

Primeiro, você precisa de uma conta Stripe. [Inscreva-se aqui](https://dashboard.stripe.com/register).

### Lado do servidor

Esta integração exige que os endpoints do seu servidor se comuniquem com a API da Stripe. Use nossas bibliotecas oficiais para acessar a API da Stripe pelo seu servidor:

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

### Lado do cliente

O [SDK da Stripe para iOS](https://github.com/stripe/stripe-ios) é de código aberto, [totalmente documentado](https://stripe.dev/stripe-ios/index.html) e compatível com aplicativos que aceitam iOS 13 ou versões mais recentes.

#### Gerenciador de pacotes Swift

Para instalar o SDK, siga estas etapas:

1. No Xcode, selecione **Arquivo** > **Adicionar dependências de pacote…** e insira `https://github.com/stripe/stripe-ios-spm` como URL do repositório.
1. Selecione o número da última versão da nossa [página de lançamentos](https://github.com/stripe/stripe-ios/releases).
1. Adicione o produto **StripePaymentSheet** ao [alvo do seu aplicativo](https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app).

#### CocoaPods

1. Se ainda não o fez, instale a versão mais recente do [CocoaPods](https://guides.cocoapods.org/using/getting-started.html).
1. Se não tiver um [Podfile](https://guides.cocoapods.org/syntax/podfile.html), execute o seguinte comando para criar um:
   ```bash
   pod init
   ```
1. Adicione esta linha ao seu `Podfile`:
   ```podfile
   pod 'StripePaymentSheet'
   ```
1. Execute o seguinte comando:
   ```bash
   pod install
   ```
1. Não se esqueça de usar o arquivo `.xcworkspace` para abrir seu projeto em Xcode, em vez do arquivo `.xcodeproj`, daqui em diante.
1. No futuro, para atualizar para a versão mais recente do SDK, execute:
   ```bash
   pod update StripePaymentSheet
   ```

#### Carthage

1. Se ainda não o fez, instale a versão mais recente do [Carthage](https://github.com/Carthage/Carthage#installing-carthage).
1. Adicione esta linha ao seu `Cartfile`:
   ```cartfile
   github "stripe/stripe-ios"
   ```
1. Siga as [instruções de instalação do Carthage](https://github.com/Carthage/Carthage#if-youre-building-for-ios-tvos-or-watchos). Certifique-se de integrar todas as estruturas necessárias listadas [here](https://github.com/stripe/stripe-ios/tree/master/StripePaymentSheet/README.md#manual-linking).
1. No futuro, para atualizar para a versão mais recente do SDK, execute o seguinte comando:
   ```bash
   carthage update stripe-ios --platform ios
   ```

#### Estrutura manual

1. Vá até a nossa [página de lançamentos do GitHub](https://github.com/stripe/stripe-ios/releases/latest) e baixe e descompacte o **Stripe.xcframework.zip**.
1. Arraste **StripePaymentSheet.xcframework** até a seção **Embedded Binaries** das configurações **General** no seu projeto Xcode. Certifique-se de selecionar **Copy items if needed**.
1. Repita a etapa 2 para todas as estruturas necessárias listadas [here](https://github.com/stripe/stripe-ios/tree/master/StripePaymentSheet/README.md#manual-linking).
1. No futuro, para atualizar para a versão mais recente do nosso SDK, repita as etapas 1 a 3.

> Para obter mais informações sobre a versão mais recente e as versões anteriores do SDK, consulte a página [Lançamentos](https://github.com/stripe/stripe-ios/releases) no GitHub. Para receber notificações quando um novo lançamento for publicado, [assista aos lançamentos](https://help.github.com/en/articles/watching-and-unwatching-releases-for-a-repository#watching-releases-for-a-repository) do repositório.

## Ativar formas de pagamento

Veja suas [configurações de formas de pagamento](https://dashboard.stripe.com/settings/payment_methods) e habilite as formas de pagamento que deseja aceitar. Você precisa de pelo menos uma forma de pagamento habilitada para criar um *PaymentIntent* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods).

Por padrão, a Stripe habilita cartões e outras formas de pagamento predominantes que podem ajudar você a alcançar mais clientes, mas recomendamos ativar outras formas de pagamento que sejam relevantes para sua empresa e seus clientes. Consulte [Suporte a formas de pagamento](https://docs.stripe.com/payments/payment-methods/payment-method-support.md) para saber mais sobre os produtos e formas de pagamento aceitos, e nossa [página de preços](https://stripe.com/pricing/local-payment-methods) para ver as tarifas.

## Adicionar um endpoint [Lado do servidor]

> #### Nota
> 
> Para exibir o PaymentSheet antes de criar um PaymentIntent, consulte [Colete os dados de pagamento antes de criar um Intent](https://docs.stripe.com/payments/accept-a-payment-deferred.md?type=payment).

Se a sua plataforma Connect utiliza [Contas configuradas pelo cliente](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), utilize o nosso [guia](https://docs.stripe.com/connect/use-accounts-as-customers.md) para substituir as referências a `Cliente` e eventos no seu código pelas referências equivalentes da API Accounts v2.

Esta integração usa três objetos da API da Stripe:

1. [PaymentIntent](https://docs.stripe.com/api/payment_intents.md): A Stripe usa isso para representar sua intenção de coletar o pagamento de um cliente, acompanhando suas tentativas de cobrança e alterações no estado do pagamento durante todo o processo.

1. (Opcional) [Customer](https://docs.stripe.com/api/customers.md): Para configurar uma forma de pagamento para pagamentos futuros, vincule-a a um *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments). Crie um objeto Customer quando o cliente abrir uma conta na sua empresa. Se o cliente pagar como convidado, você pode criar o objeto Customer antes do pagamento e associá-lo à sua representação interna da conta do cliente, mais tarde.

1. (Opcional) [CustomerSession](https://docs.stripe.com/api/customer_sessions.md): Os dados do objeto Customer são confidenciais e não podem ser recuperados diretamente do aplicativo. Uma CustomerSession concede ao SDK acesso temporário com escopo definido ao cliente e fornece opções de configuração adicionais. Consulte uma lista completa de [opções de configuração](https://docs.stripe.com/api/customer_sessions/create.md#create_customer_session-components).

> Se você nunca salva cartões para um cliente e não permite que clientes retornando reutilizem cartões salvos, é possível omitir os objetos cliente e CustomerSession da sua integração.

Por motivos de segurança, o aplicativo não pode criar esses objetos. Para isso, adicione um endpoint ao servidor para:

1. Recuperar ou criar um Customer.
1. Cria uma [CustomerSession](https://docs.stripe.com/api/customer_sessions.md) para o cliente.
1. Cria um PaymentIntent com o [valor](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-amount), a [moeda](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-currency) e o [cliente](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer).
1. Retorna o *segredo do cliente* (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)) do Payment Intent, o `client_secret` da CustomerSession, o [id](https://docs.stripe.com/api/customers/object.md#customer_object-id) do Cliente e sua [chave publicável](https://dashboard.stripe.com/apikeys) para seu aplicativo.

As formas de pagamento mostradas aos clientes durante o processo de checkout também são incluídas no PaymentIntent. Você pode permitir que a Stripe obtenha as formas de pagamento das configurações do Dashboard ou listá-las manualmente. Independentemente da opção escolhida, saiba que a moeda passada no PaymentIntent filtra as formas de pagamento mostradas para o cliente. Por exemplo, se você passar EUR no `eur` e a OXXO estiver ativada no Dashboard, a OXXO não será exibida ao cliente porque a OXXO não aceita pagamentos em `eur`.

Se sua integração não exige uma opção baseada em código para oferecer formas de pagamento, a Stripe recomenda a opção automática. Isso ocorre porque a Stripe avalia a moeda, as restrições de forma de pagamento e outros parâmetros para determinar a lista de formas de pagamento aceitas. Priorizamos as formas de formas de pagamento que aumentam a conversão e que são mais relevantes para a moeda e a localização do cliente.

#### Gerenciar formas de pagamento no Dashboard

Você pode gerenciar formas de pagamento no [Dashboard](https://dashboard.stripe.com/settings/payment_methods). A Stripe processa a devolução de formas de pagamento qualificadas com base em fatores como valor, moeda e fluxo de pagamento da transação. O PaymentIntent é criado usando as formas de pagamento configuradas no Dashboard. Se não quiser usar o Dashboard ou se quiser especificar formas de pagamento manualmente, você pode listá-las usando o atributo `payment_method_types`.

#### curl

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

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

# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="eur" \
  # In the latest version of the API, specifying the `automatic_payment_methods` parameter
  # is optional because Stripe enables its functionality by default.
  -d "automatic_payment_methods[enabled]"=true \
```

#### Listar manualmente as formas de pagamento

#### curl

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

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

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

> A forma de pagamento precisa aceitar a moeda passada no PaymentIntent. Além disso, sua empresa precisa estar estabelecida em um dos países aceitos pela forma de pagamento. Consulte a página [Opções de integração de formas de pagamento](https://docs.stripe.com/payments/payment-methods/integration-options.md) para obter mais detalhes sobre o que é aceito.

## Coletar dados de pagamento [Lado do cliente]

Para exibir o Payment Element para dispositivos móveis na tela de checkout, não se esqueça de:

- Mostrar os produtos que o cliente está comprando e o valor total
- Usar o [Address Element](https://docs.stripe.com/elements/address-element.md?platform=ios) para coletar todos os dados de envio necessários do cliente
- Adicionar um botão de checkout para exibir a IU da Stripe

#### UIKit

Na tela checkout do aplicativo, busque o segredo do cliente PaymentIntent, o segredo do cliente CustomerSession, a ID do cliente e a chave publicável do endpoint que você criou na etapa anterior. Use`STPAPIClient.shared` para definir sua chave publicável e inicialize o[PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html).

#### iOS (Swift)

```swift
import UIKit@_spi(CustomerSessionBetaAccess) import StripePaymentSheet

class CheckoutViewController: UIViewController {
  @IBOutlet weak var checkoutButton: UIButton!
  var paymentSheet: PaymentSheet?
  let backendCheckoutUrl = URL(string: "Your backend endpoint/payment-sheet")! // Your backend endpoint

  override func viewDidLoad() {
    super.viewDidLoad()

    checkoutButton.addTarget(self, action: #selector(didTapCheckoutButton), for: .touchUpInside)
    checkoutButton.isEnabled = false

    // MARK: Fetch the PaymentIntent client secret, CustomerSession client secret, Customer ID, and publishable key
    var request = URLRequest(url: backendCheckoutUrl)
    request.httpMethod = "POST"
    let task = URLSession.shared.dataTask(with: request, completionHandler: { [weak self] (data, response, error) in
      guard let data = data,
            let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
            let customerId = json["customer"] as? String,
            let customerSessionClientSecret = json["customerSessionClientSecret"] as? String,
            let paymentIntentClientSecret = json["paymentIntent"] as? String,
            let publishableKey = json["publishableKey"] as? String,
            let self = self else {
        // Handle error
        return
      }
STPAPIClient.shared.publishableKey = publishableKey// MARK: Create a PaymentSheet instance
      var configuration = PaymentSheet.Configuration()
      configuration.merchantDisplayName = "Example, Inc."
      configuration.customer = .init(id: customerId, customerSessionClientSecret: customerSessionClientSecret)
      // Set `allowsDelayedPaymentMethods` to true if your business handles
      // delayed notification payment methods like US bank accounts.
      configuration.allowsDelayedPaymentMethods = true
      self.paymentSheet = PaymentSheet(paymentIntentClientSecret:paymentIntentClientSecret, configuration: configuration)

      DispatchQueue.main.async {
        self.checkoutButton.isEnabled = true
      }
    })
    task.resume()
  }

}
```

Quando o cliente toca no botão **Checkout**, invoque `present` para apresentar a PaymentSheet. Após o cliente concluir o pagamento, a descrição é descartada e o bloco de conclusão é invocado com [PaymentSheetResult](https://stripe.dev/stripe-ios/stripe-paymentsheet/Enums/PaymentSheetResult.html).

#### iOS (Swift)

```swift
@objc
func didTapCheckoutButton() {
  // MARK: Start the checkout process
  paymentSheet?.present(from: self) { paymentResult in
    // MARK: Handle the payment result
    switch paymentResult {
    case .completed:
      print("Your order is confirmed")
    case .canceled:
      print("Canceled!")
    case .failed(let error):
      print("Payment failed: \(error)")
    }
  }
}
```

#### SwiftUI

Crie um modelo `ObservableObject` para sua tela de checkout. Esse modelo publica uma [PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html) e um [PaymentSheetResult](https://stripe.dev/stripe-ios/stripe-paymentsheet/Enums/PaymentSheetResult.html).

```swift
import StripePaymentSheet
import SwiftUI

class CheckoutViewModel: ObservableObject {
  let backendCheckoutUrl = URL(string: "Your backend endpoint/payment-sheet")! // Your backend endpoint
  @Published var paymentSheet: PaymentSheet?
  @Published var paymentResult: PaymentSheetResult?
}
```

Busque a segredo do cliente PaymentIntent, o segredo do cliente CustomerSession, a ID do cliente e a chave publicável do endpoint que você criou na etapa anterior. Use`STPAPIClient.shared` para definir sua chave publicável e inicialize o[PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html).

```swift
@_spi(CustomerSessionBetaAccess) import StripePaymentSheet
import SwiftUI

class CheckoutViewModel: ObservableObject {
  let backendCheckoutUrl = URL(string: "Your backend endpoint/payment-sheet")! // Your backend endpoint
  @Published var paymentSheet: PaymentSheet?
  @Published var paymentResult: PaymentSheetResult?
func preparePaymentSheet() {
    // MARK: Fetch thePaymentIntent and Customer information from the backend
    var request = URLRequest(url: backendCheckoutUrl)
    request.httpMethod = "POST"
    let task = URLSession.shared.dataTask(with: request, completionHandler: { [weak self] (data, response, error) in
      guard let data = data,
            let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
            let customerId = json["customer"] as? String,
            let customerSessionClientSecret = json["customerSessionClientSecret"] as? String,
            letpaymentIntentClientSecret = json["paymentIntent"] as? String,
            let publishableKey = json["publishableKey"] as? String,
            let self = self else {
        // Handle error
        return
      }

      STPAPIClient.shared.publishableKey = publishableKey// MARK: Create a PaymentSheet instance
      var configuration = PaymentSheet.Configuration()
      configuration.merchantDisplayName = "Example, Inc."
      configuration.customer = .init(id: customerId, customerSessionClientSecret: customerSessionClientSecret)
      // Set `allowsDelayedPaymentMethods` to true if your business handles
      // delayed notification payment methods like US bank accounts.
      configuration.allowsDelayedPaymentMethods = true

      DispatchQueue.main.async {
        self.paymentSheet = PaymentSheet(paymentIntentClientSecret:paymentIntentClientSecret, configuration: configuration)
      }
    })
    task.resume()
  }
}
struct CheckoutView: View {
  @ObservedObject var model = CheckoutViewModel()

  var body: some View {
    VStack {
      if model.paymentSheet != nil {
        Text("Ready to pay.")
      } else {
        Text("Loading…")
      }
    }.onAppear { model.preparePaymentSheet() }
  }
}
```

Adicione um [PaymentSheet.PaymentButton](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/PaymentButton.html) à sua `View`. O comportamento é similar a um `Button` SwiftUI, que permite ser personalizado com a adição de uma `View`. Quando você clica no botão, o PaymentSheet é exibido. Depois que você conclui o pagamento, a Stripe descarta a PaymentSheet e chama o gerenciador `onCompletion` com um objeto [PaymentSheetResult](https://stripe.dev/stripe-ios/stripe-paymentsheet/Enums/PaymentSheetResult.html).

```swift
@_spi(CustomerSessionBetaAccess) import StripePaymentSheet
import SwiftUI

class CheckoutViewModel: ObservableObject {
  let backendCheckoutUrl = URL(string: "Your backend endpoint/payment-sheet")! // Your backend endpoint
  @Published var paymentSheet: PaymentSheet?
  @Published var paymentResult: PaymentSheetResult?

  func preparePaymentSheet() {
    // MARK: Fetch the PaymentIntent and Customer information from the backend
    var request = URLRequest(url: backendCheckoutUrl)
    request.httpMethod = "POST"
    let task = URLSession.shared.dataTask(with: request, completionHandler: { [weak self] (data, response, error) in
      guard let data = data,
            let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
            let customerId = json["customer"] as? String,
            let customerSessionClientSecret = json["customerSessionClientSecret"] as? String,
            let paymentIntentClientSecret = json["paymentIntent"] as? String,
            let publishableKey = json["publishableKey"] as? String,
            let self = self else {
        // Handle error
        return
      }

      STPAPIClient.shared.publishableKey = publishableKey
      // MARK: Create a PaymentSheet instance
      var configuration = PaymentSheet.Configuration()
      configuration.merchantDisplayName = "Example, Inc."
      configuration.customer = .init(id: customerId, customerSessionClientSecret: customerSessionClientSecret)
      // Set `allowsDelayedPaymentMethods` to true if your business can handle payment methods
      // that complete payment after a delay, like SEPA Debit and Sofort.
      configuration.allowsDelayedPaymentMethods = true

      DispatchQueue.main.async {
        self.paymentSheet = PaymentSheet(paymentIntentClientSecret: paymentIntentClientSecret, configuration: configuration)
      }
    })
    task.resume()
  }
func onPaymentCompletion(result: PaymentSheetResult) {
    self.paymentResult = result
  }
}

struct CheckoutView: View {
  @ObservedObject var model = CheckoutViewModel()

  var body: some View {
    VStack {if let paymentSheet = model.paymentSheet {
        PaymentSheet.PaymentButton(
          paymentSheet: paymentSheet,
          onCompletion: model.onPaymentCompletion
        ) {
          Text("Buy")
        }
      } else {
        Text("Loading…")
      }if let result = model.paymentResult {
        switch result {
        case .completed:
          Text("Payment complete")
        case .failed(let error):
          Text("Payment failed: \(error.localizedDescription)")
        case .canceled:
          Text("Payment canceled.")
        }
      }
    }.onAppear { model.preparePaymentSheet() }
  }
}
```

Se `PaymentSheetResult` for `.completed`, informe ao usuário (por exemplo, exibindo uma tela de confirmação de pedido).

Configurar `allowsDelayedPaymentMethods` como verdadeiro permite formas de pagamento de [notificação assíncrona](https://docs.stripe.com/payments/payment-methods.md#payment-notification) como contas bancárias dos EUA. Para essas formas de pagamento, o status final do pagamento não é conhecido quando o `PaymentSheet` é concluído, sendo efetivado ou não posteriormente. Se você aceitar esses tipos de formas de pagamento, informe o cliente que seu pedido está confirmado e somente processe o pedido (por exemplo, fazendo o envio do produto) quando o pagamento for bem-sucedido.

## Configurar um URL de retorno [Lado do cliente]

O cliente pode sair do seu aplicativo para autenticar (por exemplo, no Safari ou no aplicativo bancário). Para permitir que eles voltem ao seu aplicativo após a autenticação, [configure um esquema de URL personalizado](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) e configure seu aplicativo delegado para encaminhar o URL ao SDK. A Stripe não aceita [links universais](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content).

#### SceneDelegate

#### Swift

```swift
// This method handles opening custom URL schemes (for example, "your-app://stripe-redirect")
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else {
        return
    }
    let stripeHandled = StripeAPI.handleURLCallback(with: url)
    if (!stripeHandled) {
        // This was not a Stripe url – handle the URL normally as you would
    }
}

```

#### AppDelegate

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

#### SwiftUI

#### Swift

```swift

@main
struct MyApp: App {
  var body: some Scene {
    WindowGroup {
      Text("Hello, world!").onOpenURL { incomingURL in
          let stripeHandled = StripeAPI.handleURLCallback(with: incomingURL)
          if (!stripeHandled) {
            // This was not a Stripe url – handle the URL normally as you would
          }
        }
    }
  }
}
```

Além disso, defina o [returnURL](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:6Stripe12PaymentSheetC13ConfigurationV9returnURLSSSgvp) no seu objeto [PaymentSheet.Configuration](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html) para o URL do seu aplicativo.

```swift
var configuration = PaymentSheet.Configuration()
configuration.returnURL = "your-app://stripe-redirect"
```

## Processar eventos pós-pagamento [Lado do servidor]

Stripe envia um evento [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) quando o pagamento é concluído. Use a [ferramenta Dashboard webhook](https://dashboard.stripe.com/webhooks) ou siga o [guia de webhooks](https://docs.stripe.com/webhooks/quickstart.md) para receber esses eventos e executar ações, como enviar um e-mail de confirmação do pedido ao cliente, registrar a venda em um banco de dados ou iniciar um fluxo de trabalho de envio.

Escute esses eventos em vez de aguardar um retorno de chamada do cliente. No cliente, o consumidor pode fechar a janela do navegador ou sair do aplicativo antes da execução do retorno de chamada, o que permite que clientes mal-intencionados manipulem a resposta. Configurar sua integração para escutar eventos assíncronos é o que permite a você aceitar [diferentes tipos de formas de pagamento](https://stripe.com/payments/payment-methods-guide) com uma única integração.

Além de gerenciar o evento `payment_intent.succeeded`, recomendamos gerenciar esses outros eventos ao coletar pagamentos com o Element Pagamento:

| Evento                                                                                                                          | Descrição                                                                                                                                                                                                                                                                     | Ação                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.succeeded)           | Enviado quando um cliente conclui um pagamento com êxito.                                                                                                                                                                                                                     | Envie ao cliente uma confirmação de pedido e *processe* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) o pedido. |
| [payment_intent.processing](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.processing)         | Enviado quando um cliente inicia um pagamento, mas o pagamento ainda precisa ser concluído. Esse evento costuma ser enviado quando um cliente inicia um débito bancário. Ele é seguido por um evento `payment_intent.succeeded` ou `payment_intent.payment_failed` no futuro. | Envie ao cliente uma confirmação do pedido que indica que o pagamento está pendente. Para produtos digitais, pode ser necessário executar o pedido antes de aguardar a conclusão do pagamento.  |
| [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.payment_failed) | Enviado quando um cliente tenta fazer um pagamento, mas o pagamento falha.                                                                                                                                                                                                    | Se um pagamento passa de `processing` para `payment_failed`, ofereça ao cliente outra tentativa para pagar.                                                                                     |

## Testar a integração

#### Cartões

| Número do cartão    | Cenário                                                                                                                                                                                                                                                                                             | Como testar                                                                                                                 |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| 4242424242424242    | O pagamento com cartão é bem-sucedido e não precisa de autenticação.                                                                                                                                                                                                                                | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000002500003155    | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000000000009995    | O cartão é recusado com um código de recusa como `insufficient_funds`.                                                                                                                                                                                                                              | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 6205500000000000004 | O cartão UnionPay tem um comprimento variável de 13 a 19 dígitos.                                                                                                                                                                                                                                   | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |

#### Débito bancário autenticado

| Forma de pagamento | Cenário                                                                                                                                                                                                | Como testar                                                                                                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bancontact, iDEAL  | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação imediata.                                                         | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar pagamento de teste** na página de redirecionamento. |
| Pay by Bank        | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification).                             | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento.                                |
| Pay by Bank        | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação posterior.                                                        | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar o pagamento de teste** na página de redirecionamento.                                  |
| BLIK               | Os pagamentos BLIK falham de várias formas: falhas imediatas (por exemplo, o código está vencido ou inválido), erros atrasados (o banco recusa) ou limites de tempo (o cliente não respondeu a tempo). | Use padrões de e-mail para [simular as diferentes falhas.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures)                                                                    |

#### Débitos bancários

| Forma de pagamento     | Cenário                                                                                           | Como testar                                                                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático SEPA | O cliente paga com débito automático SEPA.                                                        | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processando e, três minutos depois, para bem-sucedido. |
| Débito automático SEPA | O status da intenção de pagamento do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`.                                                                                                          |

Consulte [Testes](https://docs.stripe.com/testing.md) para obter mais informações sobre como testar sua integração.

## Optional: Habilitar Link

Ative Link nas suas [configurações de Formas de Pagamento](https://dashboard.stripe.com/settings/payment_methods) para permitir que seus clientes salvem e reutilizem com segurança suas informações de pagamento usando o botão de checkout expresso com um clique do Link.

### Passe o e-mail do cliente para o Mobile Payment Element

Link autentica o cliente usando o endereço de e-mail. A Stripe recomenda preencher previamente o máximo de informações possível para otimizar o processo de checkout.

Para preencher o nome, o e-mail e o número de telefone do cliente, forneça os dados do cliente a`defaultBillingDetails` após inicializar `PaymentSheet.Configuration`.

```swift
var configuration = PaymentSheet.Configuration()
configuration.defaultBillingDetails.name = "Jenny Rosen"
configuration.defaultBillingDetails.email = "jenny.rosen@example.com"
configuration.defaultBillingDetails.phone = "888-888-8888"
```

## Optional: Habilitar Apple Pay

> Se sua tela de checkout tiver um **botão Apple Pay** exclusivo, siga o [guia do Apple Pay](https://docs.stripe.com/apple-pay.md#present-payment-sheet) e use `ApplePayContext` para receber pagamentos pelo botão Apple Pay. Você pode usar `PaymentSheet` para processar outros tipos de forma de pagamento.

### Solicitar um ID de comerciante da Apple

Obtenha um ID de comerciante da Apple [solicitando um novo identificador](https://developer.apple.com/account/resources/identifiers/add/merchant) no site de desenvolvedores da Apple.

Preencha o formulário com descrição e identificador. A descrição é para seu controle e pode ser modificada no futuro. A Stripe recomenda que você use o nome do aplicativo como identificador (por exemplo, `merchant.com.{{YOUR_APP_NAME}}`).

### Criar um certificado Apple Pay

Crie um certificado para criptografia de dados de pagamento pelo aplicativo.

Vá até [Configurações de certificado do iOS](https://dashboard.stripe.com/settings/ios_certificates) no Dashboard, clique em **Adicionar novo aplicativo** e siga o guia.

Baixe um arquivo de solicitação de assinatura de certificado (CSR) para obter um certificado seguro da Apple que permite usar o Apple Pay.

Um arquivo CSR deve ser usado para emitir exatamente um certificado. Se você trocar seu ID de comerciante da Apple, acesse as [Configurações de certificado do iOS](https://dashboard.stripe.com/settings/ios_certificates) no Dashboard para obter um novo CSR e certificado.

### Integrar com Xcode

Adicione as funções do Apple Pay ao aplicativo. No Xcode, abra as configurações do projeto, clique na guia **Signing & Capabilities** e adicione o recurso **Apple Pay**. Talvez seja necessário fazer login na sua conta de desenvolvedor. Selecione o ID de comerciante criado anteriormente e o aplicativo já pode aceitar Apple Pay.
![](https://b.stripecdn.com/docs-statics-srv/assets/xcode.a701d4c1922d19985e9c614a6f105bf1.png)

Habilitar o recurso Apple Pay no Xcode

### Adicionar Apple Pay

#### Pagamento avulso

Para adicionar Apple Pay à PaymentSheet, defina [applePay](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:6Stripe12PaymentSheetC13ConfigurationV8applePayAC05ApplefD0VSgvp) após inicializar `PaymentSheet.Configuration` com seu ID de comerciante Apple e o [código de país da sua empresa](https://dashboard.stripe.com/settings/account).

#### iOS (Swift)

```swift
var configuration = PaymentSheet.Configuration()
configuration.applePay = .init(
  merchantId: "merchant.com.your_app_name",
  merchantCountryCode: "US"
)
```

#### Pagamentos recorrentes

Para adicionar Apple Pay à PaymentSheet, defina [applePay](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:6Stripe12PaymentSheetC13ConfigurationV8applePayAC05ApplefD0VSgvp) após inicializar `PaymentSheet.Configuration` com seu ID de comerciante Apple e o [código de país da sua empresa](https://dashboard.stripe.com/settings/account).

De acordo com as [diretrizes da Apple](https://developer.apple.com/design/human-interface-guidelines/apple-pay#Supporting-subscriptions) para pagamentos recorrentes, você também precisará definir atributos adicionais no `PKPaymentRequest`. Adicione um gerenciador em [ApplePayConfiguration.paymentRequestHandlers](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/applepayconfiguration/handlers/paymentrequesthandler) para configurar [PKPaymentRequest.paymentSummaryItems](https://developer.apple.com/documentation/passkit/pkpaymentrequest/1619231-paymentsummaryitems) com o valor que você pretende cobrar (por exemplo, 9,95&nbsp;USD por mês).

Você também pode adotar [tokens de comerciante](https://developer.apple.com/apple-pay/merchant-tokens/) definindo as propriedades `recurringPaymentRequest` ou `automaticReloadPaymentRequest` no `PKPaymentRequest`.

Para saber mais sobre como usar pagamentos recorrentes com o Apple Pay, consulte a [documentação do PassKit da Apple](https://developer.apple.com/documentation/passkit/pkpaymentrequest).

#### iOS (Swift)

```swift
let customHandlers = PaymentSheet.ApplePayConfiguration.Handlers(
    paymentRequestHandler: { request in
        // PKRecurringPaymentSummaryItem is available on iOS 15 or later
        if #available(iOS 15.0, *) {
            let billing = PKRecurringPaymentSummaryItem(label: "My Subscription", amount: NSDecimalNumber(string: "59.99"))

            // Payment starts today
            billing.startDate = Date()

            // Payment ends in one year
            billing.endDate = Date().addingTimeInterval(60 * 60 * 24 * 365)

            // Pay once a month.
            billing.intervalUnit = .month
            billing.intervalCount = 1

            // recurringPaymentRequest is only available on iOS 16 or later
            if #available(iOS 16.0, *) {
                request.recurringPaymentRequest = PKRecurringPaymentRequest(paymentDescription: "Recurring",
                                                                            regularBilling: billing,
                                                                            managementURL: URL(string: "https://my-backend.example.com/customer-portal")!)
                request.recurringPaymentRequest?.billingAgreement = "You'll be billed $59.99 every month for the next 12 months. To cancel at any time, go to Account and click 'Cancel Membership.'"
            }
            request.paymentSummaryItems = [billing]
            request.currencyCode = "USD"
        } else {
            // On older iOS versions, set alternative summary items.
            request.paymentSummaryItems = [PKPaymentSummaryItem(label: "Monthly plan starting July 1, 2022", amount: NSDecimalNumber(string: "59.99"), type: .final)]
        }
        return request
    }
)
var configuration = PaymentSheet.Configuration()
configuration.applePay = .init(merchantId: "merchant.com.your_app_name",
                                merchantCountryCode: "US",
                                customHandlers: customHandlers)
```

### Rastreamento de pedidos

Para adicionar informações de [rastreamento de pedidos](https://developer.apple.com/design/human-interface-guidelines/technologies/wallet/designing-order-tracking) no iOS&nbsp;16 ou posterior, configure um [authorizationResultHandler](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/applepayconfiguration/handlers/authorizationresulthandler) em seu `PaymentSheet.ApplePayConfiguration.Handlers`. A Stripe invoca sua implementação após a conclusão do pagamento, mas antes que o iOS descarte a descrição Apple Pay.

Na sua implementação de `authorizationResultHandler`, obtenha os detalhes do pedido a partir do seu servidor para o pedido concluído. Adicione esses detalhes ao [PKPaymentAuthorizationResult](https://developer.apple.com/documentation/passkit/pkpaymentauthorizationresult) fornecido e retorne o resultado modificado.

Para saber mais sobre o rastreamento de pedidos, consulte a [documentação de pedidos da carteira da Apple](https://developer.apple.com/documentation/walletorders).

#### iOS (Swift)

```swift
let customHandlers = PaymentSheet.ApplePayConfiguration.Handlers(
    authorizationResultHandler: { result in
      do {
        // Fetch the order details from your service
        let myOrderDetails = try await MyAPIClient.shared.fetchOrderDetails(orderID: orderID)
        result.orderDetails = PKPaymentOrderDetails(
          orderTypeIdentifier: myOrderDetails.orderTypeIdentifier, // "com.myapp.order"
          orderIdentifier: myOrderDetails.orderIdentifier, // "ABC123-AAAA-1111"
          webServiceURL: myOrderDetails.webServiceURL, // "https://my-backend.example.com/apple-order-tracking-backend"
          authenticationToken: myOrderDetails.authenticationToken) // "abc123"
        // Return your modified PKPaymentAuthorizationResult
        return result
      } catch {
        return PKPaymentAuthorizationResult(status: .failure, errors: [error])
      }
    }
)
var configuration = PaymentSheet.Configuration()
configuration.applePay = .init(merchantId: "merchant.com.your_app_name",
                               merchantCountryCode: "US",
                               customHandlers: customHandlers)
```

## Habilitar leitura de cartões

Para habilitar o suporte à leitura de cartões no iOS, defina `NSCameraUsageDescription` (**Privacy - Camera Usage Description**) no `Info.plist` do seu aplicativo e informe um motivo para o acesso à câmera (por exemplo, “Para ler cartões”).

## Optional: Ativar pagamentos por ACH

Para ativar pagamentos por débito ACH, inclua `StripeFinancialConnections` como uma dependência do aplicativo.

O [SDK da Stripe para iOS](https://github.com/stripe/stripe-ios) é de código aberto, [totalmente documentado](https://stripe.dev/stripe-ios/index.html) e compatível com aplicativos que aceitam iOS 13 ou versões mais recentes.

#### Gerenciador de pacotes Swift

Para instalar o SDK, siga estas etapas:

1. No Xcode, selecione **Arquivo** > **Adicionar dependências de pacote…** e insira `https://github.com/stripe/stripe-ios-spm` como URL do repositório.
1. Selecione o número da última versão da nossa [página de lançamentos](https://github.com/stripe/stripe-ios/releases).
1. Adicione o produto **StripeFinancialConnections** ao [alvo do seu aplicativo](https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app).

#### CocoaPods

1. Se ainda não o fez, instale a versão mais recente do [CocoaPods](https://guides.cocoapods.org/using/getting-started.html).
1. Se não tiver um [Podfile](https://guides.cocoapods.org/syntax/podfile.html), execute o seguinte comando para criar um:
   ```bash
   pod init
   ```
1. Adicione esta linha ao seu `Podfile`:
   ```podfile
   pod 'StripeFinancialConnections'
   ```
1. Execute o seguinte comando:
   ```bash
   pod install
   ```
1. Não se esqueça de usar o arquivo `.xcworkspace` para abrir seu projeto em Xcode, em vez do arquivo `.xcodeproj`, daqui em diante.
1. No futuro, para atualizar para a versão mais recente do SDK, execute:
   ```bash
   pod update StripeFinancialConnections
   ```

#### Carthage

1. Se ainda não o fez, instale a versão mais recente do [Carthage](https://github.com/Carthage/Carthage#installing-carthage).
1. Adicione esta linha ao seu `Cartfile`:
   ```cartfile
   github "stripe/stripe-ios"
   ```
1. Siga as [instruções de instalação do Carthage](https://github.com/Carthage/Carthage#if-youre-building-for-ios-tvos-or-watchos). Certifique-se de integrar todas as estruturas necessárias listadas [here](https://github.com/stripe/stripe-ios/tree/master/StripeFinancialConnections/README.md#manual-linking).
1. No futuro, para atualizar para a versão mais recente do SDK, execute o seguinte comando:
   ```bash
   carthage update stripe-ios --platform ios
   ```

#### Estrutura manual

1. Vá até a nossa [página de lançamentos do GitHub](https://github.com/stripe/stripe-ios/releases/latest) e baixe e descompacte o **Stripe.xcframework.zip**.
1. Arraste **StripeFinancialConnections.xcframework** até a seção **Embedded Binaries** das configurações **General** no seu projeto Xcode. Certifique-se de selecionar **Copy items if needed**.
1. Repita a etapa 2 para todas as estruturas necessárias listadas [here](https://github.com/stripe/stripe-ios/tree/master/StripeFinancialConnections/README.md#manual-linking).
1. No futuro, para atualizar para a versão mais recente do nosso SDK, repita as etapas 1 a 3.

> Para obter mais informações sobre a versão mais recente e as versões anteriores do SDK, consulte a página [Lançamentos](https://github.com/stripe/stripe-ios/releases) no GitHub. Para receber notificações quando um novo lançamento for publicado, [assista aos lançamentos](https://help.github.com/en/articles/watching-and-unwatching-releases-for-a-repository#watching-releases-for-a-repository) do repositório.

## Optional: Personalizar a descrição

Toda personalização é configurada usando o objeto [PaymentSheet.Configuration](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html).

### Aparência

Personalize cores, fontes e assim por diante para combinar com a aparência do seu aplicativo usando a [API appearance](https://docs.stripe.com/elements/appearance-api/mobile.md?platform=ios).

### Layout da forma de pagamento

Configure o layout das formas de pagamento na planilha usando [paymentMethodLayout](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/configuration-swift.struct/paymentmethodlayout). Você pode exibi-los horizontalmente, verticalmente ou deixar a Stripe otimizar o layout automaticamente.
![](https://b.stripecdn.com/docs-statics-srv/assets/ios-mpe-payment-method-layouts.9d0513e2fcec5660378ba1824d952054.png)

#### Swift

```swift
var configuration = PaymentSheet.Configuration()
configuration.paymentMethodLayout = .automatic
```

### Coletar endereços de usuários

Colete endereços de entrega ou cobrança locais e internacionais de seus clientes usando o [Address Element](https://docs.stripe.com/elements/address-element.md?platform=ios).

### Nome de exibição do comerciante

Especifique o nome da empresa exibido para o cliente definindo [merchantDisplayName](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:18StripePaymentSheet0bC0C13ConfigurationV19merchantDisplayNameSSvp). Por padrão, esse é o nome do seu aplicativo.

#### Swift

```swift
var configuration = PaymentSheet.Configuration()
configuration.merchantDisplayName = "My app, Inc."
```

### Modo escuro

A `PaymentSheet` se adapta automaticamente às configurações de aparência do sistema do usuário (modos claro e escuro). Se o seu aplicativo não aceitar o modo escuro, defina [estilo](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:18StripePaymentSheet0bC0C13ConfigurationV5styleAC18UserInterfaceStyleOvp) como modo `alwaysLight` ou `alwaysDark`.

```swift
var configuration = PaymentSheet.Configuration()
configuration.style = .alwaysLight
```

## Optional: Gerenciar logout de usuário

`PaymentSheet` armazena algumas informações localmente para lembrar se um usuário utilizou Link dentro de um aplicativo. Para limpar o estado interno do `PaymentSheet`, chame o método `PaymentSheet.resetCustomer()` quando o usuário fizer logout.

```swift
import UIKit
import StripePaymentSheet

class MyViewController: UIViewController {

  @objc
  func didTapLogoutButton() {
    PaymentSheet.resetCustomer()
    // Other logout logic required by your app
  }

}
```

## Optional: Conclua o pagamento em sua IU

Você pode exibir o Payment Sheet apenas para coletar dados da forma de pagamento e depois chamar um método `confirm` para concluir o pagamento na IU do aplicativo. Isso é útil quando você tem um botão de compra personalizado ou precisa de mais etapas após a coleta dos dados do pagamento.
![](https://b.stripecdn.com/docs-statics-srv/assets/ios-multi-step.cd631ea4f1cd8cf3f39b6b9e1e92b6c5.png)

Conclua o pagamento na IU do aplicativo

#### UIKit

As etapas a seguir mostram como concluir o pagamento na IU do aplicativo. Veja nosso exemplo de integração no [GitHub](https://github.com/stripe/stripe-ios/blob/master/Example/PaymentSheet%20Example/PaymentSheet%20Example/ExampleCustomCheckoutViewController.swift).

1. Primeiro, inicialize [PaymentSheet.FlowController](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/flowcontroller) em vez de `PaymentSheet` e atualize a IU com sua propriedade `paymentOption`. Essa propriedade contém uma imagem e um rótulo que representam a forma de pagamento padrão selecionada inicialmente pelo cliente.

```swift
PaymentSheet.FlowController.create(paymentIntentClientSecret: paymentIntentClientSecret, configuration: configuration) { [weak self] result in
  switch result {
  case .failure(let error):
    print(error)
  case .success(let paymentSheetFlowController):
    self?.paymentSheetFlowController = paymentSheetFlowController
    // Update your UI using paymentSheetFlowController.paymentOption
  }
}
```

1. Em seguida, chame `presentPaymentOptions` para coletar os detalhes do pagamento. Quando terminar, atualize sua IU novamente com a propriedade `paymentOption`.

```swift
paymentSheetFlowController.presentPaymentOptions(from: self) {
  // Update your UI using paymentSheetFlowController.paymentOption
}
```

1. Por fim, chame `confirm`.

```swift
paymentSheetFlowController.confirm(from: self) { paymentResult in
  // MARK: Handle the payment result
  switch paymentResult {
  case .completed:
    print("Payment complete!")
  case .canceled:
    print("Canceled!")
  case .failed(let error):
    print(error)
  }
}
```

#### SwiftUI

As etapas a seguir mostram como concluir o pagamento na IU do aplicativo. Veja nosso exemplo de integração no [GitHub](https://github.com/stripe/stripe-ios/blob/master/Example/PaymentSheet%20Example/PaymentSheet%20Example/ExampleSwiftUICustomPaymentFlow.swift).

1. Primeiro, inicialize [PaymentSheet.FlowController](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/flowcontroller) em vez de `PaymentSheet`. A propriedade `paymentOption` contém uma imagem e um rótulo representando a forma de pagamento selecionada no momento pelo cliente, que você pode usar na sua IU.

```swift
PaymentSheet.FlowController.create(paymentIntentClientSecret: paymentIntentClientSecret, configuration: configuration) { [weak self] result in
  switch result {
  case .failure(let error):
    print(error)
  case .success(let paymentSheetFlowController):
    self?.paymentSheetFlowController = paymentSheetFlowController
    // Use the paymentSheetFlowController.paymentOption properties in your UI
    myPaymentMethodLabel = paymentSheetFlowController.paymentOption?.label ?? "Select a payment method"
    myPaymentMethodImage = paymentSheetFlowController.paymentOption?.image ?? UIImage(systemName: "square.and.pencil")!
  }
}
```

1. Use [PaymentSheet.FlowController.PaymentOptionsButton](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/flowcontroller/paymentoptionsbutton) para inserir o botão que apresenta a descrição da compra para coletar os dados de pagamento. Quando `PaymentSheet.FlowController` chama o argumento `onSheetDismissed`, o `paymentOption` da instância `PaymentSheet.FlowController` reflete a forma de pagamento selecionada.

```swift
PaymentSheet.FlowController.PaymentOptionsButton(
  paymentSheetFlowController: paymentSheetFlowController,
  onSheetDismissed: {
    myPaymentMethodLabel = paymentSheetFlowController.paymentOption?.label ?? "Select a payment method"
    myPaymentMethodImage = paymentSheetFlowController.paymentOption?.image ?? UIImage(systemName: "square.and.pencil")!
  },
  content: {
    /* An example button */
    HStack {
      Text(myPaymentMethodLabel)
      Image(uiImage: myPaymentMethodImage)
    }
  }
)
```

1. Use [PaymentSheet.FlowController.PaymentOptionsButton](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/flowcontroller/paymentoptionsbutton) para encapsular o botão que confirma o pagamento.

```swift
PaymentSheet.FlowController.ConfirmButton(
  paymentSheetFlowController: paymentSheetFlowController,
  onCompletion: { result in
    // MARK: Handle the payment result
    switch result {
    case .completed:
      print("Payment complete!")
    case .canceled:
      print("Canceled!")
    case .failed(let error):
      print(error)
    }
  },
  content: {
    /* An example button */
    Text("Pay")
  }
)
```

Configurar `allowsDelayedPaymentMethods` como verdadeiro permite formas de pagamento de [notificação assíncrona](https://docs.stripe.com/payments/payment-methods.md#payment-notification) como contas bancárias dos EUA. Para essas formas de pagamento, o status final do pagamento não é conhecido quando o `PaymentSheet` é concluído, sendo efetivado ou não posteriormente. Se você aceitar esses tipos de formas de pagamento, informe o cliente que seu pedido está confirmado e somente processe o pedido (por exemplo, fazendo o envio do produto) quando o pagamento for bem-sucedido.

## Optional: Ativar coleta de CVC na confirmação

As instruções a seguir para coletar novamente o CVC de um cartão salvo durante PaymentIntent confirmação presumem que sua integração inclua o seguinte:

- Criação de PaymentIntents antes de coletar dados de pagamento

### Atualizar os parâmetros da criação de Intent

Para coletar novamente o CVC ao confirmar o pagamento, inclua `require_cvc_recollection` durante a criação do PaymentIntent.

#### curl

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

# Create an Ephemeral Key for the Customer
curl https://api.stripe.com/v1/ephemeral_keys \
  -u <<YOUR_SECRET_KEY>>: \
  -H "Stripe-Version: 2026-03-25.dahlia" \
  -H "Stripe-Account: 2026-03-25.dahlia" \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \

# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="eur" \-d "payment_method_options[card][require_cvc_recollection]"=true \
  # In the latest version of the API, specifying the `automatic_payment_methods` parameter
  # is optional because Stripe enables its functionality by default.
  -d "automatic_payment_methods[enabled]"=true \
```


# Integração no aplicativo para Android

> This is a Integração no aplicativo para Android for when payment-ui is mobile and platform is android. View the full page at https://docs.stripe.com/payments/accept-a-payment?payment-ui=mobile&platform=android.
![](https://b.stripecdn.com/docs-statics-srv/assets/android-overview.471eaf89a760f5b6a757fd96b6bb9b60.png)

Integre a IU de pagamento incorporada da Stripe no checkout do seu aplicativo Android com a classe [PaymentSheet](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/index.html).

## Configurar a Stripe [Lado do servidor] [Lado do cliente]

Primeiro, você precisa de uma conta Stripe. [Inscreva-se aqui](https://dashboard.stripe.com/register).

### Lado do servidor

Esta integração exige que os endpoints do seu servidor se comuniquem com a API da Stripe. Use as bibliotecas oficiais para acessar a API da Stripe pelo seu servidor:

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

### Lado do cliente

O [SDK da Stripe para Android](https://github.com/stripe/stripe-android) é de código aberto e [totalmente documentado](https://stripe.dev/stripe-android/).

Para instalar o SDK, adicione `stripe-android` ao bloco `dependencies` do arquivo [app/build.gradle](https://developer.android.com/studio/build/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")
}
```

> Veja mais informações sobre o último lançamento de SDK e as versões anteriores na página [Lançamentos](https://github.com/stripe/stripe-android/releases) no GitHub. Para receber notificações quando um novo lançamento for publicado, [assista aos lançamentos do repositório](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository).

## Ativar formas de pagamento

Veja suas [configurações de formas de pagamento](https://dashboard.stripe.com/settings/payment_methods) e habilite as formas de pagamento que deseja aceitar. Você precisa de pelo menos uma forma de pagamento habilitada para criar um *PaymentIntent* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods).

Por padrão, a Stripe habilita cartões e outras formas de pagamento predominantes que podem ajudar você a alcançar mais clientes, mas recomendamos ativar outras formas de pagamento que sejam relevantes para sua empresa e seus clientes. Consulte [Suporte a formas de pagamento](https://docs.stripe.com/payments/payment-methods/payment-method-support.md) para saber mais sobre os produtos e formas de pagamento aceitos, e nossa [página de preços](https://stripe.com/pricing/local-payment-methods) para ver as tarifas.

## Adicionar um endpoint [Lado do servidor]

> #### Nota
> 
> Para exibir o PaymentSheet antes de criar um PaymentIntent, consulte [Colete os dados de pagamento antes de criar um Intent](https://docs.stripe.com/payments/accept-a-payment-deferred.md?type=payment).

Se a sua plataforma Connect utiliza [Contas configuradas pelo cliente](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), utilize o nosso [guia](https://docs.stripe.com/connect/use-accounts-as-customers.md) para substituir as referências a `Cliente` e eventos no seu código pelas referências equivalentes da API Accounts v2.

Esta integração usa três objetos da API da Stripe:

1. [PaymentIntent](https://docs.stripe.com/api/payment_intents.md): A Stripe usa isso para representar sua intenção de coletar o pagamento de um cliente, acompanhando suas tentativas de cobrança e alterações no estado do pagamento durante todo o processo.

1. (Opcional) [Customer](https://docs.stripe.com/api/customers.md): Para configurar uma forma de pagamento para pagamentos futuros, vincule-a a um *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments). Crie um objeto Customer quando o cliente abrir uma conta na sua empresa. Se o cliente pagar como convidado, você pode criar o objeto Customer antes do pagamento e associá-lo à sua representação interna da conta do cliente, mais tarde.

1. (Opcional) [CustomerSession](https://docs.stripe.com/api/customer_sessions.md): Os dados do objeto Customer são confidenciais e não podem ser recuperados diretamente do aplicativo. Uma CustomerSession concede ao SDK acesso temporário com escopo definido ao cliente e fornece opções de configuração adicionais. Consulte uma lista completa de [opções de configuração](https://docs.stripe.com/api/customer_sessions/create.md#create_customer_session-components).

> Se você nunca salva cartões para um cliente e não permite que clientes retornando reutilizem cartões salvos, é possível omitir os objetos cliente e CustomerSession da sua integração.

Por motivos de segurança, o aplicativo não pode criar esses objetos. Para isso, adicione um endpoint ao servidor para:

1. Recuperar ou criar um Customer.
1. Cria uma [CustomerSession](https://docs.stripe.com/api/customer_sessions.md) para o cliente.
1. Cria um PaymentIntent com o [valor](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-amount), a [moeda](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-currency) e o [cliente](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer).
1. Retorna o *segredo do cliente* (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)) do Payment Intent, o `client_secret` da CustomerSession, o [id](https://docs.stripe.com/api/customers/object.md#customer_object-id) do Cliente e sua [chave publicável](https://dashboard.stripe.com/apikeys) para seu aplicativo.

As formas de pagamento mostradas aos clientes durante o processo de checkout também são incluídas no PaymentIntent. Você pode permitir que a Stripe obtenha as formas de pagamento das configurações do Dashboard ou listá-las manualmente. Independentemente da opção escolhida, saiba que a moeda passada no PaymentIntent filtra as formas de pagamento mostradas para o cliente. Por exemplo, se você passar EUR no `eur` e a OXXO estiver ativada no Dashboard, a OXXO não será exibida ao cliente porque a OXXO não aceita pagamentos em `eur`.

Se sua integração não exige uma opção baseada em código para oferecer formas de pagamento, a Stripe recomenda a opção automática. Isso ocorre porque a Stripe avalia a moeda, as restrições de forma de pagamento e outros parâmetros para determinar a lista de formas de pagamento aceitas. Priorizamos as formas de formas de pagamento que aumentam a conversão e que são mais relevantes para a moeda e a localização do cliente.

#### Gerenciar formas de pagamento no Dashboard

Você pode gerenciar formas de pagamento no [Dashboard](https://dashboard.stripe.com/settings/payment_methods). A Stripe processa a devolução de formas de pagamento qualificadas com base em fatores como valor, moeda e fluxo de pagamento da transação. O PaymentIntent é criado usando as formas de pagamento configuradas no Dashboard. Se não quiser usar o Dashboard ou se quiser especificar formas de pagamento manualmente, você pode listá-las usando o atributo `payment_method_types`.

#### curl

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

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

# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="eur" \
  # In the latest version of the API, specifying the `automatic_payment_methods` parameter
  # is optional because Stripe enables its functionality by default.
  -d "automatic_payment_methods[enabled]"=true \
```

#### Listar manualmente as formas de pagamento

#### curl

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

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

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

> A forma de pagamento precisa aceitar a moeda passada no PaymentIntent. Além disso, sua empresa precisa estar estabelecida em um dos países aceitos pela forma de pagamento. Consulte a página [Opções de integração de formas de pagamento](https://docs.stripe.com/payments/payment-methods/integration-options.md) para obter mais detalhes sobre o que é aceito.

## Coletar dados de pagamento [Lado do cliente]

Antes de exibir o Element Pagamento para dispositivos móveis, a página de checkout deve:

- Mostrar os produtos sendo comprados e o valor total
- Colete todas as informações de envio necessárias usando o [Address Element](https://docs.stripe.com/elements/address-element.md?platform=android)
- Incluir um botão de checkout para apresentar a IU da Stripe

#### Jetpack Compose

[Inicializar](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-builder/index.html) uma instância de `PaymentSheet` dentro de `onCreate` da sua atividade de checkout, passando um método para gerenciar o resultado.

```kotlin
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import com.stripe.android.paymentsheet.PaymentSheet
import com.stripe.android.paymentsheet.PaymentSheetResult

@Composable
fun App() {
  val paymentSheet = remember { PaymentSheet.Builder(::onPaymentSheetResult) }.build()
}

private fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {
  // implemented in the next steps
}
```

Em seguida, busque o segredo do cliente de Intenção Payment, o segredo do cliente da Sessão do cliente, a ID do cliente e a chave publicável do endpoint que você criou na etapa anterior. Defina a chave publicável usando`PaymentConfiguration` e armazene os outros para uso quando apresentar o PaymentSheet.

```kotlin
import androidx.compose.runtime.Composable
import androidx.compose.runtime.rememberimport androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue
import androidx.compose.ui.platform.LocalContext
import com.stripe.android.PaymentConfiguration
import com.stripe.android.paymentsheet.PaymentSheet
import com.stripe.android.paymentsheet.PaymentSheetResult

@Composable
fun App() {
  val paymentSheet = remember { PaymentSheet.Builder(::onPaymentSheetResult) }.build()val context = LocalContext.current
  var customerConfig by remember { mutableStateOf<PaymentSheet.CustomerConfiguration?>(null) }
  varpaymentIntentClientSecret by remember { mutableStateOf<String?>(null) }

  LaunchedEffect(context) {
    // Make a request to your own server and retrieve payment configurations
    val networkResult = ...
    if (networkResult.isSuccess) {paymentIntentClientSecret = networkResult.paymentIntent
        customerConfig = PaymentSheet.CustomerConfiguration.createWithCustomerSession(
          id = networkResult.customer,
          clientSecret = networkResult.customerSessionClientSecret
        )PaymentConfiguration.init(context, networkResult.publishableKey)}
  }
}

private fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {
  // implemented in the next steps
}
```

Quando o cliente tocar no botão checkout, chame [presentWithPaymentIntent](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/index.html#1814490530%2FFunctions%2F2002900378) para apresentar a descrição da compra. Depois que o cliente conclui o pagamento, a descrição é descartada e o [PaymentSheetResultCallback](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result-callback/index.html) é chamado com um [PaymentSheetResult](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result/index.html).

```kotlin
import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.platform.LocalContext
import com.stripe.android.PaymentConfiguration
import com.stripe.android.paymentsheet.PaymentSheet
import com.stripe.android.paymentsheet.PaymentSheetResult

@Composable
fun App() {
  val paymentSheet = remember { PaymentSheet.Builder(::onPaymentSheetResult) }.build()
  val context = LocalContext.current
  var customerConfig by remember { mutableStateOf<PaymentSheet.CustomerConfiguration?>(null) }
  var paymentIntentClientSecret by remember { mutableStateOf<String?>(null) }

  LaunchedEffect(context) {
    // Make a request to your own server and retrieve payment configurations
    val networkResult = ...
    if (networkResult.isSuccess) {
        paymentIntentClientSecret = networkResult.paymentIntent
        customerConfig = PaymentSheet.CustomerConfiguration.createWithCustomerSession(
          id = networkResult.customer,
          clientSecret = networkResult.customerSessionClientSecret
        )
        PaymentConfiguration.init(context, networkResult.publishableKey)
    }
  }Button(
    onClick = {
      val currentConfig = customerConfig
      val currentClientSecret =paymentIntentClientSecret

      if (currentConfig != null && currentClientSecret != null) {
        presentPaymentSheet(paymentSheet, currentConfig, currentClientSecret)
      }
    }
  ) {
    Text("Checkout")
  }
}private fun presentPaymentSheet(
  paymentSheet: PaymentSheet,
  customerConfig: PaymentSheet.CustomerConfiguration,paymentIntentClientSecret: String
) {
  paymentSheet.presentWithPaymentIntent(paymentIntentClientSecret,
    PaymentSheet.Configuration.Builder(merchantDisplayName = "My merchant name")
      .customer(customerConfig)
      // Set `allowsDelayedPaymentMethods` to true if your business handles
      // delayed notification payment methods like US bank accounts.
      .allowsDelayedPaymentMethods(true)
      .build()
  )
}
private fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {when(paymentSheetResult) {
    is PaymentSheetResult.Canceled -> {
      print("Canceled")
    }
    is PaymentSheetResult.Failed -> {
      print("Error: ${paymentSheetResult.error}")
    }
    is PaymentSheetResult.Completed -> {
      // Display for example, an order confirmation screen
      print("Completed")
    }
  }
}
```

#### Visualizações (Clássico)

[Inicialize](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/index.html#-394860221%2FConstructors%2F2002900378) uma instância de `PaymentSheet` dentro de `onCreate` da sua atividade de checkout, passando um método para gerenciar o resultado.

#### Kotlin

```kotlin
import com.stripe.android.paymentsheet.PaymentSheet

class CheckoutActivity : AppCompatActivity() {
  lateinit var paymentSheet: PaymentSheet

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    paymentSheet = PaymentSheet.Builder(::onPaymentSheetResult).build(this)
  }

  fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {
    // implemented in the next steps
  }
}
```

Em seguida, busque o segredo do cliente de Intenção Payment, o segredo do cliente da Sessão do cliente, a ID do cliente e a chave publicável do endpoint que você criou na etapa anterior. Defina a chave publicável usando`PaymentConfiguration` e armazene os outros para uso quando apresentar o PaymentSheet.

#### Kotlin

```kotlin
import com.stripe.android.paymentsheet.PaymentSheet

class CheckoutActivity : AppCompatActivity() {
  lateinit var paymentSheet: PaymentSheetlateinit var customerConfig: PaymentSheet.CustomerConfiguration
  lateinit varpaymentIntentClientSecret: String

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    paymentSheet = PaymentSheet.Builder(::onPaymentSheetResult).build(this)lifecycleScope.launch {
      // Make a request to your own server and retrieve payment configurations
      val networkResult = MyBackend.getPaymentConfig()
      if (networkResult.isSuccess) {paymentIntentClientSecret = networkResult.paymentIntent
        customerConfig = PaymentSheet.CustomerConfiguration.createWithCustomerSession(
          id = networkResult.customer,
          clientSecret = networkResult.customerSessionClientSecret
        )PaymentConfiguration.init(context, networkResult.publishableKey)}
    }
  }

  fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {
    // implemented in the next steps
  }
}
```

Quando o cliente tocar no botão checkout, chame [presentWithPaymentIntent](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/index.html#1814490530%2FFunctions%2F2002900378) para apresentar a descrição da compra. Depois que o cliente conclui o pagamento, a descrição é descartada e o [PaymentSheetResultCallback](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result-callback/index.html) é chamado com um [PaymentSheetResult](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result/index.html).

#### Kotlin

```kotlin
// ...
class CheckoutActivity : AppCompatActivity() {
  lateinit var paymentSheet: PaymentSheet
  lateinit var customerConfig: PaymentSheet.CustomerConfiguration
  lateinit var paymentIntentClientSecret: String
  // ...fun presentPaymentSheet() {
    paymentSheet.presentWithPaymentIntent(paymentIntentClientSecret,
      PaymentSheet.Configuration.Builder(merchantDisplayName = "My merchant name")
        .customer(customerConfig)
        // Set `allowsDelayedPaymentMethods` to true if your business handles
        // delayed notification payment methods like US bank accounts.
        .allowsDelayedPaymentMethods(true)
        .build()
    )
  }

  fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {when(paymentSheetResult) {
      is PaymentSheetResult.Canceled -> {
        print("Canceled")
      }
      is PaymentSheetResult.Failed -> {
        print("Error: ${paymentSheetResult.error}")
      }
      is PaymentSheetResult.Completed -> {
        // Display for example, an order confirmation screen
        print("Completed")
      }
    }
  }
}
```

Configurar `allowsDelayedPaymentMethods` como verdadeiro permite formas de pagamento de [notificação assíncrona](https://docs.stripe.com/payments/payment-methods.md#payment-notification) como contas bancárias dos EUA. Para essas formas de pagamento, o status final do pagamento não é conhecido quando o `PaymentSheet` é concluído, sendo efetivado ou não posteriormente. Se você aceitar esses tipos de formas de pagamento, informe o cliente que seu pedido está confirmado e somente processe o pedido (por exemplo, fazendo o envio do produto) quando o pagamento for bem-sucedido.

## Processar eventos pós-pagamento [Lado do servidor]

Stripe envia um evento [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) quando o pagamento é concluído. Use a [ferramenta Dashboard webhook](https://dashboard.stripe.com/webhooks) ou siga o [guia de webhooks](https://docs.stripe.com/webhooks/quickstart.md) para receber esses eventos e executar ações, como enviar um e-mail de confirmação do pedido ao cliente, registrar a venda em um banco de dados ou iniciar um fluxo de trabalho de envio.

Escute esses eventos em vez de aguardar um retorno de chamada do cliente. No cliente, o consumidor pode fechar a janela do navegador ou sair do aplicativo antes da execução do retorno de chamada, o que permite que clientes mal-intencionados manipulem a resposta. Configurar sua integração para escutar eventos assíncronos é o que permite a você aceitar [diferentes tipos de formas de pagamento](https://stripe.com/payments/payment-methods-guide) com uma única integração.

Além de gerenciar o evento `payment_intent.succeeded`, recomendamos gerenciar esses outros eventos ao coletar pagamentos com o Element Pagamento:

| Evento                                                                                                                          | Descrição                                                                                                                                                                                                                                                                     | Ação                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.succeeded)           | Enviado quando um cliente conclui um pagamento com êxito.                                                                                                                                                                                                                     | Envie ao cliente uma confirmação de pedido e *processe* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) o pedido. |
| [payment_intent.processing](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.processing)         | Enviado quando um cliente inicia um pagamento, mas o pagamento ainda precisa ser concluído. Esse evento costuma ser enviado quando um cliente inicia um débito bancário. Ele é seguido por um evento `payment_intent.succeeded` ou `payment_intent.payment_failed` no futuro. | Envie ao cliente uma confirmação do pedido que indica que o pagamento está pendente. Para produtos digitais, pode ser necessário executar o pedido antes de aguardar a conclusão do pagamento.  |
| [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.payment_failed) | Enviado quando um cliente tenta fazer um pagamento, mas o pagamento falha.                                                                                                                                                                                                    | Se um pagamento passa de `processing` para `payment_failed`, ofereça ao cliente outra tentativa para pagar.                                                                                     |

## Testar a integração

#### Cartões

| Número do cartão    | Cenário                                                                                                                                                                                                                                                                                             | Como testar                                                                                                                 |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| 4242424242424242    | O pagamento com cartão é bem-sucedido e não precisa de autenticação.                                                                                                                                                                                                                                | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000002500003155    | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000000000009995    | O cartão é recusado com um código de recusa como `insufficient_funds`.                                                                                                                                                                                                                              | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 6205500000000000004 | O cartão UnionPay tem um comprimento variável de 13 a 19 dígitos.                                                                                                                                                                                                                                   | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |

#### Débito bancário autenticado

| Forma de pagamento | Cenário                                                                                                                                                                                                | Como testar                                                                                                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bancontact, iDEAL  | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação imediata.                                                         | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar pagamento de teste** na página de redirecionamento. |
| Pay by Bank        | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification).                             | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento.                                |
| Pay by Bank        | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação posterior.                                                        | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar o pagamento de teste** na página de redirecionamento.                                  |
| BLIK               | Os pagamentos BLIK falham de várias formas: falhas imediatas (por exemplo, o código está vencido ou inválido), erros atrasados (o banco recusa) ou limites de tempo (o cliente não respondeu a tempo). | Use padrões de e-mail para [simular as diferentes falhas.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures)                                                                    |

#### Débitos bancários

| Forma de pagamento     | Cenário                                                                                           | Como testar                                                                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático SEPA | O cliente paga com débito automático SEPA.                                                        | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processando e, três minutos depois, para bem-sucedido. |
| Débito automático SEPA | O status da intenção de pagamento do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`.                                                                                                          |

Consulte [Testes](https://docs.stripe.com/testing.md) para obter mais informações sobre como testar sua integração.

## Optional: Habilitar Link

Ative Link nas suas [configurações de Formas de Pagamento](https://dashboard.stripe.com/settings/payment_methods) para permitir que seus clientes salvem e reutilizem com segurança suas informações de pagamento usando o botão de checkout expresso com um clique do Link.

### Passe o e-mail do cliente para o Mobile Payment Element

Link autentica o cliente usando o endereço de e-mail. A Stripe recomenda preencher previamente o máximo de informações possível para otimizar o processo de checkout.

Para preencher o nome, o endereço de e-mail e o número de telefone do cliente, forneça os dados do cliente a `defaultBillingDetails` ao inicializar `PaymentSheet.Configuration`.

#### Kotlin

```kotlin
val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "Example, Inc.")
  .defaultBillingDetails(
    PaymentSheet.BillingDetails(
        name = "Jenny Rosen",
        email = "jenny.rosen@example.com",
        phone = "888-888-8888"
    )
  )
  .build()
```

## Optional: Habilitar Google Pay

### Configurar a integração

Para usar o Google Pay, habilite a API Google Pay adicionando o seguinte à `<application>` tag do seu **AndroidManifest.xml**:

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

Veja mais detalhes na [Configuração da API Google Pay](https://developers.google.com/pay/api/android/guides/setup) do Google Pay para Android.

### Adicionar Google Pay

Para adicionar o Google Pay à sua integração, passe uma [PaymentSheet.GooglePayConfiguration](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-google-pay-configuration/index.html) com seu ambiente do Google Pay (produção ou teste) e o [código do país da sua empresa](https://dashboard.stripe.com/settings/account) quando inicializar [PaymentSheet.Configuration](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/index.html).

#### Kotlin

```kotlin
val googlePayConfiguration = PaymentSheet.GooglePayConfiguration(
  environment = PaymentSheet.GooglePayConfiguration.Environment.Test,
  countryCode = "US",
  currencyCode = "USD" // Required for Setup Intents, optional for Payment Intents
)
val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "My merchant name")
  .googlePay(googlePayConfiguration)
  .build()
```

### Testar Google Pay

O Google permite que você faça pagamentos de teste por meio de seu [Pacote de cartão de teste](https://developers.google.com/pay/api/android/guides/resources/test-card-suite). O Pacote de cartão de teste é compatível com os [cartões de teste](https://docs.stripe.com/testing.md) da Stripe.

Você precisa testar o Google Pay usando um dispositivo Android físico em vez de um dispositivo simulado, em um país onde o Google Pay é compatível. Faça login em uma conta do Google em seu dispositivo de teste com um cartão real salvo na Carteira do Google.

## Optional: Habilitar leitura de cartões

To enable card scanning support, [request production access](https://developers.google.com/pay/api/android/guides/test-and-deploy/request-prod-access) to the Google Pay API from the [Google Pay and Wallet Console](https://pay.google.com/business/console?utm_source=devsite&utm_medium=devsite&utm_campaign=devsite).

- Se você ativou o Google Pay, o recurso de escaneamento de cartões está automaticamente disponível em nossa IU em dispositivos elegíveis. Para saber mais sobre dispositivos elegíveis, consulte as [restrições da API do Google Pay](https://developers.google.com/pay/payment-card-recognition/debit-credit-card-recognition)
- **Importante:** O recurso de escanear cartão só aparece em builds assinadas com a mesma chave de assinatura registrada no [Google Pay & Wallet Console](https://pay.google.com/business/console). Builds de teste ou debug usando chaves de assinatura diferentes (por exemplo, builds distribuídas pelo Firebase App Tester) não mostrarão a opção **Escanear cartão**. Para testar o escaneamento de cartão em versões pré-lançamento, você deve:
  - Assinar suas builds de teste com a chave de assinatura de produção
  - Adicionar sua impressão digital da chave de assinatura de teste ao Google Pay e Wallet Console

## Optional: Ativar pagamentos por ACH

Para habilitar ACH pagamentos por débito, inclua Financial Connections como uma dependência do seu aplicativo.

O [SDK da Stripe para Android](https://github.com/stripe/stripe-android) é de código aberto e [totalmente documentado](https://stripe.dev/stripe-android/).

Para instalar o SDK, adicione `financial-connections` ao bloco `dependencies` do arquivo [app/build.gradle](https://developer.android.com/studio/build/dependencies):

#### Kotlin

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

android { ... }

dependencies {
  // ...

  // Financial Connections Android SDK
  implementation("com.stripe:financial-connections:23.2.0")
}
```

> Veja mais informações sobre o último lançamento de SDK e as versões anteriores na página [Lançamentos](https://github.com/stripe/stripe-android/releases) no GitHub. Para receber notificações quando um novo lançamento for publicado, [assista aos lançamentos do repositório](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository).

## Optional: Personalizar a descrição

Toda personalização é configurada usando o objeto [PaymentSheet.Configuration](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/index.html).

### Aparência

Personalize cores, fontes e assim por diante para combinar com a aparência do seu aplicativo usando a [API appearance](https://docs.stripe.com/elements/appearance-api/mobile.md?platform=android).

### Layout da forma de pagamento

Configure o layout das formas de pagamento na planilha usando [paymentMethodLayout](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/-builder/index.html#2123253356%2FFunctions%2F2002900378). Você pode exibi-los horizontalmente, verticalmente ou deixar a Stripe otimizar o layout automaticamente.
![](https://b.stripecdn.com/docs-statics-srv/assets/android-mpe-payment-method-layouts.3bcfe828ceaad1a94e0572a22d91733f.png)

#### Kotlin

```kotlin
PaymentSheet.Configuration.Builder("Example, Inc.")
  .paymentMethodLayout(PaymentSheet.PaymentMethodLayout.Automatic)
  .build()
```

### Coletar endereços de usuários

Colete endereços de entrega ou cobrança locais e internacionais de seus clientes usando o [Address Element](https://docs.stripe.com/elements/address-element.md?platform=android).

### Nome de exibição da empresa

Especifique o nome da empresa exibido para o cliente definindo [merchantDisplayName](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/index.html#-191101533%2FProperties%2F2002900378). Por padrão, esse é o nome do seu aplicativo.

#### Kotlin

```kotlin
PaymentSheet.Configuration.Builder(
  merchantDisplayName = "My app, Inc."
).build()
```

### Modo escuro

Por padrão, o `PaymentSheet` se adapta automaticamente às configurações de aparência do sistema do usuário (modo claro e escuro). É possível alterar isso configurando modo claro ou escuro no seu aplicativo:

#### Kotlin

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

## Optional: Gerenciar logout de usuário

`PaymentSheet` armazena algumas informações localmente para lembrar se um usuário utilizou Link dentro de um aplicativo. Para limpar o estado interno do `PaymentSheet`, chame o método `PaymentSheet.resetCustomer()` quando o usuário fizer logout.

#### Kotlin

```kotlin
class MyActivity: Activity {

  fun onLogoutButtonClicked() {
    PaymentSheet.resetCustomer(this)
    // Other logout logic required by your app
  }
}
```

## Optional: Conclua o pagamento em sua IU

Você pode exibir a Payment Sheet apenas para coletar dados da forma de pagamento e concluir o pagamento na IU do aplicativo. Isso é útil quando você tem um botão de compra personalizado ou precisa de mais etapas após a coleta dos dados do pagamento.
![](https://b.stripecdn.com/docs-statics-srv/assets/android-multi-step.84d8a0a44b1baa596bda491322b6d9fd.png)

> Um exemplo de integração está [disponível no nosso GitHub](https://github.com/stripe/stripe-android/blob/master/paymentsheet-example/src/main/java/com/stripe/android/paymentsheet/example/samples/ui/paymentsheet/custom_flow/CustomFlowActivity.kt).

1. Primeiro, inicialize [PaymentSheet.FlowController](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/index.html) em vez de `PaymentSheet` usando um dos métodos do [Builder](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/-builder/index.html).

#### Android (Kotlin)

```kotlin
class CheckoutActivity : AppCompatActivity() {
  private lateinit var flowController: PaymentSheet.FlowController

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

    val flowController = PaymentSheet.FlowController.Builder(
      resultCallback = ::onPaymentSheetResult,
      paymentOptionResultCallback = ::onPaymentOption,
    ).build(this)
  }
}
```

1. Em seguida, chame `configureWithPaymentIntent` com as chaves do objeto Stripe recuperadas do backend e atualize a IU no callback usando [getPaymentOption()](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/index.html#-2091462043%2FFunctions%2F2002900378). Isso contém uma imagem e um rótulo que representam a forma de pagamento selecionada atualmente pelo cliente.

#### Android (Kotlin)

```kotlin
flowController.configureWithPaymentIntent(
  paymentIntentClientSecret = paymentIntentClientSecret,
  configuration = PaymentSheet.Configuration.Builder("Example, Inc.")
    .customer(PaymentSheet.CustomerConfiguration(
      id = customerId,
      ephemeralKeySecret = ephemeralKeySecret
    ))
    .build()
) { isReady, error ->
  if (isReady) {
    // Update your UI using `flowController.getPaymentOption()`
  } else {
    // handle FlowController configuration failure
  }
}
```

1. Em seguida, chame [presentPaymentOptions](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/index.html#449924733%2FFunctions%2F2002900378) para coletar os detalhes do pagamento. Quando o cliente termina, a descrição da compra é descartada e chama o [paymentOptionCallback](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-option-callback/index.html) passado anteriormente em `create`. Implemente essa forma para atualizar a IU com o `paymentOption` retornado.

#### Android (Kotlin)

```kotlin
// ...
  flowController.presentPaymentOptions()
// ...
  private fun onPaymentOption(paymentOptionResult: PaymentOptionResult) {
    val paymentOption = paymentOptionResult.paymentOption
    if (paymentOption != null) {
      paymentMethodButton.text = paymentOption.label
      paymentMethodButton.setCompoundDrawablesRelativeWithIntrinsicBounds(
        paymentOption.drawableResourceId,
        0,
        0,
        0
      )
    } else {
      paymentMethodButton.text = "Select"
      paymentMethodButton.setCompoundDrawablesRelativeWithIntrinsicBounds(
        null,
        null,
        null,
        null
      )
    }
  }
```

1. Por fim, chame [confirm](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/index.html#-479056656%2FFunctions%2F2002900378) para finalizar o pagamento. Quando o cliente termina, a descrição da compra é descartada e chama o [paymentResultCallback](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result-callback/index.html#237248767%2FFunctions%2F2002900378) passado anteriormente em `create`.

#### Android (Kotlin)

```kotlin
  // ...
    flowController.confirmPayment()
  // ...

  private fun onPaymentSheetResult(
    paymentSheetResult: PaymentSheetResult
  ) {
    when (paymentSheetResult) {
      is PaymentSheetResult.Canceled -> {
        // Payment canceled
      }
      is PaymentSheetResult.Failed -> {
        // Payment Failed. See logcat for details or inspect paymentSheetResult.error
      }
      is PaymentSheetResult.Completed -> {
        // Payment Complete
      }
    }
  }
```

Configurar `allowsDelayedPaymentMethods` como verdadeiro permite formas de pagamento de [notificação assíncrona](https://docs.stripe.com/payments/payment-methods.md#payment-notification) como contas bancárias dos EUA. Para essas formas de pagamento, o status final do pagamento não é conhecido quando o `PaymentSheet` é concluído, sendo efetivado ou não posteriormente. Se você aceitar esses tipos de formas de pagamento, informe o cliente que seu pedido está confirmado e somente processe o pedido (por exemplo, fazendo o envio do produto) quando o pagamento for bem-sucedido.

## Optional: Ativar coleta de CVC na confirmação

As instruções a seguir para coletar novamente o CVC de um cartão salvo durante a confirmação do PaymentIntent presumem que sua integração inclua o seguinte:

- Criação de PaymentIntents antes de coletar dados de pagamento

### Atualizar os parâmetros da criação de Intent

Para coletar novamente o CVC ao confirmar o pagamento, inclua `require_cvc_recollection` durante a criação do PaymentIntent.

#### curl

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

# Create an Ephemeral Key for the Customer
curl https://api.stripe.com/v1/ephemeral_keys \
  -u <<YOUR_SECRET_KEY>>: \
  -H "Stripe-Version: 2026-03-25.dahlia" \
  -H "Stripe-Account: 2026-03-25.dahlia" \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \

# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="eur" \-d "payment_method_options[card][require_cvc_recollection]"=true \
  # In the latest version of the API, specifying the `automatic_payment_methods` parameter
  # is optional because Stripe enables its functionality by default.
  -d "automatic_payment_methods[enabled]"=true \
```


# Integração no aplicativo para o React Native

> This is a Integração no aplicativo para o React Native for when payment-ui is mobile and platform is react-native. View the full page at https://docs.stripe.com/payments/accept-a-payment?payment-ui=mobile&platform=react-native.
![](https://b.stripecdn.com/docs-statics-srv/assets/ios-overview.9e0d68d009dc005f73a6f5df69e00458.png)

Essa integração combina todas as etapas exigidas para pagar, incluindo coletar dados de pagamento e confirmar o pagamento, em uma única folha que é exibida na parte superior do seu aplicativo.

## Configurar a Stripe [Lado do servidor] [Lado do cliente]

Primeiro, você precisa de uma conta Stripe. [Inscreva-se aqui](https://dashboard.stripe.com/register).

### Lado do servidor

Esta integração exige que os endpoints do seu servidor se comuniquem com a API da Stripe. Use as bibliotecas oficiais para acessar a API da Stripe pelo seu servidor:

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

### Lado do cliente

O [SDK do React Native](https://github.com/stripe/stripe-react-native) é de código aberto e totalmente documentado. Internamente, utiliza as SDKs de [iOS nativo](https://github.com/stripe/stripe-ios) e [Android](https://github.com/stripe/stripe-android). Para instalar o SDK do React Native da Stripe, execute um dos seguintes comandos no diretório do seu projeto (dependendo de qual gerenciador de pacotes você usa):

#### yarn

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

#### npm

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

Em seguida, instale algumas outras dependências necessárias:

- Para iOS, vá para o diretório **ios** e execute `pod install` para garantir a instalação das dependências nativas necessárias.
- Para Android, não há mais dependências para instalar.

> Recomendamos seguir o [guia oficial do TypeScript](https://reactnative.dev/docs/typescript#adding-typescript-to-an-existing-project) para adicionar suporte ao TypeScript.

### Inicialização da Stripe

Para inicializar a Stripe no aplicativo React Native, insira sua tela de pagamento com o componente `StripeProvider` ou use o método de inicialização `initStripe`. Somente a [chave da API publicável](https://docs.stripe.com/keys.md#obtain-api-keys) em `publishableKey` é necessária. O exemplo a seguir mostra como inicializar a Stripe usando o componente `StripeProvider`.

```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>
  );
}
```

> Use suas [chaves de API de teste](https://docs.stripe.com/keys.md#obtain-api-keys) enquanto testa e desenvolve, e as chaves de [modo de produção](https://docs.stripe.com/keys.md#test-live-modes) quando publica seu aplicativo.

## Ativar formas de pagamento

Veja suas [configurações de formas de pagamento](https://dashboard.stripe.com/settings/payment_methods) e habilite as formas de pagamento que deseja aceitar. Você precisa de pelo menos uma forma de pagamento habilitada para criar um *PaymentIntent* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods).

Por padrão, a Stripe habilita cartões e outras formas de pagamento predominantes que podem ajudar você a alcançar mais clientes, mas recomendamos ativar outras formas de pagamento que sejam relevantes para sua empresa e seus clientes. Consulte [Suporte a formas de pagamento](https://docs.stripe.com/payments/payment-methods/payment-method-support.md) para saber mais sobre os produtos e formas de pagamento aceitos, e nossa [página de preços](https://stripe.com/pricing/local-payment-methods) para ver as tarifas.

## Adicionar um endpoint [Lado do servidor]

> #### Nota
> 
> Para exibir o PaymentSheet antes de criar um PaymentIntent, consulte [Colete os dados de pagamento antes de criar um Intent](https://docs.stripe.com/payments/accept-a-payment-deferred.md?type=payment).

Se a sua plataforma Connect utiliza [Contas configuradas pelo cliente](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), utilize o nosso [guia](https://docs.stripe.com/connect/use-accounts-as-customers.md) para substituir as referências a `Cliente` e eventos no seu código pelas referências equivalentes da API Accounts v2.

Esta integração usa três objetos da API da Stripe:

1. [PaymentIntent](https://docs.stripe.com/api/payment_intents.md): A Stripe usa isso para representar sua intenção de coletar o pagamento de um cliente, acompanhando suas tentativas de cobrança e alterações no estado do pagamento durante todo o processo.

1. (Opcional) [Customer](https://docs.stripe.com/api/customers.md): Para configurar uma forma de pagamento para pagamentos futuros, vincule-a a um *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments). Crie um objeto Customer quando o cliente abrir uma conta na sua empresa. Se o cliente pagar como convidado, você pode criar o objeto Customer antes do pagamento e associá-lo à sua representação interna da conta do cliente, mais tarde.

1. (Opcional) [CustomerSession](https://docs.stripe.com/api/customer_sessions.md): Os dados do objeto Customer são confidenciais e não podem ser recuperados diretamente do aplicativo. Uma CustomerSession concede ao SDK acesso temporário com escopo definido ao cliente e fornece opções de configuração adicionais. Consulte uma lista completa de [opções de configuração](https://docs.stripe.com/api/customer_sessions/create.md#create_customer_session-components).

> Se você nunca salva cartões para um cliente e não permite que clientes retornando reutilizem cartões salvos, é possível omitir os objetos cliente e CustomerSession da sua integração.

Por motivos de segurança, o aplicativo não pode criar esses objetos. Para isso, adicione um endpoint ao servidor para:

1. Recuperar ou criar um Customer.
1. Cria uma [CustomerSession](https://docs.stripe.com/api/customer_sessions.md) para o cliente.
1. Cria um PaymentIntent com o [valor](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-amount), a [moeda](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-currency) e o [cliente](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer).
1. Retorna o *segredo do cliente* (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)) do Payment Intent, o `client_secret` da CustomerSession, o [id](https://docs.stripe.com/api/customers/object.md#customer_object-id) do Cliente e sua [chave publicável](https://dashboard.stripe.com/apikeys) para seu aplicativo.

As formas de pagamento mostradas aos clientes durante o processo de checkout também são incluídas no PaymentIntent. Você pode permitir que a Stripe obtenha as formas de pagamento das configurações do Dashboard ou listá-las manualmente. Independentemente da opção escolhida, saiba que a moeda passada no PaymentIntent filtra as formas de pagamento mostradas para o cliente. Por exemplo, se você passar EUR no `eur` e a OXXO estiver ativada no Dashboard, a OXXO não será exibida ao cliente porque a OXXO não aceita pagamentos em `eur`.

Se sua integração não exige uma opção baseada em código para oferecer formas de pagamento, a Stripe recomenda a opção automática. Isso ocorre porque a Stripe avalia a moeda, as restrições de forma de pagamento e outros parâmetros para determinar a lista de formas de pagamento aceitas. Priorizamos as formas de formas de pagamento que aumentam a conversão e que são mais relevantes para a moeda e a localização do cliente.

#### Gerenciar formas de pagamento no Dashboard

Você pode gerenciar formas de pagamento no [Dashboard](https://dashboard.stripe.com/settings/payment_methods). A Stripe processa a devolução de formas de pagamento qualificadas com base em fatores como valor, moeda e fluxo de pagamento da transação. O PaymentIntent é criado usando as formas de pagamento configuradas no Dashboard. Se não quiser usar o Dashboard ou se quiser especificar formas de pagamento manualmente, você pode listá-las usando o atributo `payment_method_types`.

#### curl

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

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

# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="eur" \
  # In the latest version of the API, specifying the `automatic_payment_methods` parameter
  # is optional because Stripe enables its functionality by default.
  -d "automatic_payment_methods[enabled]"=true \
```

#### Listar manualmente as formas de pagamento

#### curl

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

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

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

> A forma de pagamento precisa aceitar a moeda passada no PaymentIntent. Além disso, sua empresa precisa estar estabelecida em um dos países aceitos pela forma de pagamento. Consulte a página [Opções de integração de formas de pagamento](https://docs.stripe.com/payments/payment-methods/integration-options.md) para obter mais detalhes sobre o que é aceito.

## Coletar dados de pagamento [Lado do cliente]

Antes de exibir o Element Pagamento para dispositivos móveis, a página de checkout deve:

- Mostrar os produtos sendo comprados e o valor total
- Coletar todos os dados de entrega necessários
- Incluir um botão de checkout para apresentar a IU da Stripe

No checkout do aplicativo, faça uma solicitação de rede para o endpoint de backend criado por você na etapa anterior e chame o `initPaymentSheet` do hook `useStripe`.

```javascript

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

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

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

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

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

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

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

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

Quando o cliente tocar no botão **Checkout**, chame `presentPaymentSheet()` para abrir a descrição. Depois que o cliente finalizar o pagamento, a descrição será descartada e a promessa será resolvida com um `StripeError<PaymentSheetError>` opcional.

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

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

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

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

Se não houver erro, informe ao usuário que está tudo pronto (por exemplo, exibindo uma tela de confirmação de pedido).

Configurar `allowsDelayedPaymentMethods` como verdadeiro permite formas de pagamento de [notificação assíncrona](https://docs.stripe.com/payments/payment-methods.md#payment-notification) como contas bancárias dos EUA. Para essas formas de pagamento, o status final do pagamento não é conhecido quando o `PaymentSheet` é concluído, sendo efetivado ou não posteriormente. Se você aceitar esses tipos de formas de pagamento, informe o cliente que seu pedido está confirmado e somente processe o pedido (por exemplo, fazendo o envio do produto) quando o pagamento for bem-sucedido.

## Configurar um URL de retorno (somente iOS) [Lado do cliente]

Quando um cliente sair do seu aplicativo (por exemplo, para fazer a autenticação no Safari ou no aplicativo do banco), forneça uma opção para que ele retorne automaticamente ao seu aplicativo. Muitos tipos de formas de pagamento *exigem* um URL de retorno. Se você não fornecer um, não poderemos apresentar formas de pagamento que exijam um URL de retorno aos seus usuários, mesmo que você os habilite.

Para fornecer um URL de retorno:

1. [Cadastre](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app#Register-your-URL-scheme) um URL personalizado. Links universais não são aceitos.
1. [Configurar](https://reactnative.dev/docs/linking) seu URL personalizado.
1. Configure seu componente-raiz para encaminhar o URL ao SDK da Stripe, conforme mostrado abaixo.

> Se estiver usando a Expo, [defina seu esquema](https://docs.expo.io/guides/linking/#in-a-standalone-app) no arquivo `app.json`.

```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>
  );
}
```

Além disso, defina o `returnURL` quando chamar o método `initPaymentSheet`:

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

Para obter mais informações sobre esquemas de URL nativos, consulte a documentação do [Android](https://developer.android.com/training/app-links/deep-linking) e do [iOS](https://developer.apple.com/documentation/xcode/allowing_apps_and_websites_to_link_to_your_content/defining_a_custom_url_scheme_for_your_app).

## Processar eventos pós-pagamento

Stripe envia um evento [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) quando o pagamento é concluído. Use a [ferramenta Dashboard webhook](https://dashboard.stripe.com/webhooks) ou siga o [guia de webhooks](https://docs.stripe.com/webhooks/quickstart.md) para receber esses eventos e executar ações, como enviar um e-mail de confirmação do pedido ao cliente, registrar a venda em um banco de dados ou iniciar um fluxo de trabalho de envio.

Escute esses eventos em vez de aguardar um retorno de chamada do cliente. No cliente, o consumidor pode fechar a janela do navegador ou sair do aplicativo antes da execução do retorno de chamada, o que permite que clientes mal-intencionados manipulem a resposta. Configurar sua integração para escutar eventos assíncronos é o que permite a você aceitar [diferentes tipos de formas de pagamento](https://stripe.com/payments/payment-methods-guide) com uma única integração.

Além de gerenciar o evento `payment_intent.succeeded`, recomendamos gerenciar esses outros eventos ao coletar pagamentos com o Element Pagamento:

| Evento                                                                                                                          | Descrição                                                                                                                                                                                                                                                                     | Ação                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.succeeded)           | Enviado quando um cliente conclui um pagamento com êxito.                                                                                                                                                                                                                     | Envie ao cliente uma confirmação de pedido e *processe* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) o pedido. |
| [payment_intent.processing](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.processing)         | Enviado quando um cliente inicia um pagamento, mas o pagamento ainda precisa ser concluído. Esse evento costuma ser enviado quando um cliente inicia um débito bancário. Ele é seguido por um evento `payment_intent.succeeded` ou `payment_intent.payment_failed` no futuro. | Envie ao cliente uma confirmação do pedido que indica que o pagamento está pendente. Para produtos digitais, pode ser necessário executar o pedido antes de aguardar a conclusão do pagamento.  |
| [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.payment_failed) | Enviado quando um cliente tenta fazer um pagamento, mas o pagamento falha.                                                                                                                                                                                                    | Se um pagamento passa de `processing` para `payment_failed`, ofereça ao cliente outra tentativa para pagar.                                                                                     |

## Testar a integração

#### Cartões

| Número do cartão    | Cenário                                                                                                                                                                                                                                                                                             | Como testar                                                                                                                 |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| 4242424242424242    | O pagamento com cartão é bem-sucedido e não precisa de autenticação.                                                                                                                                                                                                                                | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000002500003155    | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000000000009995    | O cartão é recusado com um código de recusa como `insufficient_funds`.                                                                                                                                                                                                                              | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 6205500000000000004 | O cartão UnionPay tem um comprimento variável de 13 a 19 dígitos.                                                                                                                                                                                                                                   | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |

#### Débito bancário autenticado

| Forma de pagamento | Cenário                                                                                                                                                                                                | Como testar                                                                                                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bancontact, iDEAL  | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação imediata.                                                         | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar pagamento de teste** na página de redirecionamento. |
| Pay by Bank        | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification).                             | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento.                                |
| Pay by Bank        | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação posterior.                                                        | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar o pagamento de teste** na página de redirecionamento.                                  |
| BLIK               | Os pagamentos BLIK falham de várias formas: falhas imediatas (por exemplo, o código está vencido ou inválido), erros atrasados (o banco recusa) ou limites de tempo (o cliente não respondeu a tempo). | Use padrões de e-mail para [simular as diferentes falhas.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures)                                                                    |

#### Débitos bancários

| Forma de pagamento     | Cenário                                                                                           | Como testar                                                                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático SEPA | O cliente paga com débito automático SEPA.                                                        | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processando e, três minutos depois, para bem-sucedido. |
| Débito automático SEPA | O status da intenção de pagamento do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`.                                                                                                          |

Consulte [Testes](https://docs.stripe.com/testing.md) para obter mais informações sobre como testar sua integração.

## Habilitar leitura de cartões [Lado do cliente]

> Ativar a leitura de cartões é obrigatório para o processo de análise de aplicativos da Apple no iOS. No Android, a leitura de cartões não é obrigatória, mas recomendamos que seja habilitada.

### iOS​

Para habilitar o suporte à leitura de cartões no iOS, defina `NSCameraUsageDescription` (**Privacy - Camera Usage Description**) no `Info.plist` do seu aplicativo e informe um motivo para o acesso à câmera (por exemplo, “Para ler cartões”).

### Android

To enable card scanning support, [request production access](https://developers.google.com/pay/api/android/guides/test-and-deploy/request-prod-access) to the Google Pay API from the [Google Pay and Wallet Console](https://pay.google.com/business/console?utm_source=devsite&utm_medium=devsite&utm_campaign=devsite).

- Se você ativou o Google Pay, o recurso de escaneamento de cartões está automaticamente disponível em nossa IU em dispositivos elegíveis. Para saber mais sobre dispositivos elegíveis, consulte as [restrições da API do Google Pay](https://developers.google.com/pay/payment-card-recognition/debit-credit-card-recognition)
- **Importante:** O recurso de escanear cartão só aparece em builds assinadas com a mesma chave de assinatura registrada no [Google Pay & Wallet Console](https://pay.google.com/business/console). Builds de teste ou debug usando chaves de assinatura diferentes (por exemplo, builds distribuídas pelo Firebase App Tester) não mostrarão a opção **Escanear cartão**. Para testar o escaneamento de cartão em versões pré-lançamento, você deve:
  - Assinar suas builds de teste com a chave de assinatura de produção
  - Adicionar sua impressão digital da chave de assinatura de teste ao Google Pay e Wallet Console

## Optional: Habilitar Link

Ative Link nas suas [configurações de Formas de Pagamento](https://dashboard.stripe.com/settings/payment_methods) para permitir que seus clientes salvem e reutilizem com segurança suas informações de pagamento usando o botão de checkout expresso com um clique do Link.

### Passe o e-mail do cliente para o Mobile Payment Element

Link autentica o cliente usando o endereço de e-mail. A Stripe recomenda preencher previamente o máximo de informações possível para otimizar o processo de checkout.

Para preencher o nome, o endereço de e-mail e o número de telefone do cliente, forneça os dados do cliente a `defaultBillingDetails` para `initPaymentSheet`.

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

## Optional: Habilitar Apple Pay

### Solicitar um ID de comerciante da Apple

Obtenha um ID de comerciante da Apple [solicitando um novo identificador](https://developer.apple.com/account/resources/identifiers/add/merchant) no site de desenvolvedores da Apple.

Preencha o formulário com descrição e identificador. A descrição é para seu controle e pode ser modificada no futuro. A Stripe recomenda que você use o nome do aplicativo como identificador (por exemplo, `merchant.com.{{YOUR_APP_NAME}}`).

### Criar um certificado do Apple Pay

Crie um certificado para criptografia de dados de pagamento pelo aplicativo.

Vá até [Configurações de certificado do iOS](https://dashboard.stripe.com/settings/ios_certificates) no Dashboard, clique em **Adicionar novo aplicativo** e siga o guia.

Baixe um arquivo de solicitação de assinatura de certificado (CSR) para obter um certificado seguro da Apple que permite usar o Apple Pay.

Um arquivo CSR deve ser usado para emitir exatamente um certificado. Se você trocar seu ID de comerciante da Apple, acesse as [Configurações de certificado do iOS](https://dashboard.stripe.com/settings/ios_certificates) no Dashboard para obter um novo CSR e certificado.

### Integrar com Xcode

Adicione as funções do Apple Pay ao aplicativo. No Xcode, abra as configurações do projeto, clique na guia **Signing & Capabilities** e adicione o recurso **Apple Pay**. Talvez seja necessário fazer login na sua conta de desenvolvedor. Selecione o ID de comerciante criado anteriormente e o aplicativo já pode aceitar Apple Pay.
![](https://b.stripecdn.com/docs-statics-srv/assets/xcode.a701d4c1922d19985e9c614a6f105bf1.png)

Habilitar o recurso Apple Pay no Xcode

### Adicionar Apple Pay

#### Pagamento avulso

Passe seu ID de comerciante quando criar `StripeProvider`:

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

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

Quando você chamar `initPaymentSheet`, passe seus [ApplePayParams](https://stripe.dev/stripe-react-native/api-reference/modules/PaymentSheet.html#ApplePayParams):

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

#### Pagamentos recorrentes

Quando você chamar `initPaymentSheet`, passe um [ApplePayParams](https://stripe.dev/stripe-react-native/api-reference/modules/PaymentSheet.html#ApplePayParams) com `merchantCountryCode` definido como o código de país da sua empresa.

De acordo com as [diretrizes da Apple](https://developer.apple.com/design/human-interface-guidelines/apple-pay#Supporting-subscriptions) para pagamentos recorrentes, você também deve definir um `cardItems` que inclua um [RecurringCartSummaryItem](https://stripe.dev/stripe-react-native/api-reference/modules/ApplePay.html#RecurringCartSummaryItem) com o valor que pretende cobrar (por exemplo, “59,95 USD por mês”).

Você também pode adotar [tokens de comerciante](https://developer.apple.com/apple-pay/merchant-tokens/) definindo a `request` com seu `type` definido como `PaymentRequestType.Recurring`

Para saber como usar pagamentos recorrentes com Apple Pay, consulte a [documentação do PassKit da Apple](https://developer.apple.com/documentation/passkit/pkpaymentrequest).

#### iOS (React Native)

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

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

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

### Rastreamento de pedidos

Para adicionar informações de [rastreamento de pedido](https://developer.apple.com/design/human-interface-guidelines/technologies/wallet/designing-order-tracking) no iOS 16 ou mais recente, configure uma função de retorno de chamada `setOrderTracking`. A Stripe chama sua implementação após a conclusão do pagamento, mas antes que o iOS ignore a descrição de compra do Apple Pay.

Na implementação da função de retorno de chamada `setOrderTracking`, obtenha os detalhes do pedido concluído no seu servidor e passe esses dados à função de `completion` informada.

Para saber mais sobre rastreamento de pedidos, consulte a [documentação de pedidos da carteira da Apple](https://developer.apple.com/documentation/walletorders).

#### iOS (React Native)

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

## Optional: Habilitar Google Pay

### Configure a integração

Para usar o Google Pay, habilite a API Google Pay adicionando o seguinte à `<application>` tag do seu **AndroidManifest.xml**:

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

Veja mais detalhes na [Configuração da API Google Pay](https://developers.google.com/pay/api/android/guides/setup) do Google Pay para Android.

### Adicionar Google Pay

Quando você inicializar `PaymentSheet`, defina `merchantCountryCode` como o código de país da sua empresa e defina `googlePay` como true.

Você também pode usar o ambiente de teste passando o parâmetro `testEnv`. Você só pode testar o Google Pay em um dispositivo Android físico. Siga a [documentação do React Native](https://reactnative.dev/docs/running-on-device) para testar seu aplicativo em um dispositivo físico.

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

## Optional: Personalizar a descrição [Lado do cliente]

Toda personalização é configurada usando `initPaymentSheet`.

### Aparência

Personalize as cores, fontes e outros elementos para combinar com a aparência do seu app usando a [API de aparência](https://docs.stripe.com/elements/appearance-api/mobile.md?platform=react-native).

### Nome de exibição do comerciante

Especifique o nome da empresa exibido para o cliente definindo `merchantDisplayName`. Por padrão, este é o nome do seu aplicativo.

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

### Modo escuro

Por padrão, o `PaymentSheet` se adapta automaticamente às configurações de aparência do sistema do usuário (modo claro e escuro). É possível alterar isso configurando a propriedade `style` como modo `alwaysLight` ou `alwaysDark` no iOS.

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

No Android, configure o modo claro ou escuro no seu aplicativo:

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

## Optional: Gerenciar logout de usuário

`PaymentSheet` armazena algumas informações localmente para lembrar se um usuário utilizou Link dentro de um aplicativo. Para limpar o estado interno do `PaymentSheet`, chame o método `resetPaymentSheetCustomer()` quando o usuário fizer logout.

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

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

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

## Optional: Conclua o pagamento em sua IU

Você pode exibir a Payment Sheet apenas para coletar dados da forma de pagamento e depois chamar um método `confirm` para concluir o pagamento na IU do aplicativo. Isso é útil quando você tem um botão de compra personalizado ou precisa de mais etapas após a coleta dos dados do pagamento.
![](https://b.stripecdn.com/docs-statics-srv/assets/react-native-multi-step.84d8a0a44b1baa596bda491322b6d9fd.png)

> Um exemplo de integração está [disponível no GitHub](https://github.com/stripe/stripe-react-native/blob/master/example/src/screens/PaymentsUICustomScreen.tsx).

1. Primeiro, chame `initPaymentSheet` e passe `customFlow: true`. `initPaymentSheet` é resolvido com uma opção de pagamento inicial que contém uma imagem e um rótulo representando a forma de pagamento do cliente. Atualize a IU com esses dados.

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

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

1. Use `presentPaymentSheet` para coletar detalhes de pagamento. Quando o cliente termina, a folha se desfaz por si mesma e resolve a promessa. Atualize sua IU com os detalhes da forma de pagamento selecionada.

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

1. Use `confirmPaymentSheetPayment` para confirmar o pagamento. Isso é resolvido com o resultado do pagamento.

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

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

Configurar `allowsDelayedPaymentMethods` como verdadeiro permite formas de pagamento de [notificação assíncrona](https://docs.stripe.com/payments/payment-methods.md#payment-notification) como contas bancárias dos EUA. Para essas formas de pagamento, o status final do pagamento não é conhecido quando o `PaymentSheet` é concluído, sendo efetivado ou não posteriormente. Se você aceitar esses tipos de formas de pagamento, informe o cliente que seu pedido está confirmado e somente processe o pedido (por exemplo, fazendo o envio do produto) quando o pagamento for bem-sucedido.