# A API Payment Intents

Aprenda a usar a API Payment Intents para pagamentos da Stripe.

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

Use a API [Payment Intents](https://docs.stripe.com/api/payment_intents.md) para criar uma integração de pagamentos capaz de gerenciar fluxos de pagamento complexos que mude ao longo do [ciclo de vida do PaymentIntent](https://docs.stripe.com/payments/paymentintents/lifecycle.md). Essa API rastreia um pagamento, da criação até o checkout, e aciona autenticações adicionais quando necessário.

Estas são algumas vantagens do uso da API [Payment Intents](https://docs.stripe.com/api/payment_intents.md):

- Administrar autenticação automática
- Sem cobranças duplicadas
- Sem problemas com a [chave de idempotência](https://docs.stripe.com/api/idempotent_requests.md)
- Compatibilidade com *Autenticação Forte de Cliente* (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) (SCA) e mudanças regulatórias similares

## Um conjunto completo de APIs

Use a API [Payment Intents](https://docs.stripe.com/api/payment_intents.md) com as APIs [Setup Intents](https://docs.stripe.com/api/setup_intents.md) e [Payment Methods](https://docs.stripe.com/api/payment_methods.md). Essas APIs ajudam a lidar com pagamentos dinâmicos (por exemplo, autenticação adicional como *3D Secure* (3D Secure (3DS) provides an additional layer of authentication for credit card transactions that protects businesses from liability for fraudulent card payments)) e a preparar sua expansão para outros países, permitindo que você aceite novos regulamentos e formas de pagamento regionais.

A integração com a API Payment Intents tem duas etapas: criar e *confirmar* (Confirming a PaymentIntent indicates that the customer intends to pay with the current or provided payment method. Upon confirmation, the PaymentIntent attempts to initiate a payment) um PaymentIntent. Cada PaymentIntent normalmente está vinculado a um único carrinho de compras ou sessão do cliente no seu aplicativo. O PaymentIntent encapsula os detalhes da transação, como formas de pagamento aceitas, o valor a ser cobrado e a moeda desejada.

## Criar um PaymentIntent

Para começar, consulte o [guia sobre como aceitar pagamentos](https://docs.stripe.com/payments/accept-a-payment.md?ui=elements). Ele descreve como criar um PaymentIntent no servidor e passar 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)) ao cliente em vez de passar todo o objeto PaymentIntent.

Ao [criar o PaymentIntent](https://docs.stripe.com/api/payment_intents/create.md), é possível especificar opções como o valor e a moeda:

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

### Práticas recomendadas

- Recomendamos criar um PaymentIntent assim que você souber o valor, como quando o cliente começa a processar o checkout, para ajudar a acompanhar seu [funil de compra](https://en.wikipedia.org/wiki/Purchase_funnel). Se o valor mudar, você pode [atualizar](https://docs.stripe.com/api.md#update_payment_intent) o [valor](https://docs.stripe.com/api.md#payment_intent_object-amount). Por exemplo, se o cliente sair do processo de checkout e adicionar novos itens ao carrinho, talvez seja necessário atualizar o valor quando ele começar o processo de checkout novamente.

- Se o processo de checkout for interrompido e depois retomado, tente reaproveitar o PaymentIntent em vez de criar outro. Cada PaymentIntent tem um ID único que você pode usar para [recuperação](https://docs.stripe.com/api.md#retrieve_payment_intent) se precisar dele novamente. No modelo de dados do seu aplicativo, é possível armazenar o ID do PaymentIntent no carrinho de compras ou sessão do cliente para facilitar a recuperação. A vantagem de reaproveitar o PaymentIntent é que o [estado do objeto](https://docs.stripe.com/payments/paymentintents/lifecycle.md) ajuda a rastrear tentativas de pagamento malsucedidas de um determinado carrinho ou sessão.

- Lembre-se de fornecer uma [chave de idempotência](https://docs.stripe.com/api/idempotent_requests.md) para evitar a criação de PaymentIntents duplicados para a mesma compra. Normalmente, essa chave é criada com base no ID associado ao carrinho ou sessão do cliente no aplicativo.

## Passar o segredo do cliente para o lado do cliente

O PaymentIntent contém um [segredo do cliente](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret), uma chave que é única para cada PaymentIntent. No lado do cliente do seu aplicativo, o segredo do cliente é usado pelo Stripe.js como parâmetro para invocar funções (como [stripe.confirmCardPayment](https://docs.stripe.com/js.md#stripe-confirm-card-payment) ou [stripe.handleCardAction](https://docs.stripe.com/js.md#stripe-handle-card-action)) e finalizar o pagamento.

### 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 %>">
  <button id="submit">Submit</button>
</form>
```

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

> O segredo do cliente pode ser utilizado para concluir o processo de pagamento com o valor especificado no PaymentIntent. Não registre, incorpore a URLs ou exponha esse segredo a qualquer outra pessoa que não seja o cliente. Verifique se todas as páginas que contenham o segredo do cliente têm *TLS* (TLS refers to the process of securely transmitting data between the client—the app or browser that your customer is using—and your server. This was originally performed using the SSL (Secure Sockets Layer) protocol).

## Após o pagamento

Após o cliente confirmar o pagamento, uma prática recomendada para seu servidor é [monitorar webhooks](https://docs.stripe.com/payments/payment-intents/verifying-status.md#webhooks) para detectar quando o pagamento é concluído corretamente ou falha.

Um `PaymentIntent` pode ter mais de um objeto de[Cobrança](https://docs.stripe.com/api/charges.md) associado a ele se houver múltiplas tentativas de pagamento. Por exemplo, tentativas podem criar múltiplas`Cobranças`. Para cada cobrança, você pode inspecionar o[resultado](https://docs.stripe.com/api/charges/object.md#charge_object-outcome) e os[detalhes das formas de pagamento](https://docs.stripe.com/api/charges/object.md#charge_object-payment_method_details) usados.

## Otimização de formas de pagamento para pagamentos futuros

O parâmetro [setup_future_usage](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-setup_future_usage) salva formas de pagamento para uso no futuro. Para cartões, ele também otimiza as taxas de autorização, cumprindo regras de rede e legislações regionais, como a [SCA](https://docs.stripe.com/strong-customer-authentication.md). Para saber qual valor utilizar, considere a frequência de uso dessa forma de pagamento no futuro.

| Como você pretende usar a forma de pagamento                                                                                                                                                 | Valor da enumeração de setup_future_usage a ser usado |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| Somente para pagamentos *na sessão* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method)     | `on_session`                                          |
| Somente para pagamentos *fora da sessão* (A payment is described as off-session if it occurs without the direct involvement of the customer, using previously-collected payment information) | `off_session`                                         |
| Pagamentos na sessão ou fora da sessão                                                                                                                                                       | `off_session`                                         |

Você pode continuar a aceitar pagamentos *fora da sessão* (A payment is described as off-session if it occurs without the direct involvement of the customer, using previously-collected payment information) com cartões configurados para pagamentos na sessão, mas a probabilidade de o banco recusar o pagamento fora da sessão e exigir autenticação do titular do cartão aumenta.

O exemplo a seguir mostra como criar um PaymentIntent e especificar `setup_future_usage`:

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

> As configurações de pagamentos fora da sessão são mais propensas a causar dificuldades adicionais. Use a configuração *na sessão* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method) se não pretende aceitar pagamentos fora da sessão com o cartão salvo.

## Descrição dinâmica no extrato

Por padrão, a [descrição no extrato](https://docs.stripe.com/get-started/account/activate.md#public-business-information) da sua conta Stripe aparece nos extratos do cliente sempre que você cobra o cartão. Para fornecer uma descrição diferente com base em pagamento, use o parâmetro [statement_descriptor](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-statement_descriptor).

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

> #### Observação
> 
> Use o parâmetro `statement_descriptor` para cobranças sem cartão e `statement_descriptor_suffix` para cobranças com cartão.

[As descrições no extrato](https://docs.stripe.com/get-started/account/statement-descriptors.md) são limitadas a 22 caracteres, não podem usar os caracteres especiais `<`, `>`, `'`, `"` ou `*` e não devem consistir apenas em números. Ao usar descrições no extrato dinâmicas, o texto dinâmico é anexado ao [prefixo da descrição no extrato](https://dashboard.stripe.com/settings/public) definido no Dashboard da Stripe. Um asterisco (`*`) e um espaço em branco também são adicionados para separar a descrição no extrato padrão da parte dinâmica. Esses dois caracteres também contam para o limite de 22 caracteres.

## Armazenar informações em metadados

A Stripe aceita [metadados](https://docs.stripe.com/api.md#metadata) nas solicitações mais comuns, como processamento de pagamentos. Os metadados não aparecem para o cliente nem são usados como referência para a recusa ou bloqueio de um pagamento no nosso sistema de prevenção de fraudes.

Por meio de metadados, você pode associar a atividade da Stripe às informações que considera relevantes.

Todos os metadados incluídos podem ser visualizados no Dashboard (por exemplo, ao consultar a página de um pagamento individual) e também estão disponíveis em relatórios comuns. Como exemplo, você pode anexar o ID do pedido da sua loja ao PaymentIntent desse pedido. Isso permite que você reconcilie facilmente os pagamentos na Stripe com os pedidos no seu sistema.

Se você está usando *Radar for Fraud Teams*, considere enviar informações adicionais do cliente e do pedido como metadados. Assim, você pode criar [regras do Radar usando atributos de metadados](https://docs.stripe.com/radar/rules/reference.md#metadata-attributes) e ter mais informações disponíveis no Dashboard, o que pode agilizar seu processo de revisão.

Quando cria uma cobrança, o PaymentIntent copia os metadados para a cobrança. Atualizações posteriores nos metadados do PaymentIntent não modificam os metadados de cobranças criadas anteriormente pelo PaymentIntent.

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

> Não armazene dados sensíveis (informações que identifiquem uma pessoa, dados de cartão e assim por diante) como metadados ou no parâmetro `description` do PaymentIntent.

## See also

- [Aceitar um pagamento online](https://docs.stripe.com/payments/accept-a-payment.md?platform=web)
- [Aceitar um pagamento em um aplicativo iOS](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=ios)
- [Aceitar um pagamento em um aplicativo Android](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=android)
- [Configurar pagamentos futuros](https://docs.stripe.com/payments/save-and-reuse.md)