Saltar al contenido principal
Esta guía explica cómo integrar PagaLeve, un proveedor de pagos basado en Pix para Brasil, en tu checkout. Yuno admite tanto el SDK de Yuno (recomendado) como los flujos de API directa. Aprenderás a:
  • Realizar pagos Pix únicos con PagaLeve
  • Realizar pagos con Pix Parcelado (Pix en cuotas) con PagaLeve

Requisitos

Antes de comenzar, necesitas:
  • Una cuenta de Yuno con acceso al Dashboard
  • Claves de API y un account_id (que se encuentra en el dashboard)
  • Una conexión de PagaLeve configurada en tu cuenta de Yuno (consulta Connections)

Crear y gestionar clientes

Crea el cliente una sola vez usando 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 identificador único del cliente en tu sistema). La respuesta devuelve id, que es el identificador 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.
Crear primero un registro de cliente en Yuno no es obligatorio. PagaLeve acepta la información del cliente (CPF, email, nombre, teléfono, fecha de nacimiento, dirección) directamente en la llamada Create Payment, igual que con Pix simple. Aun así, se recomienda crear el cliente de antemano para mantener la coherencia con tus otros métodos de pago.

Pago Pix único

Usa PagaLeve para aceptar un pago Pix estándar de una sola vez.

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. PagaLeve aparece como una opción de pago disponible en la interfaz del SDK, usando el tipo de método de pago "PIX" para un pago único.
El cliente completa el pago en la página de checkout alojada de PagaLeve. Si tu conexión de PagaLeve tiene TRANSPARENT_CHECKOUT habilitado, el cliente lo completa dentro del SDK, mediante una URL de checkout. En cualquier caso, PagaLeve confirma el resultado a Yuno mediante un webhook. Consulta Transiciones de estado más abajo.

Pago con Pix Parcelado (en cuotas)

PagaLeve admite Pix Parcelado, que permite a los clientes dividir un pago Pix en cuotas. El cliente elige el plan de cuotas en la propia página de checkout de PagaLeve: Yuno no devuelve los planes disponibles por adelantado y en la llamada Create Payment no se envía ningún dato del plan ni de las cuotas.

Paso 1: crear el pago

Crea el pago con payment_method.type "PIX_PARCELADO". Pasa los artículos del pedido en additional_data.order.items para que PagaLeve pueda armar la oferta de cuotas.
La respuesta devuelve la redirección en payment_method.payment_method_detail.bank_transfer.redirect_url: Pix Parcelado se categoriza internamente como BANK_TRANSFER, por lo que usa el mismo objeto de detalle que otros métodos de transferencia bancaria. installments e installments_plan_id regresan vacíos al crear el pago; el cliente elige la cantidad de cuotas en la página de checkout alojada de PagaLeve después de la redirección. El pago comienza en estado Created y el estado final Successful o rechazado llega mediante el webhook. Consulta Transiciones de estado más abajo.
Limitaciones
  • La moneda se limita a BRL.
  • Pix y Pix Parcelado comparten el mismo flujo de reembolso, ambos se reembolsan de la misma manera, incluidos los motivos DUPLICATE, FRAUDULENT y REQUESTED_BY_CUSTOMER.
  • PagaLeve no usa un patrón de inscripción o almacenamiento, a diferencia de NuPay. Cada pago es un checkout único.

Transiciones de estado

PagaLeve informa el estado del pago mediante webhooks, que se procesan de forma asíncrona. Para CANCELED y EXPIRED, el webhook publica el estado directamente. Para los demás estados de éxito, primero captura el pago mediante el endpoint ProcessPayment.

Endpoints