Mejores prácticas para usar SourcesObsoleto

La flexibilidad de la API Sources te ayuda a minimizar los cambios necesarios para admitir otros métodos de pago mientras los añades.

Flujo habitual para los pagos con tarjeta

En un flujo habitual del proceso de compra para pagos con tarjeta (sin incluir 3D Secure), tu integración recopila información de la tarjeta y crea una fuente, y la utiliza para hacer una solicitud de cargo. Dado que no requiere ninguna medida adicional por parte del cliente y los pagos con tarjeta ofrecen una confirmación sincrónica, podemos confirmar de inmediato si el pago es satisfactorio y que los fondos están garantizados; no es necesario usar webhooks.

El uso obligatorio de webhooks

Es posible que otros métodos de pago requieran que tu cliente tome medidas adicionales (por ejemplo, un redireccionamiento) antes de que la fuente pase a ser chargeable y pueda usarse para hacer una solicitud de cargo (por ejemplo, iDEAL). Esta transición suele ser asíncrona y puede incluso ocurrir después de que el cliente abandone tu sitio web. Por estos motivos, tu integración debe recurrir a los webhooks para determinar el momento en el que una fuente pasa a ser cobrable antes de crear un cargo.

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

De la misma manera, al crear un cargo, algunos métodos de pago asíncronos pueden 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 del cargo:

Creación de una integración flexible

Para asegurarte de que tu proceso de compra es flexible y está listo para aceptar varios métodos de pago, te recomendamos el siguiente enfoque:

Creación de la fuente

Al crear Sources, registra el ID de la fuente en la representación interna de tu pedido para que puedas recuperar el pedido cuando recibas y proceses webhooks source.chargeable. Asegúrate de indexar los objetos de tu pedido en función del atributo de esta source para que la búsqueda sea eficaz.

Creación del cargo

Con la entrega del webhook source.chargeable, se cobra a la Source. Al recibir el webhook, recupera la representación interna de tu pedido mediante una búsqueda basada en el ID de la fuente recibido y verifica que el pedido está a la espera de pago.

Al hacer una solicitud de un cargo, utiliza tu ID interno del pedido como clave de idempotencia para evitar posibles conflictos. Asimismo, si la fuente es reutilizable y quieres reutilizarla, asegúrate de vincularla a un Customer antes de cargarla. Consulta las guías de Reutilizables o de un solo uso y de Sources y Customers para obtener más información sobre cómo gestionar las Sources de un solo uso o reutilizables y sobre cómo interactuar con Customers.

De manera similar a la creación de la fuente, registra el ID del cargo en la representación interna de tu pedido para que puedas recuperar el pedido cuando recibas y proceses webhooks charge.succeeded.

Página de confirmación

Después de que tu cliente tome las medidas necesarias para autorizar un pago (por ejemplo, ha seguido un redireccionamiento), deberías presentar una página de confirmación en la que se muestre el estado del pedido. Puedes hacerlo sondeando el pedido internamente.

Como la latencia de la entrega del webhook no está garantizada, si quieres seguir acelerando tu página de confirmación, puedes sondear el estado de la Source asociada en el código del lado del cliente. Cuando detectes que tu Source se ha convertido en chargeable, puedes iniciar la creación de un Charge usando dicha Source sin esperar a que llegue el webhook source.chargeable.

Ten en cuenta que algunos tipos de Sources tardan minutos (e incluso días) en convertirse en chargeable. Si decides sondear la Source, te recomendamos que pares en algún momento y que le comuniques al cliente que su pedido está a la espera de confirmación del pago; luego, envíale un correo electrónico con la confirmación del pago de forma asíncrona. Puedes consultar nuestra mensajería recomendada para clientes para cada estado de la Source en la tabla que aparece a continuación.

Los sondeos del lado del cliente se detienen si el cliente abandona tu página. Esto significa que también debes integrarlo con el webhook source.chargeable para asegurarte de que no pierdes el seguimiento del pedido de tu cliente.

Si utilizas Stripe.js, puedes usar stripe.retrieveSource() para implementar 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();

La tabla que aparece a continuación contiene recomendaciones para mensajes para posibles clientes que puedes mostrar en función del estado de la Source.

Tras crear un Charge (y en caso de que el usuario siga en la página de confirmación), puedes mostrar los siguientes mensajes en función del estado del Charge:

Confirmación del pedido

Confirma tu pedido solo después de que hayas recibido el webhook charge.succeeded (esto puede ocurrir de forma instantánea, pero también es posible que no sea así). Envía un correo electrónico al cliente en este punto porque la confirmación del pago puede tardar días en el caso de pagos asíncronos.

Cancelaciones y errores

Escucha los webhooks source.canceled y source.failed, y asegúrate de cancelar el pedido asociado a la fuente correspondiente. Si sigues las mejores prácticas indicadas anteriormente, no deberías recibir un source.canceled webhook para fuentes que antes eran chargeable (ya que el gestor de tu source.chargeable debería haber creado un cargo inmediatamente, evitando así que la fuente se cancele). Igualmente, recibirás webhooks source.canceled para fuentes que nunca han sido chargeable y que se mantienen como pending, que, por lo general, suele indicar que tu cliente ha abandonado el flujo del proceso de compra anticipadamente. También puedes recibir un webhook source.failed cuando el Customer rechace el pago o cuando haya un error técnico en el esquema del pago.

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

Para cada uno de estos eventos, te recomendamos que notifiques a tu cliente que ha habido un error con el pedido y lo invites a volver a tu flujo de pago si lo desea.