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

# Llamadas por pagos rechazados

> Inicia llamadas masivas de IA y mensajes de WhatsApp para recuperar a clientes con pagos rechazados

Este endpoint te permite iniciar el procesamiento a gran escala de llamadas y mensajes de WhatsApp relacionados con pagos rechazados. Para usar el endpoint, debes proporcionar un objeto con información detallada sobre el pago rechazado.

Envía un encabezado `X-Idempotency-Key` único con cada solicitud, para que una solicitud reintentada se procese una sola vez.


## OpenAPI

````yaml openapi/es/ai-caller/declined-payment-calls.json POST /smart-support/external/payments/recover
openapi: 3.0.0
info:
  title: AI Caller
  description: >-
    API for initiating large-scale processing of calls and WhatsApp messages
    related to declined payments and abandoned user flows.
  version: 1.0.0
servers:
  - url: https://api-sandbox.y.uno/v1
    description: Sandbox
  - url: https://api.y.uno/v1
    description: Production (US)
security:
  - public_api_key: []
    private_secret_key: []
tags:
  - name: AI Caller
    description: Operaciones relacionadas con las cuentas de usuario
paths:
  /smart-support/external/payments/recover:
    post:
      tags:
        - AI Caller
      summary: Llamadas de pagos rechazados
      operationId: declined-payment-calls
      parameters:
        - name: X-Idempotency-Key
          in: header
          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.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - settings
              properties:
                settings:
                  type: object
                  description: Configuración del agente de IA
                  required:
                    - contact_details
                  properties:
                    contact_details:
                      type: object
                      description: Objeto con los datos de contacto
                      required:
                        - channel
                      properties:
                        channel:
                          type: string
                          enum:
                            - PHONE_CALL
                            - WHATSAPP_MESSAGE
                          description: |+
                            La lista de canales de contacto posibles.

                          example: WHATSAPP_MESSAGE
                        initial_template_message:
                          type: object
                          description: >-
                            Obligatorio si `channel = WHATSAPP_MESSAGE`.
                            Configuración inicial del mensaje de plantilla para
                            `WHATSAPP_MESSAGE`.
                          properties:
                            id:
                              type: string
                              description: ID de plantilla de Yuno
                              example: HX8e7ac569f40a064c71a37e5d672bb9123
                            variables:
                              type: object
                              description: Objeto con las variables de la plantilla
                              example:
                                name: Maria
                                amount: $10.0000
                        pdf_template:
                          type: object
                          properties:
                            id:
                              type: string
                              description: ID de plantilla PDF de Yuno
                            variables:
                              type: object
                              description: Objeto con las variables de la plantilla PDF
                              example:
                                seller_name: RAPPI
                                merchant_order_id: MX_Verification_50708779
                          description: >-
                            Configuración de la plantilla PDF para
                            WHATSAPP_MESSAGE.
                        payment_methods:
                          type: object
                          description: >-
                            Métodos de pago disponibles para ofrecer al cliente
                            pagador
                          properties:
                            available:
                              type: array
                              description: >-
                                La lista de métodos de pago disponibles que se
                                ofrecen al usuario como alternativas para
                                completar el pago.
                              items:
                                type: string
                              example:
                                - MERCADO_PAGO
                                - NEQUI
                                - CREDIT_CARD
                          required:
                            - available
                additional_information:
                  type: object
                  description: >-
                    Toda la información relevante que se entrega a la IA para
                    mejorar el contexto.
                  properties:
                    seller_details:
                      type: object
                      description: >-
                        Objeto con los datos de contacto del comercio que se
                        usan si el agente no puede responder la consulta.
                      properties:
                        name:
                          type: string
                          description: >-
                            El nombre del comercio, que la IA usa para
                            presentarse.
                          minLength: 3
                          maxLength: 255
                          example: RAPPI
                        fallback_instructions:
                          type: string
                          description: >-
                            Instrucción que se da al usuario sobre cómo
                            contactar al soporte al cliente en caso de que la IA
                            no pueda resolver el problema.
                          minLength: 3
                          maxLength: 255
                          example: >-
                            Go to the application and click on the top right
                            corner to contact a customer support agent.
                        redirection_url:
                          type: string
                          description: >-
                            URL a la que se redirige al cliente para obtener
                            soporte adicional.
                          example: www.test.com/purchase
                    payment:
                      type: object
                      description: Información del pago rechazado
                      properties:
                        account_id:
                          type: string
                          description: El identificador único de la cuenta.
                          minLength: 36
                          maxLength: 64
                          example: e4c03f29-b0f6-403a-8814-9aee1a88d60e
                        id:
                          type: string
                          description: El identificador único del pago.
                          minLength: 3
                          maxLength: 64
                          example: f1fbad16-93c1-4335-b735-2b01ec94ea9e
                        merchant_order_id:
                          type: string
                          description: Identificación de la orden.
                          minLength: 3
                          maxLength: 255
                          example: ORDER-12345
                        country:
                          type: string
                          description: País donde se procesó el pago (ISO 3166-1).
                          minLength: 2
                          maxLength: 2
                          example: US
                        description:
                          type: string
                          description: >-
                            La descripción del producto o servicio que el
                            usuario intentó comprar.
                          minLength: 3
                          maxLength: 1000
                          example: Online store purchase
                        created_at:
                          type: string
                          format: date-time
                          description: >-
                            La marca de tiempo del momento en que se realizó el
                            pago (ISO 8601).
                          minLength: 27
                          maxLength: 27
                          example: '2022-05-09T20:46:54.786342Z'
                        declined_reason:
                          type: string
                          description: >-
                            El motivo de rechazo del pago informado por el
                            proveedor de pagos.
                          minLength: 3
                          maxLength: 255
                          example: insufficient funds
                        payment_method:
                          type: object
                          properties:
                            type:
                              type: string
                              description: >-
                                El tipo de método de pago seleccionado por el
                                cliente.
                              minLength: 3
                              maxLength: 255
                              example: Credit Card
                            detail:
                              type: object
                              properties:
                                card_data:
                                  type: object
                                  properties:
                                    expiration_month:
                                      type: number
                                      description: Mes de vencimiento de la tarjeta - MM
                                      minimum: 1
                                      maximum: 12
                                      example: 12
                                    expiration_year:
                                      type: number
                                      description: Año de vencimiento de la tarjeta - YYYY
                                      minimum: 2024
                                      maximum: 9999
                                      example: 2030
                                    iin:
                                      type: string
                                      description: >-
                                        El número de identificación de la
                                        institución (IIN) corresponde a los
                                        primeros dígitos del número de una
                                        tarjeta de pago emitida por una entidad
                                        financiera.
                                      minLength: 6
                                      maxLength: 8
                                      example: '411111'
                                    lfd:
                                      type: string
                                      description: Últimos cuatro dígitos de la tarjeta.
                                      minLength: 4
                                      maxLength: 4
                                      example: '1234'
                                    issuer:
                                      type: string
                                      description: Emisor de la tarjeta.
                                      minLength: 3
                                      maxLength: 255
                                      example: CHASE
                                    type:
                                      type: string
                                      description: Tipo de emisor de la tarjeta.
                                      enum:
                                        - CREDIT
                                        - DEBIT
                                        - PREPAID
                                      minLength: 3
                                      maxLength: 255
                                      example: CREDIT
                        amount:
                          type: object
                          properties:
                            value:
                              type: number
                              description: El monto del pago que fue rechazado.
                              example: 149.99
                            currency:
                              type: string
                              description: La moneda del pago que fue rechazado (ISO 4217).
                              minLength: 3
                              maxLength: 3
                              example: USD
                        customer_payer:
                          type: object
                          properties:
                            first_name:
                              type: string
                              description: El nombre del cliente.
                              minLength: 3
                              maxLength: 255
                              example: John
                            last_name:
                              type: string
                              description: El apellido del cliente.
                              minLength: 3
                              maxLength: 255
                              example: Doe
                            phone:
                              type: object
                              properties:
                                country_code:
                                  type: string
                                  description: >-
                                    Código de área del celular del cliente
                                    pagador.
                                  minLength: 2
                                  maxLength: 3
                                  example: '1'
                                number:
                                  type: string
                                  description: Número de celular del cliente pagador.
                                  minLength: 1
                                  maxLength: 32
                                  example: '5551234567'
            examples:
              Request Example:
                summary: Request Example
                value:
                  settings:
                    contact_details:
                      channel: PHONE_CALL
                      initial_template_message:
                        id: HX8e7ac569f40a064c71a37e5d672bb9123
                        variables:
                          name: Maria
                          amount: $10.0000
                      pdf_template:
                        id: ede0d2da-138d-441b-8101-85e2d21af8b9
                        variables:
                          seller_name: RAPPI
                          merchant_order_id: MX_Verification_50708779
                      payment_methods:
                        available:
                          - MERCADO_PAGO
                          - NEQUI
                  additional_information:
                    seller_details:
                      name: RAPPI
                      fallback_instructions: >-
                        Go to the application and click on the top right corner
                        to contact a customer support agent.
                      redirection_url: www.test.com/purchase
                    payment:
                      account_id: e4c03f29-b0f6-403a-8814-9aee1a88d60e
                      id: f1fbad16-93c1-4335-b735-2b01ec94ea9e
                      merchant_order_id: MX_Verification_50708779
                      country: CO
                      description: Purchase in McDonalds
                      created_at: '2022-05-09T20:46:54.786342Z'
                      declined_reason: insufficient funds
                      payment_method:
                        type: Credit Card
                        detail:
                          card_data:
                            iin: '636318'
                            lfd: '2671'
                            type: CREDIT
                            issuer: SCOTIABANK
                            expiration_year: 2030
                            expiration_month: 12
                      amount:
                        currency: COP
                        value: 27000
                      customer_payer:
                        first_name: Pepito
                        last_name: Perez
                        phone:
                          country_code: '57'
                          number: '3000000000'
      responses:
        '200':
          description: Éxito
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 7c3a9c6e-9bf0-4c2c-9f67-752b16ba5dd5
                  message:
                    type: string
                    example: Communication processed successfully
              examples:
                Success:
                  value:
                    id: 7c3a9c6e-9bf0-4c2c-9f67-752b16ba5dd5
                    message: Communication processed successfully
                  summary: Success
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Missing customer_payer.first_name required field
              examples:
                Bad Request:
                  value:
                    message: Missing customer_payer.first_name required field
                  summary: Bad Request
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Internal error
              examples:
                Internal Error:
                  value:
                    message: Internal error
                  summary: Internal Error
components:
  securitySchemes:
    public_api_key:
      type: apiKey
      in: header
      name: public-api-key
      description: |
        Ejemplo: `<Your public-api-key>`
    private_secret_key:
      type: apiKey
      in: header
      name: private-secret-key
      description: |
        Ejemplo: `<Your private-secret-key>`      

````

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