Atualizações do status do pagamento

O PaymentIntents é 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 nas configurações do usuário.

Verificar o status do PaymentIntent no cliente

Quando concluir um pagamento no cliente com a função confirmCardPayment, você pode inspecionar o PaymentIntent retornado para determinar seu status atual:

(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:

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 ). 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 e passando o segredo do cliente.

Veja a seguir alguns status possíveis do PaymentIntent após uma confirmação:

Leia mais sobre os status de PaymentIntent.

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

Monitorar um PaymentIntent com webhooks

A Stripe pode enviar eventos de webhook 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 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.

Para gerenciar um evento de webhook, crie uma rota no servidor e configure um endpoint de webhook correspondente no Dashboard. 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:

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:

Para testar webhooks localmente, você pode usar o Stripe CLI. Após instalá-lo, você poderá encaminhar eventos ao seu servidor:

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

Saiba mais sobre configurar webhooks.

Identificar cobranças em um PaymentIntent

Quando você tenta receber um pagamento de um cliente, o PaymentIntent cria uma Charge. Para ver o ID da cobrança mais recente, inspecione a propriedade latest_charge do PaymentIntent:

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

intent = Stripe::PaymentIntent.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 e especifique o parâmetro payment_intent​.

curl -G https://api.stripe.com/v1/charges \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d payment_intent=
{{PAYMENT_INTENT_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 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.

Consulte a documentação das formas de pagamento para obter mais detalhes sobre como gerenciar as próximas ações obrigatórias.