Actualizaciones del estado del pago

Los PaymentIntents se actualizan en respuesta a acciones ejecutadas por el cliente o el método de pago. Tu integración puede inspeccionar el PaymentIntent para determinar el estado del proceso de pago y tomar medidas comerciales o responder a estados que requieran mayor intervención.

También puedes usar el Dashboard de Stripe para configurar tu cuenta a fin de que te envíe un correo electrónico que te informe sobre el estado del pago, como cuando recibes los pagos realizados correctamente. Cambia tus notificaciones por correo electrónico en tu configuración de usuario.

Comprobar el estado del PaymentIntent del lado del cliente

Cuando el cliente completa un pago con la función confirmCardPayment, puedes inspeccionar el PaymentIntent devuelto para determinar su estado actual:

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

Estos son algunos de los posibles resultados cuando se usa la función confirmCardPayment:

La promesa que devuelve confirmCardPayment se resuelve cuando el proceso de pago se completa o falla con un error. Cuando se completa correctamente y devuelve un PaymentIntent, el estado siempre es succeeded (o requires_capture si se captura más tarde). Cuando el pago requiere un paso más, como la autenticación, la promesa no se resuelve hasta que ese paso se complete o se agote el tiempo de espera.

Comprobar el estado del PaymentIntent del lado del cliente sin usar confirmCardPayment

Para comprobar el estado de un PaymentIntent sin usar la función confirmCardPayment, recupéralo de forma independiente usando la función retrievePaymentIntent y transfiriendo el secreto de cliente.

Estos son algunos de los posibles estados del PaymentIntent después de una confirmación:

Obtén más información sobre los estados 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
  }
})();

Supervisar un PaymentIntent con webhooks

Stripe puede enviar eventos de webhook a tu servidor a fin de notificarte cuando cambie el estado de un PaymentIntent, que puedes usar para, por ejemplo, determinar cuándo entregar bienes y servicios.

No intentes gestionar la entrega del pedido del lado del cliente porque los clientes pueden abandonar la página después de completar el pago, pero antes de que se inicie el proceso de entrega. En lugar de iniciarlo del lado del cliente, usa webhooks para supervisar el evento payment_intent.succeeded y manejar su finalización de forma asincrónica.

Para gestionar un evento de webhook, crea una ruta en tu servidor y configura el punto de conexión de webhooks correspondiente en el Dashboard. Stripe envía el evento payment_intent.succeeded cuando un pago se realiza correctamente, y el evento payment_intent.payment_failed cuando un pago falla.

La carga del webhook incluye el objeto PaymentIntent. El siguiente ejemplo muestra cómo gestionar ambos 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

Cuando el pago falla, puedes buscar más detalles inspeccionando la propiedad last_payment_error del PaymentIntent. Puedes notificarle al cliente que no se completó el pago y recomendarle volver a intentarlo con otro método de pago. Reutiliza el mismo PaymentIntent para continuar el seguimiento de la compra del cliente.

Cómo administrar eventos de webhook específicos

La siguiente lista describe cómo administrar eventos de webhook:

Para probar los webhooks localmente, puedes utilizar la CLI de Stripe. Después de instalarla, puedes reenviar los eventos a tu servidor:

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

Más información sobre cómo configurar webhooks.

Cómo identificar cargos en un PaymentIntent

Cuando intentas cobrar un pago a un cliente, el PaymentIntent crea un Charge. Para obtener la ID del cargo más reciente, inspecciona la propiedad latest_charge del 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_4eC39HqLyjWDarjtT1zdp7dc'

intent = Stripe::PaymentIntent.retrieve('{{PAYMENT_INTENT_ID}}')
latest_charge = intent.latest_charge

Para ver todos los cargos asociados con un PaymentIntent, incluidos los cargos fallidos, haz una lista de todos los cargos y especifica el parámetro payment_intent​.

curl -G https://api.stripe.com/v1/charges \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d payment_intent=
{{PAYMENT_INTENT_ID}}

Cómo llevar a cabo las próximas acciones

Para completar el proceso de pago, algunos métodos de pago requieren pasos adicionales, como la autenticación. Stripe.js se encarga de estos pasos automáticamente una vez que se confirma el PaymentIntent, pero es posible que sea recomendable gestionarlos manualmente en algunas integraciones avanzadas.

La propiedad next_action del PaymentIntent exhibe el siguiente paso que tu integración debe gestionar para efectivizar el pago. El tipo de las próximas acciones posibles puede diferir según cada método de pago. Puedes encontrar una lista completa de estas acciones en la documentación de la API.

Puedes consultar la documentación sobre los métodos de pago para obtener más detalles sobre cómo gestionar las próximas acciones requeridas.