Aceptar pagos con OXXO

Lado del servidor

Esta integración necesita puntos de conexión en tu servidor que se comuniquen con la API de Stripe. Usa nuestras bibliotecas oficiales para acceder a la API de Stripe desde tu servidor:

# Available as a gem
sudo gem install stripe

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Lado del cliente

El SDK para React Native es de código abierto y está plenamente documentado. Internamente, utiliza SDK para iOS nativo y Android. Para instalar el SDK para React Native de Stripe, ejecuta uno de los siguientes comandos en el directorio del proyecto (según el administrador de paquetes que utilices):

yarn add @stripe/stripe-react-native

A continuación, instala otras dependencias necesarias:

• Para iOS, navega hasta el directorio de ios y ejecuta pod install para asegurarte de instalar también las dependencias nativas necesarias.
• Para Android, no hay más dependencias para instalar.

Inicialización de Stripe

Para inicializar Stripe en tu aplicación React Native, ajusta tu pantalla de pago con el componente StripeProvider o usa el método de inicialización initStripe. Solo se requiere la clave publicable de la API en publishableKey. El siguiente ejemplo muestra cómo inicializar Stripe usando el componente StripeProvider.

import React, { useState, useEffect } from 'react';
import { StripeProvider } from '@stripe/stripe-react-native';

function App() {
  const [publishableKey, setPublishableKey] = useState('');

  const fetchPublishableKey = async () => {
    const key = await fetchKey(); // fetch key from your server here
    setPublishableKey(key);
  };

  useEffect(() => {
    fetchPublishableKey();
  }, []);

  return (
    <StripeProvider
      publishableKey={publishableKey}
      merchantIdentifier="merchant.identifier" // required for Apple Pay
      urlScheme="your-url-scheme" // required for 3D Secure and bank redirects
    >
      // Your app code here
    </StripeProvider>
  );
}

Un PaymentIntent es un objeto que representa tu intención de cobrar a un cliente y hace el seguimiento del ciclo de vida del proceso de pago en cada etapa.

Lado del servidor

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.

curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "amount"=1099 \
  -d "currency"="mxn" \
  -d "payment_method_types[]"="oxxo"

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.

Lado del cliente

Del lado del cliente, solicita un PaymentIntent desde tu servidor y almacena el secreto de cliente.

const fetchPaymentIntentClientSecret = async () => {
  const response = await fetch(`${API_URL}/create-payment-intent`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      email,
      currency: 'mxn',
      payment_method_types: ['oxxo'],
    }),
  });
  const {clientSecret, error} = await response.json();

  return {clientSecret, error};
};

En tu aplicación, recopila el nombre completo y la dirección de correo electrónico del cliente.

export default function OxxoPaymentScreen() {
  const [name, setName] = useState();
  const [email, setEmail] = useState();

  const handlePayPress = async () => {
    // ...
  };

  return (
    <Screen>
      <TextInput
        placeholder="Name"
        onChange={(value) => setName(value.nativeEvent.text)}
      />
      <TextInput
        placeholder="E-mail"
        onChange={(value) => setEmail(value.nativeEvent.text)}
      />
    </Screen>
  );
}

Recupera el secreto de cliente del PaymentIntent que creaste y llama a confirmPayment. Se abrirá una vista web para mostrar el vale OXXO.

export default function OxxoPaymentScreen() {
  const [name, setName] = useState();
  const [email, setEmail] = useState();

  const handlePayPress = async () => {
    const billingDetails: PaymentMethodCreateParams.BillingDetails = {
      name,
      email,
    };

    const { error, paymentIntent } = await confirmPayment(clientSecret, {
      paymentMethodType: 'Oxxo',
      paymentMethodData: {
        billingDetails,
      }
    });

    if (error) {
      Alert.alert(`Error code: ${error.code}`, error.message);
      console.log('Payment confirmation error', error.message);
    } else if (paymentIntent) {
      if (paymentIntent.status === PaymentIntents.Status.RequiresAction) {
        Alert.alert(
          'Success',
          `The OXXO voucher was created successfully. Awaiting payment from customer.`
        );
      } else {
        Alert.alert('Payment intent status:', paymentIntent.status);
      }
    }
  };

  return (
    <Screen>
      <TextInput
        placeholder="Name"
        onChange={(value) => setName(value.nativeEvent.text)}
      />
      <TextInput
        placeholder="E-mail"
        onChange={(value) => setEmail(value.nativeEvent.text)}
      />
    </Screen>
  );
}

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

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.

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

En el entorno de prueba, usa los siguientes correos electrónicos cuando llames a confirmPayment para probar diferentes escenarios.