> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# PagaLeve

> Acepta Pix Parcelado (Pix en cuotas) y pagos Pix únicos con PagaLeve, usando los flujos del SDK de Yuno o de la API directa.

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](https://docs.y.uno/es/docs/using-yuno/dashboard-overview/connections.md))

## 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](https://docs.y.uno/reference/customers/create-customer.md) 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](https://docs.y.uno/reference/customers/retrieve-customer.md) con el `id` de Yuno.
3. Usa [Retrieve Customer by External Id](https://docs.y.uno/reference/customers/retrieve-customer-by-external-id.md) con el parámetro de consulta `merchant_customer_id`.

> [!TIP]
>
> 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.

> [tab] SDK de Yuno
>
> ### Paso 1: crear una sesión de checkout
>
> Comienza creando una sesión de checkout con el endpoint [Create Checkout Session](https://docs.y.uno/es/reference/checkout-sessions/create-checkout-session.md).
>
> ```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> {
>   "account_id": "{{account_id}}",
>   "country": "BR",
>   "customer_id": "{{customer_id}}",
>   "merchant_order_id": "order-0000024",
>   "payment_description": "One-time Pix Payment with PagaLeve",
>   "amount": {
>     "currency": "BRL",
>     "value": 15000
>   }
> }
> ```
>
> 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.
>
> > [!TIP]
> >
> > 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](#status-transitions) más abajo.

> [tab] API directa
>
> ### Paso 1: crear un pago
>
> Usa [Create payment](https://docs.y.uno/es/reference/payments/create-payment.md) con el flujo directo.
>
> ```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> {
>   "description": "One-time Pix Payment with PagaLeve",
>   "account_id": "{{account_id}}",
>   "merchant_order_id": "0000024",
>   "country": "BR",
>   "amount": {
>     "currency": "BRL",
>     "value": 150
>   },
>   "customer_payer": {
>     "id": "{{customer_id}}"
>   },
>   "callback_url": "https://your-callback.com",
>   "workflow": "DIRECT",
>   "payment_method": {
>     "type": "PIX"
>   }
> }
> ```
>
> > [!TIP]
> >
> > La respuesta devuelve el `redirect_url` del checkout en el detalle del método de pago. Redirige al cliente allí para completar el pago; PagaLeve confirma el resultado a Yuno mediante un webhook. Consulta [Transiciones de estado](#status-transitions) más abajo para ver cómo se corresponden los estados de PagaLeve con los de Yuno.
>
> ### Paso 2: confirmar el pago
>
> Usa [Retrieve payment by id](https://docs.y.uno/reference/payments/retrieve-payment-by-id) para confirmar el estado final.

## 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.

> [tab] SDK de Yuno
>
> ### 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.
>
> ```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> {
>   "description": "Pix Parcelado Payment with PagaLeve",
>   "account_id": "{{account_id}}",
>   "merchant_order_id": "0000023",
>   "country": "BR",
>   "amount": {
>     "currency": "BRL",
>     "value": 250
>   },
>   "customer_payer": {
>     "id": "{{customer_id}}"
>   },
>   "workflow": "SDK_CHECKOUT",
>   "checkout": {
>     "session": "{{checkout_session_id}}"
>   },
>   "payment_method": {
>     "type": "PIX_PARCELADO"
>   },
>   "additional_data": {
>     "order": {
>       "items": [
>         {
>           "id": "{{sku}}",
>           "name": "{{item_name}}",
>           "quantity": 1,
>           "unit_amount": 250,
>           "category": "{{item_category}}"
>         }
>       ]
>     }
>   }
> }
> ```
>
> > [!TIP]
> >
> > 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](#status-transitions) más abajo.

> [tab] API directa
>
> ### Paso 1: crear el pago
>
> Usa [Create payment](https://docs.y.uno/es/reference/payments/create-payment.md) con el flujo directo y `payment_method.type` `"PIX_PARCELADO"`. Pasa los artículos del pedido en `additional_data.order.items`, con la misma estructura que se muestra en la pestaña del SDK anterior.
>
> > [!TIP]
> >
> > Consulta [Transiciones de estado](#status-transitions) más abajo para ver cómo informa PagaLeve los cambios de estado, y la pestaña del SDK anterior para saber dónde regresa la URL de redirección en la respuesta y dónde elige el cliente el plan de cuotas.
>
> ### Paso 2: consultar el pago
>
> Usa [Retrieve payment by id](https://docs.y.uno/reference/payments/retrieve-payment-by-id) para confirmar el estado final.

> [!NOTE]
>
> **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`.

| Estado de PagaLeve | Estado de Yuno |
| - | - |
| `NEW` | Creado |
| `ACCEPTED` | Pendiente de confirmación del proveedor |
| `AUTHORIZED` | Exitoso |
| `COMPLETED` | Exitoso |
| `RELEASED` | Exitoso |
| `CAPTURED` | Exitoso |
| `CANCELED` | Cancelado por el usuario |
| `EXPIRED` | Expirado por el proveedor |
| `PAYMENT_DECLINED` | Rechazado por el proveedor |

## Endpoints

* [Crear cliente](https://docs.y.uno/reference/customers/create-customer.md)
* [Consultar cliente](https://docs.y.uno/reference/customers/retrieve-customer.md)
* [Consultar cliente por ID externo](https://docs.y.uno/reference/customers/retrieve-customer-by-external-id.md)
* [Crear sesión de checkout](https://docs.y.uno/es/reference/checkout-sessions/create-checkout-session.md)
* [Crear pago](https://docs.y.uno/es/reference/payments/create-payment.md)
* [Consultar pago por ID](https://docs.y.uno/reference/payments/retrieve-payment-by-id)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.