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

Instala las bibliotecas oficiales de Stripe para acceder a la API desde tu aplicación:

# Available as a gem
sudo gem install stripe

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

Cuando un usuario (un vendedor o proveedor de servicios) crea una cuenta en tu plataforma, tienes que crear una Cuenta de usuario (llamada cuenta conectada) para poder 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.

Crear una cuenta conectada y completar la información automáticamente

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.

Crea un enlace de cuenta

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

Redirige al usuario a la URL del enlace de cuenta

La respuesta a tu solicitud de Account Links incluye un valor para la url de la clave. Redirige a este enlace para enviar al usuario al flujo. Los enlaces de cuenta son temporales y de un solo uso, ya que otorgan acceso a la información personal del usuario de la cuenta conectada. Autentica al usuario en tu aplicación antes de redirigirlo a esta URL. Si deseas completar previamente la información, debes hacerlo antes de generar el enlace de la cuenta. Después de crear el enlace de la cuenta, no podrás leer ni escribir información para la cuenta.

Gestiona el caso de un usuario que vuelve a la plataforma

El onboarding de Connect requiere que especifiques 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 que el usuario tenga la mejor experiencia.

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:

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

refresh_url

Se redirige a tu usuario a la refresh_url en los siguientes casos:

• Se venció el enlace (pasaron algunos minutos desde que se creó).
• 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.
• Se rechazó la cuenta.

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.

Gestiona los casos de usuarios que no hayan completado el onboarding

Si se redirige al usuario a tu return_url, es posible que no haya completado el proceso de onboarding. Usa el punto de conexión /v1/accounts para recuperar la cuenta del usuario y verificar 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 a través de un nuevo enlace de cuenta (generado por tu integración). Para ver si ha completado el proceso de onboarding, verifica el estado del parámetro details_submitted en su cuenta.

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 habilitar y deshabilitar métodos de pago según sea necesario. Esta guía asume que tienes habilitados Bancontact, tarjetas de crédito, EPS, iDEAL, Przelewy24, débito directo SEPA y Sofort.

Antes de que se abra el formulario de pago, 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. Los métodos de pago menos prioritarios se ocultan en un menú de contenido adicional.

Integra Stripe Checkout como un formulario de pago directamente en tu sitio web o redirige a los usuarios a una página alojada por Stripe para aceptar pagos. Checkout admite varios métodos de pago y muestra automáticamente los que más le pueden interesar a tu cliente. También puedes usar el Payment Element, un componente prediseñado de la interfaz de usuario que está integrado como un iframe en tu formulario de pago. Esto sirve para aceptar varios métodos de pago con una sola integración del front-end.

Página alojada por Stripe

Formulario integrado

Flujo personalizado

Crea una sesión de Checkout Client-side Server-side

Una sesión de Checkout controla lo que tu cliente ve en el formulario de pago integrable, por ejemplo, las partidas, el importe y la moneda del pedido y los métodos de pago aceptados. Cuando se realizan cargos Direct, Checkout usa la configuración de la imagen de marca de la cuenta conectada. Para obtener más información, consulta la sección Personalizar la imagen de marca.

A diferencia de los cargos a un Destino y de los cargos y envíos de fondos separados, los usuarios de las cuentas conectadas son responsables de gestionar las disputas asociadas con los cargos Direct. No es responsabilidad de la plataforma.

En tu servidor, haz la siguiente llamada a la API de Stripe. Después de haber creado una sesión de Checkout, redirige a tu cliente a la URL recibida en la respuesta.

Command Line

cURL

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d mode=payment \
  -d "line_items[0][price]"=
{{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -d "payment_intent_data[application_fee_amount]"=123 \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel"

• line_items: este argumento representa los artículos que compra el cliente y que se mostrarán en la interfaz de usuario alojada.
• success_url: este argumento redirige al usuario después de que completa el pago.
• cancel_url: este argumento redirige al usuario después de hacer click en Cancelar.
• Stripe-Account: este encabezado indica un cargo Direct para la cuenta conectada. Con los cargos Direct, la cuenta conectada es responsable de las comisiones de Stripe, de los reembolsos y de los contracargos. La imagen de marca de la cuenta conectada se utiliza en Checkout, lo que le transmite al cliente la sensación de estar interactuando directamente con el comerciante a cargo del cobro y no con tu plataforma.
• (Opcional) payment_intent_data[application_fee_amount]: este argumento especifica el importe que tu plataforma tomará de la transacción. Después de que se procesa el pago en la cuenta conectada, se transfiere application_fee_amount a la plataforma y la comisión de Stripe se deduce del saldo de la cuenta conectada.

Gestiona eventos posteriores al pago del lado del servidor

Stripe envía un evento checkout.session.completed cuando se completa el pago. Utiliza un webhook para recibir estos eventos y ejecutar acciones, como 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 tareas para un 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. Además, algunos métodos de pago tardan entre 2 y 14 días en confirmar el pago. Si configuras tu integración para escuchar eventos asincrónicos, podrás aceptar varios métodos de pago con una sola integración.

Además de gestionar el evento checkout.session.completed, te recomendamos que gestiones otros dos eventos cuando cobres pagos con Checkout:

Evento	Descripción	Próximos pasos
checkout.session.completed	Mediante el envío del formulario de Checkout, el cliente ha autorizado correctamente el pago.	Espera hasta saber si el pago se efectuó correctamente o no.
checkout.session.async_payment_succeeded	El pago del cliente se efectuó correctamente.	Completa el pedido de los productos o servicios comprados.
checkout.session.async_payment_failed	El pago se rechazó o falló por algún otro motivo.	Ponte en contacto con el cliente por correo electrónico y solicítale que haga un nuevo pedido.

Todos estos eventos incluyen el objeto Checkout Session. Después de que el pagose efectúa, el estado subyacente del PaymentIntent cambia de processing a succeeded.

Para probar el flujo de creación de cuentas, crea cuentas y usa OAuth. Para probar la configuración de los Métodos de pago de las cuentas conectadas, inicia sesión en una de las cuentas de prueba y accede a la configuración de los métodos de pago. Prueba el flujo de compra con las claves de prueba y una cuenta de prueba. Puedes usar las tarjetas de prueba para probar el flujo de pago y simular pagos con distintos resultados.