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

# Código QR y pago instantáneo

> Combina un pago con código QR de Pix con la inscripción a una suscripción para habilitar cobros recurrentes automáticos

En el flujo **QR Code & Instant Payment**, Yuno presenta un único código QR que cobra al cliente de inmediato y lo inscribe en todos los pagos recurrentes futuros en un solo paso. Cuando el cliente escanea el QR, su aplicación bancaria procesa la primera cuota y, al mismo tiempo, captura su consentimiento para los cobros automáticos posteriores, sin necesidad de aprobaciones adicionales ni de ingreso manual.

Después del escaneo y el pago iniciales, cada **solicitud posterior** la envía el comercio a través de Yuno y el banco del cliente la valida automáticamente contra el consentimiento original, lo que garantiza transferencias rápidas y confiables sin más interacción del cliente. Este flujo simplifica la gestión de suscripciones al combinar la inscripción y el pago en una sola acción del usuario.

## Paso 1: primer pago y creación de la suscripción

Para iniciar el flujo, debes comenzar con un [pago Pix](https://docs.y.uno/es/reference/payments/create-payment.md#/) estándar que también configure la suscripción. Esto genera un código QR o una pantalla de redirección para que el cliente autorice la recurrencia. Una vez pagado, se crea la suscripción y se devuelve un `subscription_code`.

Puedes definir la frecuencia, la ventana de disponibilidad y el tipo de monto (fijo o variable) como parte del payload de la suscripción.

| Campos de las suscripciones | Descripción |
| :- | :- |
| Frecuencia | Define la frecuencia con la que se realizarán los cobros de la suscripción (semanal, mensual, trimestral, semestral o anual) y especifica el monto que se debe cobrar en el siguiente ciclo de facturación. |
| Disponibilidad | Las fechas de inicio y fin de la suscripción. |
| Monto | Define el valor que usarás para los pagos futuros de la suscripción. Puede ser `FIXED` con un valor mínimo definido, o `VARIABLE` sin un monto definido para los pagos futuros. |

Ten en cuenta que la información definida al crear la suscripción restringe las fechas y los valores que se pueden usar en los pagos futuros.

```json Example theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "amount": {
    "value": "100",
    "currency": "BRL"
  },
	"payment_method": {
        "type": "PIX_AUTOMATIC"
	},
	"subscription": {
    "frequency": {
      "type": "MONTH",
      "value": 1
    },
    "availability": {
      "start_at": "2025-05-23T20:17:30.277678Z",
      "finish_at": "2027-05-23T20:17:30.277678Z"
    },
    "amount": {
      "value": "100",
      "currency": "BRL",
      "type": "FIXED"
    }
  }
}
```

Después de que se confirma el pago inicial, el cliente tiene una suscripción activa y puedes comenzar a programar cobros futuros.

## Paso 2: pagos futuros

Según lo definido por el banco central, los pagos deben crearse dentro de una **ventana de programación de 10 a 2 días antes de la fecha de cobro programada**. Usa el `subscription.id` para identificar la recurrencia en la [creación del pago](https://docs.y.uno/es/reference/payments/create-payment.md#/).

| Campos de los pagos futuros | |
| :- | :- |
| `subscription.id` | ID de la suscripción obtenido en el primer paso (devuelto allí como `subscription_code`). |
| `billing_date` | Al especificar el objeto `billing_date`, el comercio puede definir la lógica de la fecha exacta de cobro de la suscripción. |

```json Example theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
"workflow": "DIRECT",
"amount": {
  "value": "100",
  "currency": "BRL"
},
"payment_method": {
  "type": "PIX_AUTOMATIC",
},
"subscription": {
  "id": "cab9f0fe-2428-419b-8f9d-4b5efee8c1c8",
  "billing_date": {
    "type": "DAY",
    "day": 14
  }
}
```

Si un pago recurrente falla, se puede reintentar con una nueva solicitud de pago. Los **reintentos** deben realizarse **dentro de los 7 días** posteriores a la fecha de cobro original y se limitan a **3 intentos por ciclo**.


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