Mejores prácticas para usar SourcesObsoleto

Prácticas recomendadas para aceptar diversos métodos de pago a través de una sola integración.

Advertencia

We deprecated the Sources API and plan to remove support for local payment methods. If you currently handle any local payment methods using the Sources API, you must migrate them to the Payment Methods API.

While we don’t plan to remove support for card payments, we recommend replacing any use of the Sources API with the PaymentMethods API, which provides access to our latest features and payment method types.

La flexibilidad de la API Sources te ayuda a minimizar los cambios necesarios para aceptar otros métodos de pago a medida que los agregas.

Flujo típico de pagos con tarjeta

En un flujo de compra típico para pagos con tarjeta (excepto con 3D Secure), tu integración recopila información de la tarjeta y crea una fuente que utiliza para hacer una solicitud de pago. Debido a que no se requiere ninguna otra acción por parte del cliente y a que los pagos con tarjeta brindan confirmación sincrónica, podemos confirmar si el pago se hizo correctamente y si los fondos están garantizados en el momento; el uso de webhooks no es necesario.

El uso obligatorio de webhooks

Otros métodos de pago pueden solicitar al cliente que lleve a cabo una acción adicional (por ejemplo, un redireccionamiento) para que la fuente pase a ser chargeable y se pueda utilizar para hacer una solicitud de pago (como iDEAL). En general, esta transición es asincrónica e incluso puede concretarse después de que el cliente deja tu sitio web. Por ese motivo, tu integración debe basarse en webhooks para determinar si se pueden hacer cargos en la fuente antes de crearlos.

Stripe envía los siguientes eventos de webhook para notificarte sobre los cambios en el estado de la fuente:

Evento	Descripción	Acción sugerida
`source.chargeable`	El estado del objeto Source pasa a ser `chargeable` después de que el cliente autentica y verifica el pago.	Crea un objeto Charge.
`source.failed`	El estado del objeto Source no pasó a cobrable porque el cliente se negó a autenticar el pago.	Cancela el pedido y, si quieres, vuelve a invitar al cliente a tu flujo de pago.
`source.canceled`	El objeto Source venció y no se puede usar para crear un cargo.	Cancela el pedido y, si quieres, vuelve a invitar al cliente a tu flujo de pago.

De la misma manera, al crear un cargo, algunos métodos de pago asincrónicos podrían tardar días en confirmar los fondos y efectuar el pago, lo que exige que los webhooks sepan cuándo confirmar y, finalmente, cuándo completar el pedido.

Stripe envía los siguientes eventos de webhook para notificarte sobre los cambios en el estado de un cargo:

Evento	Descripción	Acción sugerida
`charge.pending`	El cargo está pendiente (pagos asincrónicos únicamente).	No se requiere acción alguna.
`charge.succeeded`	El cargo se hizo correctamente y se completó el pago.	Finaliza el pedido y envía una confirmación al cliente por correo electrónico.
`charge.failed`	El cargo falló y no pudo completarse el pago.	Cancela el pedido y, si quieres, vuelve a invitar al cliente a tu flujo de pago.

Cómo crear una integración flexible

Para garantizar que tu proceso de finalización de compra sea flexible y esté preparado para aceptar varios métodos de pago, te recomendamos el siguiente enfoque:

Creación de un objeto Source

Al crear Sources, debes registrar el ID de la fuente en tu representación interna del pedido para poder recuperar el pedido cuando recibas y proceses webhooks source.chargeable. Asegúrate de indexar los objetos Order basándote en este atributo source para que la búsqueda sea eficiente.

Creación de un cargo

El envío del webhook source.chargeable genera un cargo en el objeto Source. Al recibir el webhook, recupera tu representación interna del pedido mediante una búsqueda basada en el ID de fuente recibido y verifica que el pedido esté a la espera de pago.

Al hacer una solicitud de pago, usa tu ID interna de pedido como clave de idempotencia para evitar cualquier posible condición de carrera. Además, si la fuente es reutilizable y quieres volver a usarla, asegúrate de adjuntarla a un objeto Customer antes de hacer el cargo. Consulta las guías sobre fuentes de un solo uso y reutilizables y Fuentes y clientes para obtener más información sobre cómo administrar los objetos Sources de un solo uso y reutilizables, y cómo interactúan con los objetos Customers.

Al igual que al crear fuentes, registra el ID del cargo en tu representación interna del pedido para poder recuperar el pedido cuando recibas y proceses webhooks charge.succeeded.

Página de confirmación

Después de que el cliente toma las medidas necesarias para autorizar el pago (por ejemplo, siguió el redireccionamiento a otro sitio), debe abrirse una página de confirmación que muestre el estado del pedido. Puedes hacerlo sondeando el pedido internamente.

Debido a que no está garantizada la latencia del envío del webhook, si quieres optimizar aún más tu página de confirmación, puedes sondear el estado del objeto Source asociado, en el código de lado del cliente. Al detectar que el objeto Source es chargeable, puedes iniciar la creación del objeto Charge usando ese objeto Source sin esperar a que llegue el webhook source.chargeable.

Ten en cuenta que algunos objetos Source tardan minutos (e incluso días) en pasar a ser chargeable. Si decides sondear el objeto Source, te recomendamos hacer una pausa en algún punto para explicarle al cliente que el pedido está a la espera de la confirmación del pago y luego enviarle un correo electrónico con la confirmación de manera asincrónica. En la siguiente tabla, puedes ver los mensajes que recomendamos enviar al cliente según el estado del objeto Source.

El sondeo de lado del cliente se interrumpe si el cliente abandona tu página, es decir, que también debes tener en cuenta el webhook source.chargeable para asegurarte de no perder el rastro del pedido del cliente.

Si usas Stripe.js, puedes usar stripe.retrieveSource() para hacer tu propio sondeo:

// In order-confirmation-page.js

const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

// After some amount of time, we should stop trying to resolve the order synchronously:
const MAX_POLL_COUNT = 10;
let pollCount = 0;

const pollForSourceStatus = async () => {
  const {source} = await stripe.retrieveSource({id: SOURCE_ID, client_secret: CLIENT_SECRET})
  if (source.status === 'chargeable') {
    // Make a request to your server to charge the Source.
    // Depending on the Charge status, show your customer the relevant message.
  } else if (source.status === 'pending' && pollCount < MAX_POLL_COUNT) {
    // Try again in a second, if the Source is still `pending`:
    pollCount += 1;
    setTimeout(pollForSourceStatus, 1000);
  } else {
    // Depending on the Source status, show your customer the relevant message.
  }
};

pollForSourceStatus();

En la siguiente tabla, se ofrecen recomendaciones relacionadas con los posibles mensajes que puedes enviar al cliente según el estado del objeto Source.

Estado	Mensajes para el cliente
El estado de la fuente es `chargeable`	Se recibió el pedido y se espera la confirmación del pago.
El estado de la fuente es `canceled`	Falló el pago y no se pudo procesar el pedido.
La estado de la fuente es `failed`	Falló el pago y no se pudo procesar el pedido.
La fuente sigue `pending` después de un tiempo de sondeo	Se recibió el pedido y se espera la confirmación del pago.

Después de crear el Charge (y si el usuario sigue en tu página de confirmación), puedes presentar los siguientes mensajes según el estado del objeto Charge:

Estado	Mensajes para el cliente
El estado del cargo es `pending`	Se recibió el pedido y se espera la confirmación del pago.
El estado del cargo es `failed`	Falló el pago y no se pudo procesar el pedido.
El estado del cargo es `succeeded`	Se confirmó el pago y se completó el pedido.

Confirmación del pedido

Confirma el pedido solo después de recibir el webhook charge.succeeded (lo que puede suceder al instante o no). En esta etapa, envía un correo electrónico al cliente porque la confirmación puede demorar días si el pago es asincrónico.

Cancelaciones y errores

Escucha los webhooks source.canceled y source.failed y asegúrate de cancelar el pedido asociado con la fuente correspondiente. Si sigues las buenas prácticas mencionadas arriba, no deberías recibir webhooks source.canceled por fuentes que ya fueron chargeable (pues el controlador source.chargeable debería haber creado un cargo enseguida para que no se pudiera cancelar la fuente). En cambio, recibirás webhooks source.canceled por fuentes cuyo estado haya quedado pending y nunca haya sido chargeable, lo que generalmente indica que tu cliente abandonó el flujo de compra antes. También puedes recibir webhooks source.failed cuando el cliente rechaza el pago o se produce un error técnico en la red de pagos.

También debes escuchar los webhooks charge.failed para asegurarte de cancelar el pedido asociado con el cargo recibido.

Para cada uno de estos eventos, te recomendamos que le notifiques al cliente que hubo un error en el pedido y que lo invites a regresar al flujo de compra, si lo desea.