Permite que las empresas de tu plataforma acepten pagos en forma directa

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

Lado del servidor

Esta integración necesita puntos de conexión en tu servidor que se comuniquen con la API de Stripe. Usa las 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, vaya al directorio ios y ejecute pod install para asegurarse de que también instala 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 { 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>
  );
}

Cuando un usuario (vendedor o proveedor de servicios) crea un cuenta en tu plataforma, crea una Cuenta de usuario (llamada cuenta conectada) para que puedas aceptar pagos y transferir fondos a su cuenta bancaria. Las cuentas conectadas representan a tu usuario en la API de Stripe y ayudan con la recopilación de los requisitos de onboarding para que Stripe pueda verificar la identidad del usuario. En el ejemplo de la plataforma para crear tiendas, la cuenta conectada representa a la empresa que configura su tienda en línea.

Paso 2.1: Crea una cuenta conectada y completa automáticamente la información del lado del servidor

Usa la API /v1/accounts para crear una cuenta conectada. Puedes crear la cuenta conectada utilizando los parámetros predeterminados de la cuenta conectada o especificando el tipo de cuenta.

curl -X POST https://api.stripe.com/v1/accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Si ya recopilaste información para tus cuentas conectadas, puedes completar automáticamente esa información en el objeto Account. Puedes completar previamente cualquier información de la cuenta, incluida la información personal y de la empresa, la información de la cuenta externa, etc.

El onboarding de Connect no solicita la información que se completó automáticamente. Sin embargo, sí le pide al titular de la cuenta que confirme la información completada automáticamente antes de aceptar el contrato de servicio de Connect.

Cuando pruebes la integración, completa automáticamente la información de la cuenta con los datos de prueba.

Paso 2.2: Crear un enlace de cuenta Server-side

Puedes crear un enlace de cuenta llamando a la API Account Links con los siguientes parámetros:

• account
• refresh_url
• return_url
• type = account_onboarding

curl https://api.stripe.com/v1/account_links \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  --data-urlencode refresh_url="https://example.com/reauth" \
  --data-urlencode return_url="https://example.com/return" \
  -d type=account_onboarding

Paso 2.3: Redirigir a tu usuario a la URL del enlace de cuenta Client-side

La respuesta a tu solicitud de Account Links incluye un valor para la clave url. Los enlaces de cuenta son temporales y de un solo uso, ya que otorgan acceso a los datos personales del usuario de la cuenta conectada. Si quieres completar previamente la información, debes hacerlo antes de generar el enlace de la cuenta. Después de crear el enlace para una cuenta Standard, no podrás leer ni escribir información para la cuenta. Envía esta URL a tu aplicación y ábrela en el navegador para que el usuario complete el flujo de onboarding de Connect.

Paso 2.4: Gestionar el caso de un usuario que vuelve a la plataforma Client-side

El onboarding de Connect te exige especificar una return_url y una refresh_url para gestionar todos los casos en los que se redirige al usuario a tu plataforma. Es importante implementarlas correctamente para brindarle la mejor experiencia al usuario. Puedes configurar un enlace profundo para permitir que la página web de Stripe redirija a los clientes automáticamente a tu aplicación.

return_url

Stripe redirige al usuario a esta URL cuando dicho usuario completa el flujo de onboarding de Connect. Esto no implica que se haya recopilado toda la información ni que no haya requisitos pendientes en la cuenta. Solo significa que se entró y se salió del flujo correctamente.

No se especifica ningún estado a través de esta URL. Después de redirigir al usuario a tu return_url, verifica el estado del parámetro details_submitted en su cuenta por medio de uno de los siguientes métodos:

• Escuchando los webhooks account.updated
• Llamando a la API Accounts e inspeccionando el objeto devuelto

refresh_url

Tu usuario será redirigido a la refresh_url en estos casos:

• Se venció el enlace (pasaron algunos minutos desde la creación del enlace)
• El usuario ya visitó el enlace (actualizó la página o se desplazó de página en el navegador)
• Tu plataforma ya no puede acceder a la cuenta
• La cuenta ha sido rechazada

La refresh_url debería activar un método en tu servidor para volver a llamar a la API Account Links con los mismos parámetros y redirigir al usuario al flujo de onboarding de Connect para crear una experiencia fluida.

Paso 2.5: Gestiona los casos de usuarios que no hayan completado el onboarding

Es posible que un usuario redirigido a tu return_url no haya completado el proceso de onboarding. Usa el punto de conexión /v1/accounts para recuperar la cuenta del usuario y comprueba si hay charges_enabled. Si la cuenta no ha finalizado todo el proceso de onboarding, proporciona indicaciones de interfaz de usuario para que el usuario pueda continuarlo más tarde. Podrá completar la activación de su cuenta con un nuevo enlace de cuenta (generado por tu integración). Puedes verificar el estado del parámetro details_submitted en su cuenta para ver si se completó el proceso de onboarding.

Visualiza tu configuración de métodos de pago y habilita los que quieras aceptar. Los pagos con tarjeta se habilitan de forma predeterminada, pero puedes habilitarlos y deshabilitarlos según sea necesario.

Esta integración usa tres objetos de la API de Stripe:

1. PaymentIntent: Stripe lo utiliza para representar tu intención de cobrarle a un cliente, haciendo el seguimiento de los intentos de cobro y de los cambios en el estado del pago a lo largo del proceso.

2. (Opcional) Cliente: Para configurar un método de pago para pagos futuros, debes adjuntarlo a un Cliente. Crea el “Customer Object” cuando tu cliente cree una cuenta en tu empresa. Si tu cliente hace un pago como invitado, puedes crear un “Customer Object” antes del pago y asociarlo con tu propia representación interna de la cuenta del cliente más adelante.

3. (Opcional) Clave efímera del cliente: la información que contiene el Customer Object es confidencial y no se puede recuperar directamente desde una aplicación. Una clave efímera le otorga al SDK acceso temporal al cliente.

Por motivos de seguridad, tu aplicación no puede crear estos objetos. En su lugar, agrega un punto de conexión en tu servidor que haga lo siguiente:

1. Recupere el objeto Customer o cree uno nuevo.
2. Cree una Ephemeral Key para el objeto Customer.
3. Crea una PaymentIntent con el importe, la moneda y el cliente. También puedes incluir opcionalmente el parámetro automatic_payment_methods. Stripe habilita su funcionalidad de forma predeterminada en la última versión de la API.
4. Devuelve a tu aplicación el secreto de cliente del Payment Intent, el secret de la clave efímera, la ID del cliente y tu clave publicable.

Los métodos de pago que se muestran a los clientes durante el proceso de compra también se incluyen en el PaymentIntent. Puedes permitir que Stripe extraiga los métodos de pago de tu configuración del Dashboard o puedes enumerarlos manualmente. Independientemente de la opción que elijas, debes saber que la moneda especificada en el PaymentIntent filtra los métodos de pago que se muestran al cliente. Por ejemplo, si especificas eur en el PaymentIntent y tienes habilitado OXXO en el Dashboard, OXXO no se mostrará al cliente porque OXXO no admite pagos en eur.

A menos que tu integración requiera una opción basada en código para ofrecer métodos de pago, Stripe recomienda usar la opción automatizada. Esto se debe a que Stripe evalúa la moneda, las restricciones de los métodos de pago y otros parámetros para determinar la lista de métodos de pago admitidos. Se les da prioridad a los métodos de pago que aumentan la conversión y guardan mayor relación con la moneda y la ubicación del cliente.

# Create a Customer (use an existing Customer ID if this is a returning customer)
curl https://api.stripe.com/v1/customers \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -X "POST"

# Create an Ephemeral Key for the Customer
curl https://api.stripe.com/v1/ephemeral_keys \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -H "Stripe-Version: 2025-08-27.basil" \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \

# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
"
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="eur" \
  # In the latest version of the API, specifying the `automatic_payment_methods` parameter
  # is optional because Stripe enables its functionality by default.
  -d "automatic_payment_methods[enabled]"=true \
  -d application_fee_amount="123" \

Antes de mostrar el Payment Element móvil, tu página de finalización de compra debe cumplir con los siguientes requisitos:

• Mostrar los productos de la compra y el importe total
• Recopilar la información de envío necesaria
• Incluir un botón de pago para presentar la interfaz de usuario de Stripe

En la finalización de compra de tu aplicación, haz una solicitud de red al punto de conexión de back-end que creaste en el paso anterior y llama a initPaymentSheet desde el hook useStripe.

export default function CheckoutScreen() {
  const { initPaymentSheet, presentPaymentSheet } = useStripe();
  const [loading, setLoading] = useState(false);

  const fetchPaymentSheetParams = async () => {
    const response = await fetch(`${API_URL}/payment-sheet`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
    });
    const { paymentIntent, ephemeralKey, customer } = await response.json();

    return {
      paymentIntent,
      ephemeralKey,
      customer,
    };
  };

  const initializePaymentSheet = async () => {
    const {
      paymentIntent,
      ephemeralKey,
      customer,
    } = await fetchPaymentSheetParams();

    const { error } = await initPaymentSheet({
      merchantDisplayName: "Example, Inc.",
      customerId: customer,
      customerEphemeralKeySecret: ephemeralKey,
      paymentIntentClientSecret: paymentIntent,
      // Set `allowsDelayedPaymentMethods` to true if your business can handle payment
      //methods that complete payment after a delay, like SEPA Debit and Sofort.
      allowsDelayedPaymentMethods: true,
      defaultBillingDetails: {
        name: 'Jane Doe',
      }
    });
    if (!error) {
      setLoading(true);
    }
  };

  const openPaymentSheet = async () => {
    // see below
  };

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

  return (
    <Screen>
      <Button
        variant="primary"
        disabled={!loading}
        title="Checkout"
        onPress={openPaymentSheet}
      />
    </Screen>
  );
}

Cuando el cliente toque el botón Pagar, llama a presentPaymentSheet() para abrir la hoja. Después de que el cliente completa el pago, la hoja se cierra y la promesa se resuelve con un StripeError<PaymentSheetError> opcional.

export default function CheckoutScreen() {
  // continued from above

  const openPaymentSheet = async () => {
    const { error } = await presentPaymentSheet();

    if (error) {
      Alert.alert(`Error code: ${error.code}`, error.message);
    } else {
      Alert.alert('Success', 'Your order is confirmed!');
    }
  };

  return (
    <Screen>
      <Button
        variant="primary"
        disabled={!loading}
        title="Checkout"
        onPress={openPaymentSheet}
      />
    </Screen>
  );
}

Si no se produjo ningún error, infórmale al usuario que el proceso terminó (por ejemplo, mostrándole una pantalla de confirmación del pedido).

Establecer allowsDelayedPaymentMethods en true permite aceptar métodos de pago de notificación diferida como cuentas bancarias en EE. UU. Para estos métodos de pago, el estado final del pago no se conoce cuando se completa el PaymentSheet, sino que se efectúa con éxito o falla más tarde. Si aceptas este tipo de métodos de pago, infórmale al cliente que su pedido está confirmado y solo finalízalo (por ejemplo, envía el producto) cuando el pago se realice correctamente.

El cliente puede salir de tu aplicación para autenticarse (por ejemplo, en Safari o en su aplicación bancaria). Para permitirles que regresen automáticamente a tu aplicación después de autenticarse, configura un esquema de URL personalizado y define el delegado de la aplicación para que envíe la URL al SDK. Stripe no admite enlaces universales.

// This method handles opening custom URL schemes (for example, "your-app://stripe-redirect")
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else {
        return
    }
    let stripeHandled = StripeAPI.handleURLCallback(with: url)
    if (!stripeHandled) {
        // This was not a Stripe url – handle the URL normally as you would
    }
}

Además, debes definir la returnURL del objeto PaymentSheet.Configuration en la URL de tu aplicación.

var configuration = PaymentSheet.Configuration()
configuration.returnURL = "your-app://stripe-redirect"

Stripe envía un evento payment_intent.succeeded cuando se completa el pago. Usa la herramienta de webhook del Dashboard o sigue la guía de webhooks para recibir estos eventos y ejecutar acciones como, 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 un flujo de envío.

Escucha estos eventos en lugar de esperar una devolución de llamada del cliente. De su lado, el cliente puede cerrar la ventana del navegador o salir de la aplicación antes de que se ejecute la devolución de llamada, y clientes malintencionados podrían manipular la respuesta. Si configuras tu integración para escuchar eventos asincrónicos, podrás aceptar diferentes tipos de métodos de pago con una sola integración.

Además de administrar el evento payment_intent.succeeded, recomendamos administrar estos otros eventos si se cobran pagos con el Payment Element:

Consulta Pruebas para obtener información adicional para probar tu integración.