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

# Crear notificación previa al débito

> Envía al cliente la notificación previa al débito que exige NPCI antes de un débito recurrente de UPI Autopay.

Antes de cada débito recurrente de UPI Autopay, NPCI exige notificar al cliente con anticipación. Este endpoint envía ese aviso a través del proveedor de pagos y devuelve un `id` que debes referenciar en el débito.

El flujo tiene tres pasos:

1. **Notificar**: llama a este endpoint con el `vaulted_token` del mandato, el `amount` próximo y la `billing_date`. El enrutamiento al proveedor proviene de `origin_payment_id` (el pago que creó el mandato) o de un `provider_data` explícito.
2. **Revisar el estado**: `SENT` significa que el proveedor entregó la notificación y devolvió su referencia en `provider_data.provider_notification_id`.
3. **Debitar**: crea el pago recurrente con `payment_method.detail.bank_transfer.pre_debit_notification_id` establecido con el `id` devuelto. Yuno resuelve la referencia del proveedor y la reenvía automáticamente (consulta [Crear pago](https://docs.y.uno/es/reference/payments/create-payment.md)).

Esta solicitud requiere un `X-Idempotency-Key`. Si reutilizas un `merchant_reference`, se devuelve la notificación existente de tu cuenta.


## OpenAPI

````yaml openapi/es/pre-debit-notifications/create-pre-debit-notification.json POST /predebit-notify
openapi: 3.1.0
info:
  title: pre-debit-notifications
  version: 1.0.0
servers:
  - url: https://api-sandbox.y.uno/v1
    description: Sandbox
  - url: https://api.y.uno/v1
    description: Production (US)
security:
  - sec0: []
    sec1: []
paths:
  /predebit-notify:
    post:
      summary: Crear notificación previa al débito
      description: >-
        Envía al cliente la notificación previa al débito que exige NPCI antes
        de un débito recurrente de UPI Autopay. El proveedor entrega el aviso y
        devuelve una referencia; conserva el id devuelto y envíalo en el débito
        recurrente como
        payment_method.detail.bank_transfer.pre_debit_notification_id.
      operationId: create-pre-debit-notification
      parameters:
        - name: X-Idempotency-Key
          in: header
          required: true
          description: >-
            Identificador único que se usa en los encabezados HTTP para
            garantizar que una solicitud se procese una sola vez, aunque se
            reintente por problemas de red o timeouts.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - account_id
                - merchant_reference
                - amount
                - billing_date
              properties:
                account_id:
                  type: string
                  format: uuid
                  description: El ID de tu cuenta de Yuno.
                merchant_reference:
                  type: string
                  description: >-
                    Tu referencia única para esta notificación. Reutilizar una
                    referencia devuelve la notificación existente (idempotente
                    por cuenta).
                description:
                  type: string
                  description: >-
                    Texto que se muestra al cliente en la notificación (por
                    ejemplo, el nombre de la suscripción y el aviso de
                    renovación).
                amount:
                  type: object
                  required:
                    - currency
                    - value
                  properties:
                    currency:
                      type: string
                      description: >-
                        Código de moneda ISO 4217 del próximo débito (para UPI
                        Autopay, INR).
                      example: INR
                    value:
                      type: string
                      description: Monto del próximo débito.
                      example: '499.00'
                billing_date:
                  type: string
                  format: date
                  description: >-
                    Fecha del próximo débito (YYYY-MM-DD). Según NPCI, notifica
                    al cliente al menos 24 horas antes del débito.
                billing_sequence_number:
                  type: string
                  description: >-
                    Número de secuencia del débito dentro del mandato (por
                    ejemplo, 2 para el segundo cargo).
                origin_payment_id:
                  type: string
                  format: uuid
                  description: >-
                    ID del pago de creación del mandato. Si se proporciona, Yuno
                    deriva el proveedor y la conexión a partir de su cargo
                    exitoso. Se requiere origin_payment_id o provider_data.
                customer_payer:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                      description: ID de cliente de Yuno.
                    merchant_customer_id:
                      type: string
                      description: Tu identificador del cliente.
                payment_method:
                  type: object
                  properties:
                    type:
                      type: string
                      description: Tipo de método de pago del mandato.
                      example: UPI_AUTOPAY
                    vaulted_token:
                      type: string
                      format: uuid
                      description: >-
                        Token almacenado del mandato inscrito. Yuno resuelve a
                        partir de él la credencial del mandato del proveedor.
                provider_data:
                  type: object
                  description: >-
                    Enrutamiento explícito al proveedor. Se requiere
                    origin_payment_id o provider_data (id + connection_id).
                  properties:
                    id:
                      type: string
                      description: ID del proveedor (por ejemplo, EBANX).
                      example: EBANX
                    connection_id:
                      type: string
                      format: uuid
                      description: Conexión por la que se envía la notificación.
            examples:
              UPI Autopay:
                value:
                  account_id: 00000000-0000-0000-0000-000000000000
                  merchant_reference: subscription-2026-08-INV-00187
                  description: Your subscription renews soon
                  amount:
                    currency: INR
                    value: '499.00'
                  billing_date: '2026-08-01'
                  billing_sequence_number: '2'
                  customer_payer:
                    id: 9a8b7c6d-5e4f-4a3b-8c1d-0e9f8a7b6c5d
                  payment_method:
                    type: UPI_AUTOPAY
                    vaulted_token: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                  provider_data:
                    id: EBANX
                    connection_id: 6c1f6bfb-736b-439e-b568-32f671f65256
      responses:
        '201':
          description: >-
            Notificación creada. Revisa el estado: SENT significa que el
            proveedor la entregó.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: >-
                      Identificador único de la notificación previa al débito.
                      Haz referencia a él en el débito recurrente como
                      payment_method.detail.bank_transfer.pre_debit_notification_id.
                  account_id:
                    type: string
                    format: uuid
                    description: El ID de tu cuenta de Yuno.
                  status:
                    type: string
                    enum:
                      - SENT
                      - REJECTED
                      - ERROR
                    description: >-
                      SENT: el proveedor aceptó y entregó la notificación.
                      REJECTED: el proveedor la rechazó. ERROR: no se pudo
                      transmitir la notificación.
                  merchant_reference:
                    type: string
                    description: >-
                      Tu referencia única para esta notificación (idempotente
                      por cuenta).
                  description:
                    type: string
                    description: Texto que se muestra al cliente en la notificación.
                  amount:
                    type: object
                    required:
                      - currency
                      - value
                    properties:
                      currency:
                        type: string
                        description: >-
                          Código de moneda ISO 4217 del próximo débito (para UPI
                          Autopay, INR).
                        example: INR
                      value:
                        type: string
                        description: Monto del próximo débito.
                        example: '499.00'
                  billing_date:
                    type: string
                    format: date
                    description: Fecha del próximo débito (YYYY-MM-DD).
                  origin_payment_id:
                    type: string
                    format: uuid
                    description: >-
                      El pago de creación del mandato que se usó para derivar el
                      proveedor y la conexión, cuando se proporciona.
                  provider_data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: >-
                          Proveedor que gestionó la notificación (por ejemplo,
                          EBANX).
                      connection_id:
                        type: string
                        format: uuid
                        description: Conexión que se usó para enviar la notificación.
                      provider_transaction_id:
                        type: string
                        description: >-
                          Referencia de transacción del proveedor, cuando está
                          disponible.
                      provider_notification_id:
                        type: string
                        description: >-
                          Referencia del proveedor de la notificación entregada.
                          Yuno la resuelve y la reenvía al proveedor
                          automáticamente cuando el débito recurrente hace
                          referencia a esta notificación.
                      raw_request:
                        type: object
                        description: >-
                          Solicitud ofuscada al proveedor. Solo se devuelve para
                          organizaciones en la lista de permitidos.
                      raw_response:
                        type: object
                        description: >-
                          Respuesta ofuscada del proveedor. Solo se devuelve
                          para organizaciones en la lista de permitidos.
                  created_at:
                    type: string
                    format: date-time
                  updated_at:
                    type: string
                    format: date-time
        '400':
          description: >-
            Parámetros no válidos (por ejemplo, falta el enrutamiento al
            proveedor o billing_date tiene un formato incorrecto).
        '422':
          description: >-
            El vaulted_token no tiene una credencial almacenada para el
            proveedor resuelto (STORED_CREDENTIAL_NOT_FOUND), o el pago de
            origen no tiene una conexión utilizable
            (PROVIDER_CONNECTION_REQUIRED).
components:
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: public-api-key
      x-default: <Your public-api-key>
    sec1:
      type: apiKey
      in: header
      name: private-secret-key
      x-default: <Your private-secret-key>

````

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