Saltar al contenido principal
Esta guía explica cómo integrar NuPay, el método de pago digital de NuBank, en tu checkout. Yuno admite los flujos de Yuno SDK (recomendado) y de Direct API. Aprenderás a:
  • Inscribir NuPay como método de pago de un cliente
  • Realizar pagos sin inscripción (modo 2FA)
  • Realizar pagos en cuotas (condiciones de pago)
  • Configurar suscripciones

Requisitos

Antes de comenzar, necesitas:
  • Una cuenta de Yuno con acceso al Dashboard
  • Claves de API y un account_id (que encuentras en el Dashboard)
  • Un cliente creado en Yuno (o créalo en el Paso 1)

Crear y administrar clientes

Crea el cliente una sola vez con tu merchant_customer_id externo y luego consúltalo por el id de Yuno o por merchant_customer_id, según necesites.
  1. Usa el endpoint Create Customer y proporciona tu propio merchant_customer_id (el id único del cliente en tu sistema). La respuesta devuelve id, que es el id de cliente de Yuno.
  2. Usa Retrieve Customer con el id de Yuno.
  3. Usa Retrieve Customer by External Id con el parámetro de consulta merchant_customer_id.

Inscribir el método de pago NuPay

Sigue los pasos a continuación para inscribir el método de pago NU_PAY_ENROLLMENT a un cliente.
Con la integración del SDK, Yuno se encarga de mostrar el método de pago NuPay, redirigir al cliente a NuBank para la autenticación y gestionar el flujo de regreso.

Paso 1: Crear un cliente

Crea un cliente y obtén su id de cliente de Yuno con el endpoint Create Customer.

Paso 2: Crear una sesión de cliente

Usa el id del cliente y el endpoint Create Customer Session para recibir un customer_session.

Paso 3: Inicializar el SDK e inscribir

Inicializa el SDK de Yuno (Web, Android o iOS) con el customer_session.Si usas el checkout del SDK o la integración headless, llama a Enroll Payment Method (Checkout) (POST /customers/sessions/{customer_session}/payment-methods) con payment_method_type: NU_PAY_ENROLLMENT.El SDK muestra automáticamente el método de pago NuPay, gestiona la redirección del cliente a NuBank y se encarga del flujo de autenticación.

Paso 4: Confirmar la inscripción

Escucha los webhooks o consulta los métodos de pago inscritos para verificar que el estado sea ENROLLED.

Pagos sin inscripción (modo 2FA)

Puedes aceptar pagos únicos con NuPay sin exigir que el cliente inscriba su método de pago. Esto suele llamarse modo 2FA, ya que el cliente autentica cada transacción de forma individual.
Acepta pagos sin inscripción usando el SDK de Yuno. El SDK se encarga de mostrar NuPay y de redirigir al cliente para completar la autenticación.

Paso 1: Crear una sesión de checkout

Comienza creando una sesión de checkout con el endpoint Create Checkout Session.
La respuesta devuelve un ID de checkout_session.

Paso 2: Inicializar el SDK

Inicializa el SDK de Yuno (Web, Android o iOS) con el ID de checkout_session. NuPay se mostrará automáticamente como una opción de pago disponible en la interfaz del SDK.

Paso 3: El cliente completa el pago

Cuando el cliente selecciona NuPay:
  1. El SDK solicita la autenticación al cliente.
  2. El cliente es redirigido a Nu para la autenticación 2FA.
  3. El SDK recibe el resultado y procesa el pago a través de Yuno.

Paso 4: Gestionar pagos con el flujo SDK (opcional)

Si llamas directamente a la API de pagos de Yuno mientras usas el checkout del SDK, establece workflow en SDK_CHECKOUT y pasa el token checkout.session:

Pagos con condiciones de pago (cuotas)

NuPay admite cuotas tanto para métodos de pago inscritos como para pagos únicos (modo 2FA).
NuPay admite cuotas para métodos de pago inscritos y pagos únicos (modo 2FA) dentro del SDK.

Paso 1: Obtener las condiciones de pago

Solicita las opciones de cuotas disponibles con el endpoint APM installments, según el flujo:
Selecciona el id del plan y el número de cuotas de la respuesta.

Paso 2: Crear el pago con el flujo del SDK

Crea el pago con el flujo del SDK estableciendo workflow: "SDK_CHECKOUT" y pasando checkout.session junto con los detalles del plan:

Subscription flow

Puedes usar NuPay para cargos recurrentes.
Los pagos recurrentes y las suscripciones con NuPay se configuran fácilmente con el token de inscripción del SDK:
  1. Crea un cliente.
  2. Inscribe NuPay mediante el SDK de Yuno (flujo Checkout) para obtener un vaulted_token.
  3. Crea una suscripción con el vaulted_token inscrito usando el endpoint Create subscription.
  4. Consulta y administra el estado de la suscripción según necesites.
Limitaciones
  • Las suscripciones con NuPay no admiten condiciones de pago (cuotas)
  • No se admite crear suscripciones directamente dentro de una solicitud de pago

Endpoints