# Actualizaciones del estado del pago

Supervisa y verifica el estado del pago para que puedas responder a pagos realizados correctamente o que fallaron.

Los *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) 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](https://docs.stripe.com/get-started/account/teams.md#email-notifications) en tu [configuración de usuario](https://dashboard.stripe.com/settings/user).

## Comprobar el estado del PaymentIntent del lado del cliente

Cuando el cliente completa un pago con la función [confirmCardPayment](https://docs.stripe.com/js.md#stripe-confirm-card-payment), puedes inspeccionar el PaymentIntent devuelto para determinar su estado actual:

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

| **Evento**                    | **Qué ocurrió**                                                                 | **Integración prevista**                                                      |
| ----------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Resuelve con un PaymentIntent | El cliente completó el pago en la página de finalización de compra              | Notifica al cliente que el pago se realizó correctamente                      |
| Resuelve con un error         | No se pudo completar el pago del cliente en la página de finalización de compra | Muestra un mensaje de error y pídele al cliente que vuelva a intentar el pago |

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](https://docs.stripe.com/payments/place-a-hold-on-a-payment-method.md)). 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](https://docs.stripe.com/js/payment_intents/retrieve_payment_intent) y transfiriendo el *secreto de 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
  }
})();
```

Estos son algunos de los [posibles estados](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-status) del PaymentIntent después de una confirmación:

| **Qué ocurrió**                                                                 | **Estado previsto del PaymentIntent** |
| ------------------------------------------------------------------------------- | ------------------------------------- |
| El cliente completó el pago en la página de finalización de compra              | `succeeded`                           |
| El cliente no completó el proceso de finalización de compra                     | `requires_action`                     |
| No se pudo completar el pago del cliente en la página de finalización de compra | `requires_payment_method`             |

[Obtén más información sobre los estados de PaymentIntent](https://docs.stripe.com/payments/paymentintents/lifecycle.md).

## Supervisar un PaymentIntent con webhooks

Stripe puede enviar eventos de *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) 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.

> Si bien es técnicamente posible usar el sondeo en lugar de los webhooks para monitorear los cambios provocados por las operaciones asíncronas (es decir, recuperar repetidamente un PaymentIntent para comprobar su estado), hacerlo es mucho menos confiable y puede causar problemas de limitación de frecuencia. Stripe aplica [limitaciones de frecuencia](https://docs.stripe.com/testing.md#rate-limits) en las solicitudes de API, así que ten cuidado si decides usar el sondeo.

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](https://dashboard.stripe.com/account/webhooks). 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:

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

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:

| Evento                      | Descripción                                                                                                                                                                                              | Próximos pasos                                                                                                                 |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `processing`                | El pago del cliente se envió a Stripe con éxito. Solo se aplica a métodos de pago con [notificación de confirmación diferida](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Espera hasta saber si el pago iniciado se efectuó con éxito o no.                                                              |
| `succeeded`                 | El pago del cliente se efectuó correctamente.                                                                                                                                                            | Entrega los productos o servicios comprados.                                                                                   |
| `amount_capturable_updated` | Se autorizó el pago del cliente y está listo para su captura.                                                                                                                                            | Captura los fondos disponibles para el pago.                                                                                   |
| `payment_failed`            | El pago del cliente fue rechazado por una red de tarjetas o expiró.                                                                                                                                      | Contacta al cliente enviándole un correo electrónico o una notificación push y solicítale que proporcione otro método de pago. |

Para probar los webhooks localmente, puedes utilizar [la CLI de Stripe](https://docs.stripe.com/stripe-cli.md). Después de instalarla, puedes reenviar los eventos a tu servidor:

```bash
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](https://docs.stripe.com/webhooks.md).

## Cómo identificar cargos en un PaymentIntent

Cuando intentas cobrar un pago a un cliente, el PaymentIntent crea un [Charge](https://docs.stripe.com/api/charges.md). Para obtener la ID del cargo más reciente, inspecciona la propiedad [latest_charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge) del 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 todos los cargos asociados con un PaymentIntent, incluidos los cargos fallidos, [haz una lista de todos los cargos](https://docs.stripe.com/api/charges/list.md#list_charges-payment_intent) y especifica el parámetro `payment_intent​`.

```curl
curl -G https://api.stripe.com/v1/charges \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "payment_intent={{PAYMENTINTENT_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](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-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](https://docs.stripe.com/api.md#payment_intent_object-next_action-type).

Puedes consultar la [documentación sobre los métodos de pago](https://docs.stripe.com/payments/payment-methods/overview.md) para obtener más detalles sobre cómo gestionar las próximas acciones requeridas.