Recibe pagos y luego transfiérelos en tu marketplace

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 (vendedor o proveedor de servicios) crea una cuenta en tu marketplace, tienes que crear la Cuenta de usuario correspondiente (llamada cuenta conectada). No puedes aceptar pagos ni transferir fondos a la cuenta bancaria del usuario sin tener una cuenta conectada. Las cuentas conectadas representan a los usuarios en la API de Stripe y recopilan la información necesaria para verificar la identidad del usuario. En nuestro ejemplo de alquiler de vivienda, la cuenta conectada representa al propietario de la vivienda.

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

Utiliza la API /v1/accounts para crear una cuenta conectada especificando las propiedades de la cuenta conectada o el tipo de cuenta.

curl https://api.stripe.com/v1/accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "controller[losses][payments]"=application \
  -d "controller[fees][payer]"=application \
  -d "controller[stripe_dashboard][type]"=express

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 clave url. Redirige a tu usuario a este enlace para enviarlo al flujo. Las direcciones URL desde la API Account Links son temporales y solo se pueden utilizar una vez, ya que otorgan acceso a los datos personales del usuario de la cuenta conectada. Autentica a los usuarios en tu aplicación antes de redirigirlos a esta URL. Si quieres completar los datos automáticamente, debes hacerlo antes de generar el enlace de cuenta. Después de haber creado el enlacede la cuenta, no podrás leer ni escribir información para la cuenta conectada.

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

Stripe 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ó la URL (el usuario 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

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 la configuración de métodos de pago y habilita los que quieras admitir. Los pagos con tarjeta, Google Pay y Apple Pay están habilitados de forma predeterminada, pero puedes habilitar y deshabilitar los métodos de pago según sea necesario.

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.

Usa Stripe Checkout para aceptar pagos. Checkout admite varios métodos de pago y muestra automáticamente aquellos que se adaptan mejor a tu cliente. Puedes aceptar pagos con Checkout mediante una página alojada por Stripe o agregar un formulario de pago prediseñado integrable directamente en tu sitio web. También puedes crear un flujo personalizado (con Payment Element) 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 and Server

La sesión de Checkout controla lo que tu cliente puede ver en la página de pagos alojada por Stripe, como las partidas, el importe y la moneda del pedido, y los métodos de pago aceptados.

Agrega un botón para finalizar la compra en tu sitio web que llame a un punto de conexión del lado del servidor para crear una sesión de Checkout.

checkout.html

<html>
  <head>
    <title>Checkout</title>
  </head>
  <body>
    <form action="/create-checkout-session" method="POST">
      <button type="submit">Checkout</button>
    </form>
  </body>
</html>

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
:" \
  -d mode=payment \
  -d "line_items[0][price]"=
{{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -d "payment_intent_data[application_fee_amount]"=123 \
  -d "payment_intent_data[transfer_data][destination]"=
{{CONNECTED_ACCOUNT_ID}} \
  --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. Estos artículos se muestran en la interfaz de usuario alojada por Stripe.
• success_url: este argumento redirige al usuario después de que completa el pago.
• cancel_url: este argumento redirige al usuario después de que hace clic en Cancelar.
• payment_intent_data[application_fee_amount]: este argumento especifica el importe que tu plataforma tomará de la transacción. El importe total del cargo se transfiere de inmediato de la plataforma a la cuenta conectada especificada por transfer_data[destination] después de la captura del cargo. El application_fee_amount se vuelve a transferir a la plataforma y se deduce la comisión de Stripe del importe de la plataforma.
• payment_intent_data[transfer_data][destination]: este argumento indica que se trata de un cargo a un Destino. Un cargo a un Destino es aquel que se procesa en la plataforma y por el cual los fondos se transfieren de manera inmediata y automática al saldo pendiente de la cuenta conectada. En nuestro ejemplo de alquiler de viviendas, queremos crear una experiencia en la que el cliente pague a través de la plataforma y esta le pague al propietario.

Checkout utiliza la configuración de marca de la cuenta de tu plataforma para los cargos a un destino. Para obtener más información, consulta Personaliza la imagen de marca.

Esta sesión crea un cargo a un destino. Si necesitas controlar el plazo de las transferencias o transferir fondos de un solo pago a varias personas, utiliza cargos y envíos de fondos separados. Para usar cargos separados, consulta Habilita a otras empresas para que acepten pagos directamente.

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 administrar el evento checkout.session.completed, te recomendamos administrar otros dos eventos al cobrar pagos con Checkout:

Evento	Descripción	Próximos pasos
checkout.session.completed	El cliente ha autorizado correctamente el pago enviando el formulario de Checkout.	Espera hasta saber si el pago se efectuó correctamente o no.
checkout.session.async_payment_succeeded	El pago del cliente se efectuó correctamente.	Entrega 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 pago se efectúa correctamente, el estado del PaymentIntent subyacente cambia de processing a succeeded.

Para probar el flujo de creación de cuentas, crea cuentas y usa OAuth.

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