# Atualizações do status do pagamento

Monitore e verifique o status dos pagamento para poder responder a pagamentos bem-sucedidos e malsucedidos.

O *PaymentIntents* (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) é atualizado como resposta a ações realizadas pelo cliente ou pela forma de pagamento. Sua integração pode examinar o PaymentIntent para determinar o status da forma de pagamento e permitir que você tome medidas comerciais ou responda a situações que precisem de mais intervenção.

Você também pode usar o Stripe Dashboard para configurar sua conta para enviar e-mail sobre o status do pagamento, como pagamentos bem-sucedidos. Altere suas [notificações por e-mail](https://docs.stripe.com/get-started/account/teams.md#email-notifications) nas [configurações do usuário](https://dashboard.stripe.com/settings/user).

## Verificar o status do PaymentIntent no cliente

Quando concluir um pagamento no cliente com a função [confirmCardPayment](https://docs.stripe.com/js.md#stripe-confirm-card-payment), você pode inspecionar o PaymentIntent retornado para determinar seu status atual:

```javascript
(async () => {
  const {paymentIntent, error} = await stripe.confirmCardPayment(clientSecret);
  if (error) {
    // Handle error here
  } else if (paymentIntent && paymentIntent.status === 'succeeded') {
    // Handle successful payment here
  }
})();
```

A função `confirmCardPayment` pode apresentar estes resultados:

| **Evento**                   | **O que ocorreu**                                       | **Integração esperada**                                                               |
| ---------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Resolve com um PaymentIntent | O cliente concluiu o pagamento na página de checkout    | Informe ao cliente que o pagamento foi bem-sucedido                                   |
| Resolve com um erro          | O pagamento do cliente falhou na sua página de checkout | Exiba uma mensagem de erro e solicite que o cliente tente fazer o pagamento novamente |

A promessa retornada por `confirmCardPayment` é resolvida quando o processo de pagamento é concluído ou falha com um erro. Quando é concluído corretamente e retorna um PaymentIntent, o status é sempre `succeeded` (ou `requires_capture` se [capturar posteriormente](https://docs.stripe.com/payments/place-a-hold-on-a-payment-method.md) ). Quando o pagamento exige uma etapa adicional, como autenticação, a promessa só é resolvida quando essa etapa é concluída ou o tempo esgota.

## Verificar o status do PaymentIntent no cliente sem usar confirmCardPayment

Para verificar o status de um PaymentIntent sem usar a função `confirmCardPayment`, recupere-o de forma independente usando a função [retrievePaymentIntent](https://docs.stripe.com/js/payment_intents/retrieve_payment_intent) e passando 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)).

```javascript
(async () => {
  const {paymentIntent} = await stripe.retrievePaymentIntent(clientSecret);
  if (paymentIntent && paymentIntent.status === 'succeeded') {
    // Handle successful payment here
  } else {
    // Handle unsuccessful, processing, or canceled payments and API errors here
  }
})();
```

Veja a seguir alguns [status possíveis](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-status) do PaymentIntent após uma confirmação:

| **O que ocorreu**                                       | **Status esperado do PaymentIntent** |
| ------------------------------------------------------- | ------------------------------------ |
| O cliente concluiu o pagamento na página de checkout    | `succeeded`                          |
| O cliente não concluiu o checkout                       | `requires_action`                    |
| O pagamento do cliente falhou na sua página de checkout | `requires_payment_method`            |

[Leia mais sobre os status de PaymentIntent](https://docs.stripe.com/payments/paymentintents/lifecycle.md).

## Monitorar um PaymentIntent com webhooks

A Stripe pode enviar eventos de *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) para o seu servidor para notificar quando o status de um PaymentIntent muda, que você pode usar para finalidades como determinar quando executar mercadorias e serviços.

Não tente gerenciar a *execução* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) do pedido no lado do cliente porque ele pode sair da página após concluir o pagamento, mas antes do início do processo de execução. Em vez de executar o pedido no lado do cliente, use webhooks para monitorar o evento `payment_intent.succeeded` e processar a execução de forma assíncrona.

> É tecnicamente possível usar sondagens em vez de webhooks para monitorar alterações causadas por operações assíncronas (recuperar repetidamente um PaymentIntent para verificar seu status), mas fazer isso é muito menos confiável e pode causar problemas de limitação de taxa. A Stripe [limita a taxa](https://docs.stripe.com/testing.md#rate-limits) das solicitações da API . Portanto, tome cuidado se decidir usar sondagens.

Para gerenciar um evento de webhook, crie uma rota no servidor e configure um endpoint de webhook correspondente [no Dashboard](https://dashboard.stripe.com/account/webhooks). A Stripe envia o evento `payment_intent.succeeded` quando o pagamento é bem-sucedido, e o evento `payment_intent.payment_failed` quando o pagamento falha.

O conteúdo do webhook inclui o objeto PaymentIntent. O exemplo abaixo mostra como gerenciar ambos os eventos:

#### Ruby

```ruby
require 'sinatra'
require 'stripe'

post '/webhook' do
    payload = request.body.read
    sig_header = request.env['HTTP_STRIPE_SIGNATURE']
    event = nil

    begin
        event = Stripe::Webhook.construct_event(
            payload, sig_header, endpoint_secret
        )
    rescue JSON::ParserError => e
        # Invalid payload
        status 400
        return
    rescue Stripe::SignatureVerificationError => e
        # Invalid signature
        status 400
        return
    end

    case event['type']
    when 'payment_intent.succeeded'
        intent = event['data']['object']
        puts "Succeeded:", intent['id']
        # Fulfill the customer's purchase
    when 'payment_intent.payment_failed'
        intent = event['data']['object']
        error_message = intent['last_payment_error'] && intent['last_payment_error']['message']
        puts "Failed:", intent['id'], error_message
        # Notify the customer that payment failed
    end

    status 200
end
```

Quando o pagamento não é bem-sucedido, você pode obter mais detalhes inspecionando a propriedade `last_payment_error` do PaymentIntent. É possível notificar o cliente que o pagamento não foi concluído e recomendar que ele tente outra forma de pagamento. Reutilize o mesmo PaymentIntent para continuar a rastrear a compra do cliente.

### Gerenciar eventos de webhook específicos

A lista a seguir descreve como gerenciar eventos de webhook:

| Evento                      | Descrição                                                                                                                                                                                                             | Próximas etapas                                                                                                   |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `processing`                | O pagamento do cliente foi enviado com sucesso para a Stripe. Aplicável apenas a formas de pagamento com [confirmação de sucesso atrasada](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Esperar a conclusão ou falha do pagamento iniciado.                                                               |
| `succeeded`                 | O pagamento do cliente foi confirmado.                                                                                                                                                                                | Execute o pedido de mercadorias ou serviços.                                                                      |
| `amount_capturable_updated` | O pagamento do cliente foi autorizado e está pronto para captura.                                                                                                                                                     | Capturar os fundos disponíveis para pagamento                                                                     |
| `payment_failed`            | O pagamento do cliente foi recusado pela bandeira do cartão ou expirou por outros motivos…                                                                                                                            | Entre em contato com o cliente por e-mail ou notificação push e solicite que ele forneça outra forma de pagamento |

Para testar webhooks localmente, você pode usar o [Stripe CLI](https://docs.stripe.com/stripe-cli.md). Após instalá-lo, você poderá encaminhar eventos ao seu servidor:

```bash
stripe listen --forward-to localhost:4242/webhook
Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
```

Saiba mais sobre [configurar webhooks](https://docs.stripe.com/webhooks.md).

## Identificar cobranças em um PaymentIntent

Quando você tenta receber um pagamento de um cliente, o PaymentIntent cria uma [Charge](https://docs.stripe.com/api/charges.md). Para ver o ID da cobrança mais recente, inspecione a propriedade [latest_charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge) do PaymentIntent:

#### 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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

intent = client.v1.payment_intents.retrieve('{{PAYMENT_INTENT_ID}}')
latest_charge = intent.latest_charge
```

Para ver todas as cobranças associadas a um PaymentIntent, incluindo as cobranças malsucedidas, [liste todas as cobranças](https://docs.stripe.com/api/charges/list.md#list_charges-payment_intent) e especifique o parâmetro `payment_intent​`.

```curl
curl -G https://api.stripe.com/v1/charges \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "payment_intent={{PAYMENTINTENT_ID}}"
```

## Gerenciar as próximas ações

Algumas formas de pagamento exigem etapas adicionais, como autenticação, para concluir o processo de pagamento. O Stripe.js gerencia essas etapas automaticamente durante a confirmação do PaymentIntent, mas pode ser melhor processá-las manualmente em integrações avançadas.

A propriedade [next_action](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action) do PaymentIntent expõe a próxima etapa que sua integração deve processar para concluir o pagamento. O tipo de próximas ações possíveis pode diferir entre as várias formas de pagamento. Veja uma lista completa das próximas ações na [documentação de API](https://docs.stripe.com/api.md#payment_intent_object-next_action-type).

Consulte a [documentação das formas de pagamento](https://docs.stripe.com/payments/payment-methods/overview.md) para obter mais detalhes sobre como gerenciar as próximas ações obrigatórias.