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

# Reembolsar pago (dos tarjetas)

> Reembolsa una tarjeta de un pago de dos tarjetas, de forma total o parcial, usando el id de transacción de esa tarjeta.

Esta solicitud reembolsa una tarjeta de un pago creado con [Create Payment (two cards)](https://docs.y.uno/es/reference/payments/create-payment-v2.md). El reembolso es por tarjeta: envía el `id` de la transacción `PURCHASE` o `CAPTURE` de esa tarjeta en `payment_method.payment_methods[].transactions`.

Si omites `amount`, la tarjeta se reembolsa por completo. Un reembolso sobre una tarjeta tiene como tope el monto de esa tarjeta menos lo que ya se reembolsó en ella. Después de reembolsar una tarjeta, el pago queda en `SUCCEEDED / PARTIALLY_REFUNDED`; después de ambas, queda en `REFUNDED / REFUNDED`. La respuesta es `201` con el pago en el formato v2.

> [!WARNING]
>
> Mientras una tarjeta tiene un contracargo abierto, los reembolsos son rechazados con `INVALID_STATUS`.

Esta solicitud requiere un `X-Idempotency-Key`. Consulta [Authentication](https://docs.y.uno/es/reference/getting-started/authentication.md#idempotency) para obtener más detalles.


## OpenAPI

````yaml openapi/es/payments/refund-payment-v2.json POST /payments/{payment_id}/transactions/{transaction_id}/refund
openapi: 3.1.0
info:
  title: payments-v2
  version: 2.0.0
servers:
  - url: https://api-sandbox.y.uno/v2
    description: Sandbox
  - url: https://api.y.uno/v2
    description: Production (US)
security:
  - sec0: []
    sec1: []
paths:
  /payments/{payment_id}/transactions/{transaction_id}/refund:
    post:
      summary: Reembolsar pago (dos tarjetas)
      description: >-
        Reembolsa una tarjeta, total o parcialmente. El reembolso está limitado
        al monto de esa tarjeta menos lo que ya se reembolsó en ella.
      operationId: refund-payment-v2
      parameters:
        - name: X-Idempotency-Key
          in: header
          required: true
          description: >-
            Clave única de esta solicitud. Obligatoria en cada solicitud de pago
            v2. Si el resultado no es claro, reintenta con la misma clave. Sin
            ella, la solicitud se rechaza con `400 INVALID_PARAMETERS`: "The
            header 'x-idempotency-key' is required."
          schema:
            type: string
            format: uuid
        - name: payment_id
          in: path
          required: true
          description: El `id` del pago devuelto por `POST /v2/payments`.
          schema:
            type: string
            format: uuid
        - name: transaction_id
          in: path
          required: true
          description: >-
            El `id` de la transacción de la tarjeta sobre la que operar, de
            `payment_method.payment_methods[].transactions[]`.
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - merchant_reference
              properties:
                description:
                  type: string
                  description: Descripción del reembolso. (MAX 255; MIN 3).
                reason:
                  type: string
                  description: >-
                    Motivo de la operación. Los valores posibles son
                    `DUPLICATE`, `FRAUDULENT` y `REQUESTED_BY_CUSTOMER`.
                  enum:
                    - DUPLICATE
                    - FRAUDULENT
                    - REQUESTED_BY_CUSTOMER
                merchant_reference:
                  type: string
                  description: >-
                    Identificación de la transacción de pago definida por el
                    comercio (MAX 255; MIN 3).
                amount:
                  type: object
                  description: >-
                    Opcional. Monto a reembolsar en esta tarjeta. Si lo omites,
                    la tarjeta se reembolsa por completo.
                  required:
                    - currency
                    - value
                  properties:
                    currency:
                      type: string
                      description: Código de moneda ISO 4217 (3 caracteres).
                      example: BRL
                    value:
                      type: number
                      description: Monto en unidades mayores (múltiplo de 0.0001).
                      example: 300
                customer_payer:
                  type: object
                  description: Indica el objeto customer de los pagos.
                  properties:
                    first_name:
                      type: string
                      description: El nombre del cliente (MAX 255; MIN 3).
                    last_name:
                      type: string
                      description: El apellido del cliente (MAX 255; MIN 3).
                    gender:
                      type: string
                      description: >-
                        El género del cliente (MAX 2; MIN 1). <br/>- M=Masculino
                        <br/>- F=Femenino <br/>- NB=No binario <br/>- NA=No
                        aplica <br/>- NK=No se conoce <br/>- U=Sin definir.
                      enum:
                        - M
                        - F
                        - NB
                        - NA
                        - NK
                        - U
                    date_of_birth:
                      type: string
                      description: >-
                        La fecha de nacimiento del cliente en formato
                        `YYYY-MM-DD` (Longitud: 10).
                    email:
                      type: string
                      description: El correo electrónico del cliente (MAX 255; MIN 3).
                    nationality:
                      type: string
                      description: >-
                        La nacionalidad del cliente (MAX 2; MIN 2; [ISO
                        3166-1](/es/reference/country-reference)).
                    document:
                      type: object
                      description: >-
                        Indica el objeto del documento del cliente, con su
                        número y su tipo.
                      required:
                        - document_number
                        - document_type
                      properties:
                        document_number:
                          type: string
                          description: Número de documento del cliente (MAX 40; MIN 3)
                        document_type:
                          type: string
                          description: >-
                            El tipo de documento del cliente (MAX 6, MIN 2).
                            Accede a la [lista de tipos de
                            documento](/es/reference/country-reference) para más
                            detalles.
                          enum:
                            - DNI
                            - CI
                            - LC
                            - LE
                            - CUIT
                            - CUIL
                            - PAS
                            - CPF
                            - RG
                            - CNH
                            - CNPJ
                            - RUT
                            - RUN
                            - CC
                            - CE
                            - NIT
                            - DUI
                            - PIC
                            - DPI
                            - IFR
                            - INE
                            - CP
                            - RFC
                            - CURP
                            - CIP
                            - CIC
                            - CUI
                            - RUC
                    phone:
                      type: object
                      description: Especifica el objeto de teléfono del cliente.
                      properties:
                        country_code:
                          type: string
                          description: >-
                            El código de país del teléfono del cliente (MAX 3;
                            MIN 1).
                        number:
                          type: string
                          description: >-
                            El número de teléfono del cliente, sin el código de
                            país (MAX 32; MIN 1).
                    billing_address:
                      type: object
                      description: >-
                        Indica el objeto de la dirección de facturación del
                        cliente.
                      properties:
                        address_line_1:
                          type: string
                          description: >-
                            La línea principal de la dirección de facturación
                            del cliente (MAX 255; MIN 3).
                        address_line_2:
                          type: string
                          description: >-
                            La línea secundaria de la dirección de facturación
                            del cliente (MAX 255; MIN 3).
                        city:
                          type: string
                          description: >-
                            La ciudad considerada para la dirección de
                            facturación (MAX 255; MIN 3).
                        country:
                          type: string
                          description: >-
                            El país considerado para la dirección de facturación
                            (MAX 2; MIN 2; [ISO
                            3166-1](https://docs.y.uno/es/reference/customers/the-customer-object#country-code-list-iso-3166-1)).
                          enum:
                            - AR
                            - BO
                            - BR
                            - CL
                            - CO
                            - CR
                            - EC
                            - SV
                            - GT
                            - HN
                            - MX
                            - NI
                            - PA
                            - PY
                            - PE
                            - US
                            - UY
                        state:
                          type: string
                          description: >-
                            El estado considerado para la dirección de
                            facturación (MAX 255; MIN 3).
                        zip_code:
                          type: string
                          description: >-
                            El código postal considerado para la dirección de
                            facturación (MAX 10; MIN 5).
                    shipping_address:
                      type: object
                      description: Indica el objeto de la dirección de envío del cliente.
                      properties:
                        address_line_1:
                          type: string
                          description: >-
                            La línea principal de la dirección de envío del
                            cliente (MAX 255; MIN 3).
                        address_line_2:
                          type: string
                          description: >-
                            La línea secundaria de la dirección de envío del
                            cliente (MAX 255; MIN 3).
                        city:
                          type: string
                          description: >-
                            La ciudad considerada para la dirección de envío
                            (MAX 255; MIN 3).
                        country:
                          type: string
                          description: >-
                            El país considerado para la dirección de envío (MAX
                            2; MIN 2; [ISO
                            3166-1](https://docs.y.uno/es/reference/customers/the-customer-object#country-code-list-iso-3166-1)).
                          enum:
                            - AR
                            - BO
                            - BR
                            - CL
                            - CO
                            - CR
                            - EC
                            - SV
                            - GT
                            - HN
                            - MX
                            - NI
                            - PA
                            - PY
                            - PE
                            - US
                            - UY
                        state:
                          type: string
                          description: >-
                            El estado considerado para la dirección de envío
                            (MAX 255; MIN 3).
                        zip_code:
                          type: string
                          description: >-
                            El código postal considerado para la dirección de
                            envío (MAX 10; MIN 5).
                payment_method:
                  type: object
                  description: Especifica el objeto de método de pago para los pagos.
                  properties:
                    detail:
                      type: object
                      description: Indica el objeto con el detalle del método de pago.
                      properties:
                        bank_transfer:
                          type: object
                          description: >-
                            Especifica los detalles del método de pago por
                            transferencia bancaria.
                          properties:
                            account_type:
                              type: string
                              description: Tipo de cuenta bancaria (MAX 255; MIN 3)
                              enum:
                                - CHECKINGS
                                - SAVINGS
                            bank_name:
                              type: string
                              description: Nombre del banco (MAX 255; MIN 3)
                            bank_id:
                              type: string
                              description: ID del banco (MAX 255; MIN 3)
                            beneficiary_name:
                              type: string
                              description: Nombre del titular de la cuenta (MAX 255; MIN 3)
                            bank_account:
                              type: string
                              description: Número de cuenta bancaria (MAX 255; MIN 3)
                            beneficiary_document_type:
                              type: string
                              description: >-
                                Tipo de documento del titular de la cuenta (MAX
                                255; MIN 3)
                            beneficiary_document:
                              type: string
                              description: >-
                                Número de documento del titular de la cuenta
                                (MAX 255; MIN 3)
                            reference:
                              type: string
                              description: >-
                                Código de referencia del usuario (MAX 255; MIN
                                1)
                            bank_account_mask_number:
                              type: string
                              description: >-
                                Número enmascarado de la cuenta bancaria
                                asociada a la transferencia (por ejemplo,
                                ****6789). Es un dato de la cuenta, no del
                                mandato.
                            mandate:
                              type: object
                              description: >-
                                Datos del mandato de débito directo, para los
                                métodos de transferencia bancaria que funcionan
                                con mandatos (por ejemplo, ACH, SEPA, BACS,
                                PAD).
                              properties:
                                id:
                                  type: string
                                  description: >-
                                    Identificador del mandato, tal como lo
                                    entrega el proveedor de pagos.
                                info:
                                  type: string
                                  description: Free-text mandate information.
                                received_status:
                                  type: string
                                  description: >-
                                    Estado del proveedor que indica si se
                                    recibió el mandato. Se reenvía tal como lo
                                    entrega el proveedor de pagos.
                                existing_status:
                                  type: string
                                  description: >-
                                    Estado del proveedor del mandato existente.
                                    Se reenvía tal como lo entrega el proveedor
                                    de pagos.
                                created_at:
                                  type: string
                                  format: date-time
                                  description: >-
                                    Fecha y hora en que se creó el mandato (ISO
                                    8601).
                                updated_at:
                                  type: string
                                  format: date-time
                                  description: >-
                                    Fecha y hora de la última actualización del
                                    mandato (ISO 8601).
      responses:
        '201':
          description: El pago después de la operación, con la estructura v2
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentV2'
              examples:
                One card refunded:
                  value:
                    id: 7c1b6e2a-5f3d-4a8e-9b21-3e4f5a6b7c8d
                    account_id: 493e9374-510a-4201-9e09-de669d75f256
                    description: Order paid with two cards
                    country: BR
                    status: SUCCEEDED
                    sub_status: PARTIALLY_REFUNDED
                    merchant_order_id: order-10045
                    created_at: '2026-10-27T14:02:11.120Z'
                    updated_at: '2026-10-27T14:02:12.300Z'
                    split_payment_methods: true
                    payment_methods_count: 2
                    sdk_action_required: false
                    amount:
                      currency: BRL
                      value: 300
                    checkout:
                      session: null
                    payment_method:
                      capture: true
                      account_updater: false
                      payment_methods:
                        - sequence: 1
                          type: CARD
                          amount:
                            currency: BRL
                            value: 200
                          transactions:
                            - id: d2a4f6b8-1c3e-4a5b-8d7f-9e0a1b2c3d4e
                              type: PURCHASE
                              status: SUCCEEDED
                              category: CARD
                              amount: 200
                              provider_id: YUNO_TEST_PAYMENT_GATEWAY
                              response_code: SUCCEEDED
                              response_message: Transaction successful
                              reason: null
                              description: null
                              merchant_reference: null
                              three_d_secure_action_required: false
                              created_at: '2026-10-27T14:02:11.402Z'
                              updated_at: '2026-10-27T14:02:12.118Z'
                            - id: b6e8d0f2-5a7c-4e9f-8b1d-3c4d5e6f7a8b
                              type: REFUND
                              status: SUCCEEDED
                              category: CARD
                              amount: 200
                              provider_id: YUNO_TEST_PAYMENT_GATEWAY
                              response_code: SUCCEEDED
                              response_message: Transaction successful
                              reason: null
                              description: null
                              merchant_reference: null
                              three_d_secure_action_required: false
                              created_at: '2026-10-27T14:02:11.402Z'
                              updated_at: '2026-10-27T14:02:12.118Z'
                        - sequence: 2
                          type: CARD
                          amount:
                            currency: BRL
                            value: 100
                          transactions:
                            - id: e3b5a7c9-2d4f-4b6c-9e8a-0f1b2c3d4e5f
                              type: PURCHASE
                              status: SUCCEEDED
                              category: CARD
                              amount: 100
                              provider_id: YUNO_TEST_PAYMENT_GATEWAY
                              response_code: SUCCEEDED
                              response_message: Transaction successful
                              reason: null
                              description: null
                              merchant_reference: null
                              three_d_secure_action_required: false
                              created_at: '2026-10-27T14:02:11.402Z'
                              updated_at: '2026-10-27T14:02:12.118Z'
                    customer_payer:
                      id: cfae0941-7234-427a-a739-ef4fce966c79
                      first_name: Ana
                      last_name: Souza
                      email: ana.souza@example.com
                    workflow: DIRECT
                    callback_url: https://merchant.example.com/checkout/return
                    metadata: []
        '400':
          description: >-
            Solicitud no válida. `INVALID_PARAMETERS` cuando falta la clave de
            idempotencia o el monto supera lo que se puede operar;
            `INVALID_STATUS` cuando la tarjeta no admite la operación, por
            ejemplo un reembolso mientras la tarjeta tiene un contracargo
            abierto, o una captura o cancelación mientras el pago está en
            `REFUND_RETRY_IN_PROCESS` o `CANCEL_RETRY_IN_PROCESS`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  messages:
                    type: array
                    items:
                      type: string
              examples:
                Missing idempotency key:
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - The header 'x-idempotency-key' is required.
        '401':
          description: Credenciales no válidas
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  messages:
                    type: array
                    items:
                      type: string
              example:
                code: INVALID_CREDENTIALS
                messages:
                  - Invalid credentials
components:
  schemas:
    PaymentV2:
      type: object
      description: Un pago financiado con dos tarjetas.
      properties:
        id:
          type: string
          format: uuid
        account_id:
          type: string
          format: uuid
        description:
          type: string
        country:
          type: string
        status:
          type: string
          description: >-
            Estado agregado del pago. Consulta [Pagar con dos
            tarjetas](/es/docs/payment-features/pay-with-two-cards#statuses).
        sub_status:
          type: string
          description: >-
            Subestado agregado, por ejemplo `APPROVED`, `AUTHORIZED`,
            `PARTIALLY_CAPTURED`, `PARTIALLY_REFUNDED`,
            `REFUND_RETRY_IN_PROCESS` o `CANCEL_RETRY_IN_PROCESS`.
        merchant_order_id:
          type: string
        merchant_reference:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        split_payment_methods:
          type: boolean
          description: '`true` para un pago financiado con dos tarjetas.'
        payment_methods_count:
          type: integer
          description: 'Número de tarjetas que financian el pago: `2`.'
        sdk_action_required:
          type: boolean
          description: >-
            `true` cuando el SDK debe continuar el pago, por ejemplo para
            ejecutar un desafío 3DS.
        amount:
          type: object
          description: Total del pago.
          required:
            - currency
            - value
          properties:
            currency:
              type: string
              description: Código de moneda ISO 4217 (3 caracteres).
              example: BRL
            value:
              type: number
              description: Monto en unidades mayores (múltiplo de 0.0001).
              example: 300
        checkout:
          type: object
          properties:
            session:
              type:
                - string
                - 'null'
        payment_method:
          type: object
          properties:
            capture:
              type: boolean
              description: Configuración de captura compartida por ambas tarjetas.
            account_updater:
              type:
                - boolean
                - 'null'
            payment_methods:
              type: array
              description: >-
                Una entrada por tarjeta. No hay un estado por tarjeta: lee el
                resultado de cada tarjeta en sus `transactions`.
              minItems: 2
              maxItems: 2
              items:
                type: object
                properties:
                  sequence:
                    type: integer
                    description: 'Posición de la tarjeta: `1` o `2`.'
                  type:
                    type: string
                    enum:
                      - CARD
                  amount:
                    type: object
                    description: Parte del total que paga esta tarjeta.
                    required:
                      - currency
                      - value
                    properties:
                      currency:
                        type: string
                        description: Código de moneda ISO 4217 (3 caracteres).
                        example: BRL
                      value:
                        type: number
                        description: Monto en unidades mayores (múltiplo de 0.0001).
                        example: 300
                  payment_method_detail:
                    type: object
                    description: Detalles de la tarjeta, como en el objeto de pago v1.
                  payment_method_owner:
                    type: object
                    description: Titular de la tarjeta, cuando se envía en la solicitud.
                  transactions:
                    type: array
                    description: >-
                      Transacciones de esta tarjeta. Una tarjeta que pasó por
                      3DS muestra `THREE_D_SECURE` seguido de `PURCHASE` o
                      `AUTHORIZE`.
                    items:
                      type: object
                      description: >-
                        Una transacción de la tarjeta. Lee el resultado de la
                        tarjeta en sus transacciones.
                      properties:
                        id:
                          type: string
                          format: uuid
                          description: >-
                            Id de la transacción. Úsalo en las operaciones por
                            transacción.
                        type:
                          type: string
                          description: >-
                            Tipo de transacción, por ejemplo `THREE_D_SECURE`,
                            `PURCHASE`, `AUTHORIZE`, `CAPTURE`, `CANCEL` o
                            `REFUND`.
                        status:
                          type: string
                          description: >-
                            Estado de esta transacción, por ejemplo `SUCCEEDED`,
                            `DECLINED`, `PENDING` o `ERROR`.
                        category:
                          type: string
                          example: CARD
                        amount:
                          type: number
                          description: Monto de esta transacción.
                        provider_id:
                          type: string
                          description: Proveedor que procesó la transacción.
                        response_code:
                          type: string
                          description: Código de respuesta de Yuno de la transacción.
                        response_message:
                          type: string
                        reason:
                          type:
                            - string
                            - 'null'
                        description:
                          type:
                            - string
                            - 'null'
                        merchant_reference:
                          type:
                            - string
                            - 'null'
                        three_d_secure_action_required:
                          type:
                            - boolean
                            - 'null'
                        created_at:
                          type: string
                          format: date-time
                        updated_at:
                          type:
                            - string
                            - 'null'
                          format: date-time
        customer_payer:
          type: object
          description: El pagador, tal como se envió en la solicitud.
        additional_data:
          type:
            - object
            - 'null'
        callback_url:
          type: string
        workflow:
          type: string
          enum:
            - DIRECT
            - REDIRECT
            - SDK_CHECKOUT
        metadata:
          type: array
          items:
            type: object
  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.