# Actualizaciones del estado del pago

Controla y verifica el estado del pago para poder responder tanto a los pagos realizados correctamente como a los fallidos.

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 que puedas tomar medidas comerciales o responder a estados que requieran mayor intervención.

También puedes usar el Dashboard de Stripe para configurar tu cuenta para que te envíe un correo electrónico sobre el estado de un pago, como 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).

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

A continuación, indicamos algunos de los posibles resultados al utilizar la función `confirmCardPayment`:

| **Evento**                    | **Qué ha ocurrido**                                                       | **Integración prevista**                                                        |
| ----------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Resuelve con un PaymentIntent | El cliente completó el pago en la página de proceso de compra             | Informa al cliente de que el pago se efectuó correctamente                      |
| Resuelve con un error         | El pago del cliente no pudo completarse en la página de proceso de compra | Muestra un mensaje de error y solicita al cliente que vuelva a intentar el pago |

La promesa devuelta por `confirmCardPayment` se resuelve cuando el proceso de pago finaliza o falla con un error. Cuando se completa con éxito y devuelve un PaymentIntent, el estado siempre será `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 adicional, como la autenticación, la promesa no se resuelve hasta que se completa ese paso o se agota el tiempo de espera.

## Comprueba 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 pasando el *secreto del 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é ha ocurrido**                                                       | **Estado previsto del PaymentIntent** |
| ------------------------------------------------------------------------- | ------------------------------------- |
| El cliente completó el pago en la página de proceso de compra             | `succeeded`                           |
| El cliente no completó el proceso de compra                               | `requires_action`                     |
| El pago del cliente no pudo completarse en la página de proceso de compra | `requires_payment_method`             |

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

## Supervisa un PaymentIntent con webhooks

Stripe puede enviar eventos de *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) a tu servidor para notificarte los cambios que se produzcan en el estado de un PaymentIntent. Esto resulta útil, por ejemplo, para determinar cuándo entregar bienes y servicios.

No intentes gestionar *la ejecución de pedidos* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) del lado del cliente porque el cliente puede salir de la página después de efectuar el pago, pero antes de que se inicie el proceso de ejecución de pedidos. En lugar de iniciarlo del lado del cliente, utiliza webhooks para supervisar el evento `payment_intent.succeeded` y gestionar la ejecución del pedido de forma asincrónica.

> Aunque es posible usar el sondeo en lugar de webhooks para supervisar los cambios provocados por las operaciones asincrónicas (es decir, recuperar repetidamente un PaymentIntent para que puedas comprobar su estado), esto es mucho menos fiable y puede causar problemas de limitación de velocidad. Stripe aplica [límites de velocidad](https://docs.stripe.com/testing.md#rate-limits) en las solicitudes de API, así que ten cuidado si usas el sondeo.

Para gestionar un evento de webhook, crea una ruta en tu servidor y configura el punto de conexión de webhook correspondiente [en el Dashboard](https://dashboard.stripe.com/account/webhooks). Stripe envía el evento `payment_intent.succeeded` cuando el pago se realiza correctamente y el evento `payment_intent.payment_failed` cuando el 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 encontrar más detalles si inspeccionas la propiedad `last_payment_error` del PaymentIntent. Asimismo, puedes notificar al cliente que el pago no se completó y animarlo a intentarlo de nuevo con otro método de pago. Reutiliza el mismo PaymentIntent para continuar el seguimiento de la compra del cliente.

### Cómo gestionar eventos de webhook específicos

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

| Evento                      | Descripción                                                                                                                                                                                                  | Siguientes pasos                                                                                                                       |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `processing`                | El pago del cliente se envió a Stripe correctamente. 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 hizo efectivo o no.                                                                          |
| `succeeded`                 | El pago del cliente se ha realizado correctamente.                                                                                                                                                           | Completa el pedido de los productos o servicios comprados.                                                                             |
| `amount_capturable_updated` | Se autorizó el pago del cliente y está listo para la captura.                                                                                                                                                | Captura los fondos disponibles para el pago.                                                                                           |
| `payment_failed`            | La red de tarjeta rechazó el pago del cliente o este caducó.                                                                                                                                                 | Contacta con el cliente mediante un correo electrónico o una notificación emergente, 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)
```

Obtén 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 [cargo](https://docs.stripe.com/api/charges.md). Para obtener el 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.
Stripe.api_key = '<<YOUR_SECRET_KEY>>'

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](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 siguientes 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 al confirmar el PaymentIntent, pero si tiene una integración avanzada, puede que sea recomendable gestionarlos de forma manual.

La propiedad [next_action](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action) del PaymentIntent muestra el siguiente paso que tu integración debe llevar a cabo para completar el pago. El tipo de próximas acciones posibles puede variar entre los distintos métodos de pago. Puedes encontrar una lista completa de las próximas acciones posibles 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 información sobre cómo gestionar las próximas acciones necesarias.