Aceptar pagos con OXXO

Cómo aceptar pagos con OXXO, un método de pago muy usado en México.

Web

Móvil

Precaución

El contenido de esta sección se refiere a un producto heredado. En cambio, debes usar la guía Aceptar un pago para la ruta de integración más reciente. Si bien Stripe aún admite este producto, el soporte podría finalizar si el producto queda obsoleto.

En México, los usuarios de Stripe pueden aceptar pagos OXXO de clientes en México usando las API Payment Intents y Payment Methods. Los clientes abonan presentando un vale OXXO con un número y el pago en efectivo efectuado en una tienda OXXO de 24 horas. Stripe te notifica cuando se completa el pago.

Lo que estás creando

Nombre

Correo electrónico

Configurar Stripe
Lado del servidor

Primero, necesitas una cuenta de Stripe. Inscríbete ahora.

Usa nuestras bibliotecas oficiales para acceder a la API de Stripe desde tu aplicación:

Crear un PaymentIntent
Lado del servidor

Stripe usa un objeto PaymentIntent para representar tu intención de cobrar a un cliente y hace el seguimiento de los cambios de estado desde la creación del vale OXXO hasta que se completa el pago.

Crea un PaymentIntent en tu servidor con un importe en mxn (OXXO no acepta otras monedas). Si ya tienes una integración con la API Payment Intents, agrega oxxo a la lista de tipos de métodos de pago de tu PaymentIntent.

Recuperar el secreto de cliente

El PaymentIntent incluye un secreto de cliente que el lado del cliente usa para completar el proceso de pago de forma segura. Puedes usar diferentes métodos para pasar el secreto del cliente al lado del cliente.

Recupera el secreto de cliente de un punto de conexión de tu servidor con la funcionalidad fetch del navegador. Este método es más conveniente si tu lado del cliente es una aplicación de una sola página, especialmente, si fue diseñada con un marco de front-end moderno como React. Crea el punto de conexión del servidor que se usa para el secreto de cliente:

Luego recupera el secreto de cliente con JavaScript del lado del cliente:

(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();

Opciones de métodos de pago adicionales

Puedes especificar un parámetro opcional expires_after_days en las opciones de métodos de pago de tu PaymentIntent que define la cantidad de días calendario que deben pasar para que venza el vale de OXXO. Por ejemplo, si creas un vale de OXXO un lunes y defines expires_after_days en 2, el vale vencerá el miércoles a las 23:59, hora de América/Sao_Paulo (UTC-3). El parámetro expires_after_days puede ser de 1 a 7 días. El valor predeterminado es de 3 días.

Recopilar datos del método de pago
Lado del cliente

Crea un formulario de pago del lado de tu cliente para recopilar los datos de facturación necesarios:

Campo	Valor
`name`	El nombre completo (nombre y apellido) del cliente. Tanto el nombre como el apellido deben tener al menos dos caracteres cada uno.
`email`	La dirección de correo electrónico completa del cliente.

checkout.html
<form id="payment-form">
  <div class="form-row">
    <label for="name">
      Name
    </label>
    <input id="name" name="name" required>
  </div>

  <div class="form-row">
    <label for="email">
      Email
    </label>
    <input id="email" name="email" required>
  </div>

  <!-- Used to display form errors. -->
  <div id="error-message" role="alert"></div>

  <button id="submit-button">Pay with OXXO</button>
</form>

Enviar el pago a Stripe
Lado del cliente

Cuando el cliente hace clic para pagar con OXXO, usa Stripe.js para enviar el pago a Stripe. Stripe.js es nuestra biblioteca principal de JavaScript para crear flujos de pago.

Incluye el script de Stripe.js en tu página de finalización de compra agregándolo al head de tu archivo HTML.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
</head>

Crea una instancia de Stripe.js con el siguiente JavaScript en tu página de pago.

client.js
// Set your publishable key. Remember to switch to your live publishable key in production!
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

Usa stripe.confirmOxxoPayment y el secreto de cliente del objeto PaymentIntent que creaste en el Paso 2 para enviar los datos de pagos del cliente.

Una vez recibida la confirmación, Stripe abrirá automáticamente un cuadro de diálogo para mostrar el vale OXXO al cliente.

client.js
const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const result = await stripe.confirmOxxoPayment(
    '{{PAYMENT_INTENT_CLIENT_SECRET}}',
    {
      payment_method: {
        billing_details: {
          name: document.getElementById('name').value,
          email: document.getElementById('email').value,
        },
      },
    });
  // Stripe.js will open a modal to display the OXXO voucher to your customer
  // This async function finishes when the customer closes the modal

  if (result.error) {
    // Display error to your customer
    const errorMsg = document.getElementById('error-message');
    errorMsg.innerText = result.error.message;
  }
});

Nota

stripe.confirmOxxoPayment puede tardar varios segundos en completarse. Durante ese tiempo, deshabilita tu formulario para no reenviarlo y muestra un indicador de espera, por ejemplo, un indicador giratorio. Si recibes un mensaje de error, muéstraselo al cliente, vuelve a habilitar el formulario y oculta el indicador de espera.

Cuando se crea un vale de OXXO correctamente, el valor de la propiedad status del PaymentIntent devuelto es requires_action. Comprueba el estado del PaymentIntent en el Dashboard o examina la propiedad de estado del objeto. Si el vale OXXO no se creó correctamente, revisa el mensaje de error recibido para determinar la causa (por ejemplo, formato de correo electrónico no válido).

Opcional: enviar al cliente el enlace del vale por correo electrónico

Stripe envía un evento payment_intent.requires_action cuando el vale de OXXO se crea correctamente. Si necesitas enviar a tus clientes el enlace del vale por correo electrónico, puedes recuperar el PaymentIntent para obtener el enlace al recibir el evento. El campo hosted_voucher_url en payment_intent.next_action.oxxo_display_details contiene el enlace para acceder al vale.

Opcional: personalizar tu vale

Stripe permite la personalización de las interfaces de usuario del cliente en la página de configuración de imagen de marca.

La siguiente configuración de marca puede aplicarse al vale:

Ícono: tu imagen de marca y el nombre público de la empresa
Color de énfasis: se utiliza como color del botón Copiar número
Color de la marca: se utiliza como color de fondo

Gestionar eventos posteriores al pago
Lado del servidor

OXXO es un método de pago con notificación diferida, de manera que los fondos no están disponibles de inmediato. Es posible que el cliente no pague el vale en una tienda de 24 horas inmediatamente después de realizar la compra.

Stripe envía un evento payment_intent.succeeded el siguiente día hábil (de lunes a viernes, excepto que sea día feriado en México) por cada vale de OXXO pagado. Utiliza el Dashboard o crea un controlador de webhooks para recibir estos eventos y ejecutar acciones (por ejemplo, enviar un correo electrónico de confirmación del pedido a tu cliente, registrar la venta en una base de datos o iniciar el flujo de envío).

Después de la fecha de vencimiento, el estado del PaymentIntent pasa a ser processing, y el cliente ya no puede pagar el vale de OXXO vencido. Si este vale no se paga antes de las 23:59, hora de América/Mexico_City (UTC-6) del día del vencimiento, Stripe envía un evento payment_intent.payment_failed dentro de los 10 días calendario posteriores a la fecha de vencimiento (en la mayoría de los casos, el evento se envía dentro de los 7 días calendario). Por ejemplo, si el vale de OXXO vence el 1 de septiembre, este evento se envía el 10 de septiembre a más tardar.

Evento	Descripción	Próximos pasos
`payment_intent.requires_action`	El vale OXXO se creó correctamente.	Espera a que el cliente pague el vale OXXO.
`payment_intent.processing`	El cliente ya no puede pagar el vale OXXO.	Espera hasta saber si el pago se concreta o no.
`payment_intent.succeeded`	El cliente pagó el vale OXXO antes del vencimiento.	Entrega los bienes o servicios que el cliente compró.
`payment_intent.payment_failed`	El cliente no pagó el vale OXXO antes del vencimiento.	Comunícate con el cliente por correo electrónico o envía una notificación push y solicítale otro método de pago.

Recibir eventos y realizar operaciones comerciales

Manualmente

Utiliza el Dashboard de Stripe para ver todos tus pagos en Stripe, enviar recibos por correo electrónico, gestionar transferencias o reintentar pagos fallidos.

Visualiza tus pagos de prueba en el Dashboard

Código personalizado

Crea un controlador de webhooks para escuchar eventos y crear flujos de pago asincrónicos personalizados. Prueba y depura tu integración de webhooks en forma local con la CLI de Stripe.

Crea un webhook personalizado

Probar la integración

En el entorno de prueba, establece payment_method.billing_details.email en los siguientes valores cuando llames a stripe.confirmOxxoPayment para probar diferentes escenarios.

Correo electrónico	Descripción
`{any_prefix}@{any_domain}`	Simula un vale OXXO abonado por el cliente al cabo de 3 minutos con el webhook `payment_intent.succeeded` recibido después de 3 minutos. En modo activo, este webhook llega después de 1 día hábil. Ejemplo: fulano@test.com
`{any_prefix}succeed_immediately@{any_domain}`	Simula un vale OXXO abonado por el cliente de inmediato con el webhook `payment_intent.succeeded` recibido después de unos segundos. En modo activo, este webhook llega después de 1 día hábil. Ejemplo: succeed_immediately@test.com
`{any_prefix}expire_immediately@{any_domain}`	Simula un vale OXXO que venza antes de que pague el cliente con el webhook `payment_intent.payment_failed` recibido después de unos segundos. El campo `expires_after` en next_action.oxxo_display_details está establecido en la hora actual, independientemente de cómo esté definido el parámetro `expires_after_days` en opciones de métodos de pago. Ejemplo: expire_immediately@test.com
`{any_prefix}expire_with_delay@{any_domain}`	Simula un vale OXXO que venza antes de que pague el cliente con el webhook `payment_intent.payment_failed` recibido después de 3 minutos. El campo `expires_after` en next_action.oxxo_display_details se establece en 3 minutos, independientemente de cómo esté definido el parámetro `expires_after_days` en opciones de métodos de pago. Ejemplo: expire_with_delay@test.com
`{any_prefix}fill_never@{any_domain}`	Simula un vale OXXO que venza antes de que pague el cliente con el webhook `payment_intent.payment_failed` recibido después de 1 día hábil y 2 días calendario. En modo activo, este webhook llega a la misma hora que en modo de prueba. Ejemplo: fill_never@test.com

OpcionalMuestra los datos de OXXO a tu cliente
Lado del cliente

OpcionalEnviar correos electrónicos con instrucciones de pago

Vencimiento y cancelación

Los vales OXXO vencen después de la marca de tiempo UNIX expires_after, y el cliente ya no puede pagar un vale una vez vencido. Los vales OXXO no se pueden cancelar antes de su vencimiento.

Después del vencimiento del vale OXXO, el estado del PaymentIntent cambia a requires_payment_method. A estas alturas, puedes confirmar el PaymentIntent con otro método de pago o cancelarlo.