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

# Cancelar pago

> Cancela un pago pendiente antes de que se complete y actualiza su estado a cancelado.

Un pago con estado **PENDING** debido al estado **AUTHORIZE** de una transacción se puede cancelar antes de completarse si el pago ya no es necesario. Enviar una solicitud de cancelación actualizará el estado del pago a **CANCELLED**.

> [!WARNING]
>
> **Pagos con 3DS**
>
> Los pagos en estado **PENDING** debido a la autenticación 3DS no se pueden cancelar. Estos pagos están en un estado temporal a la espera de la autenticación del usuario. El estado del pago se actualizará automáticamente a **FRAUD VERIFIED** o **CANCELLED** según el resultado del proceso de autenticación.

> [!NOTE]
>
> **Métodos de pago alternativos**
>
> Los métodos de pago alternativos como PIX también admiten la cancelación de pagos con estado PENDING. Comunícate con tu gerente técnico de cuenta para obtener más información.

Si necesitas un comprobante de la transacción cancelada, puedes obtenerlo después de que se haya creado. Para hacerlo, usa el endpoint [Retrieve Payment by ID](https://docs.y.uno/es/reference/payments/retrieve-payment-by-id-v2.md) y revisa el campo `receipt_url` en el objeto `payment.transaction`. Consulta [The Payment Object](https://docs.y.uno/es/reference/payments/the-payment-object.md) para `receipt`, `receipt_url` y `receipt_language`.

Para usar este endpoint, debes enviar un `X-Idempotency-Key` en tu solicitud. Consulta la página [Authentication](https://docs.y.uno/es/reference/getting-started/authentication.md#idempotency) para obtener más información.


## OpenAPI

````yaml openapi/es/payments/cancel-payment.json POST /payments/{payment_id}/transactions/{transaction_id}/cancel
openapi: 3.1.0
info:
  title: payment-api-refundcancel-payment
  version: 1.0.2
servers:
  - url: https://api-sandbox.y.uno/v1
    description: Sandbox
  - url: https://api.y.uno/v1
    description: Production (US)
security:
  - sec0: []
    sec1: []
    sec2: []
paths:
  /payments/{payment_id}/transactions/{transaction_id}/cancel:
    post:
      summary: Cancelar pago
      operationId: cancel-payment
      parameters:
        - name: payment_id
          in: path
          description: El identificador único del pago (UUID, 36 caracteres).
          schema:
            type: string
          required: true
        - name: transaction_id
          in: path
          description: El identificador único de la transacción (UUID, 36 caracteres).
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - merchant_reference
              properties:
                description:
                  type: string
                  description: Descripción de la cancelación. (MAX 255; MIN 3)
                reason:
                  type: string
                  description: >-
                    Motivo de la cancelación. Los valores pueden ser
                    `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).
                response_additional_data:
                  type: object
                  description: >-
                    Especifica datos adicionales requeridos para la respuesta de
                    la transacción
                  properties:
                    receipt:
                      type: boolean
                      description: >-
                        Indica si se necesita un comprobante en la respuesta de
                        la transacción
                    receipt_language:
                      type: string
                      description: Indica el idioma del comprobante que se generará
                      enum:
                        - ES
                        - EN
                        - PT
                    transactions_history:
                      type: boolean
                      description: >-
                        Cuando es true, incluye el historial de transacciones en
                        la respuesta
                    raw_request:
                      type: boolean
                      description: >-
                        Cuando es true, incluye en la salida la solicitud sin
                        procesar del proveedor
                    raw_response:
                      type: boolean
                      description: >-
                        Cuando es true, incluye en la salida la respuesta sin
                        procesar del proveedor
            examples:
              Request Example:
                value:
                  description: Duplicate
                  reason: REQUESTED_BY_CUSTOMER
                  merchant_reference: AAB01-432245
      responses:
        '201':
          description: '201'
          content:
            application/json:
              examples:
                Result:
                  value:
                    id: 438bea6c-9061-4416-b824-469c3c05868d
                    type: CANCEL
                    status: SUCCEEDED
                    category: CARD
                    amount:
                      captured: 0
                      currency: USD
                      currency_conversion: null
                      refunded: 0
                      value: 30000
                    merchant_reference: ''
                    created_at: '2024-06-06T14:03:08.384014Z'
                    updated_at: '2024-06-06T14:03:08.453617Z'
                    provider_data:
                      id: YUNO_TEST_PAYMENT_GW
                      transaction_id: ''
                      account_id: ''
                      status: SUCCEEDED
                      sub_status: ''
                      status_detail: SUCCEEDED
                      response_message: null
                      response_code: SUCCEEDED
                      raw_response:
                        message: provider response
                      third_party_transaction_id: null
                      third_party_account_id: null
                      iso8583_response_code: '00'
                      iso8583_response_message: Approved or completed successfully
                    connection_data:
                      id: 58cc35f4-faef-4107-8e09-d18d60121d38
                      name: Connection name
                    response_code: SUCCEEDED
                    response_message: Transaction successful
                    payment:
                      id: 2d6f75c1-c4bc-4d2d-80ec-0af4d12c85da
                      account_id: ''
                      description: Test
                      country: US
                      status: CANCELED
                      sub_status: CANCELED
                      merchant_order_id: '0000023'
                      created_at: '2024-06-06T14:01:34.286228Z'
                      updated_at: '2024-06-06T14:03:08.484781Z'
                      amount:
                        captured: 0
                        currency: USD
                        currency_conversion: null
                        refunded: 0
                        value: 30000
                      split_marketplace: []
                    customer_payer: null
                    simplified_mode: false
                    receipt: false
                    receipt_url: null
                    receipt_language: null
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 438bea6c-9061-4416-b824-469c3c05868d
                  type:
                    type: string
                    example: CANCEL
                  status:
                    type: string
                    example: SUCCEEDED
                  category:
                    type: string
                    example: CARD
                  amount:
                    type: object
                    properties:
                      captured:
                        type: integer
                        example: 0
                        default: 0
                      currency:
                        type: string
                        example: USD
                      currency_conversion: {}
                      refunded:
                        type: integer
                        example: 0
                        default: 0
                      value:
                        type: integer
                        example: 30000
                        default: 0
                  merchant_reference:
                    type: string
                    example: ''
                  created_at:
                    type: string
                    example: '2024-06-06T14:03:08.384014Z'
                  updated_at:
                    type: string
                    example: '2024-06-06T14:03:08.453617Z'
                  provider_data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: YUNO_TEST_PAYMENT_GW
                      transaction_id:
                        type: string
                        example: ''
                      account_id:
                        type: string
                        example: ''
                      status:
                        type: string
                        example: SUCCEEDED
                      sub_status:
                        type: string
                        example: ''
                      status_detail:
                        type: string
                        example: SUCCEEDED
                      response_message: {}
                      response_code:
                        type: string
                        example: SUCCEEDED
                      raw_request:
                        type: object
                        description: >-
                          Copia ofuscada de la solicitud que Yuno envió al
                          proveedor. Solo se devuelve para organizaciones
                          autorizadas.
                      raw_response:
                        type: object
                        properties:
                          message:
                            type: string
                            example: provider response
                      third_party_transaction_id: {}
                      third_party_account_id: {}
                      iso8583_response_code:
                        type: string
                        example: '00'
                      iso8583_response_message:
                        type: string
                        example: Approved or completed successfully
                  connection_data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: 58cc35f4-faef-4107-8e09-d18d60121d38
                      name:
                        type: string
                        example: Connection name
                  response_code:
                    type: string
                    example: SUCCEEDED
                  response_message:
                    type: string
                    example: Transaction successful
                  payment:
                    type: object
                    properties:
                      id:
                        type: string
                        example: 2d6f75c1-c4bc-4d2d-80ec-0af4d12c85da
                      account_id:
                        type: string
                        example: ''
                      description:
                        type: string
                        example: Test
                      country:
                        type: string
                        example: US
                      status:
                        type: string
                        example: CANCELED
                      sub_status:
                        type: string
                        example: CANCELED
                      merchant_order_id:
                        type: string
                        example: '0000023'
                      created_at:
                        type: string
                        example: '2024-06-06T14:01:34.286228Z'
                      updated_at:
                        type: string
                        example: '2024-06-06T14:03:08.484781Z'
                      amount:
                        type: object
                        properties:
                          captured:
                            type: integer
                            example: 0
                            default: 0
                          currency:
                            type: string
                            example: USD
                          currency_conversion: {}
                          refunded:
                            type: integer
                            example: 0
                            default: 0
                          value:
                            type: integer
                            example: 30000
                            default: 0
                      discount_amount:
                        type: object
                        description: >-
                          El descuento total de la promoción de Yuno aplicada al
                          pago: la suma de las líneas `YUNO_PROMOTION` de
                          `additional_data.order.discounts`. No aparece cuando
                          no se aplicó ninguna promoción. El monto cobrado es
                          `amount.value` menos este valor, y está en
                          `transactions.amount`. Consulta
                          [Promociones](/es/docs/payment-features/promotions).
                        properties:
                          currency:
                            type: string
                            description: >-
                              La moneda del descuento, la misma que
                              `amount.currency`.
                          value:
                            type: number
                            description: El descuento.
                      split_marketplace:
                        type: array
                  customer_payer: {}
                  simplified_mode:
                    type: boolean
                    example: false
                    default: true
                  receipt:
                    type: boolean
                    example: false
                    default: true
                  receipt_url: {}
                  receipt_language: {}
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - Invalid request
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: INVALID_REQUEST
                  messages:
                    type: array
                    items:
                      type: string
                      example: Invalid request
        '401':
          description: '401'
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    code: INVALID_CREDENTIALS
                    messages:
                      - Invalid credentials
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: INVALID_CREDENTIALS
                  messages:
                    type: array
                    items:
                      type: string
                      example: Invalid credentials
        '403':
          description: '403'
          content:
            application/json:
              examples:
                Forbidden:
                  value:
                    code: AUTHORIZATION_REQUIRED
                    messages:
                      - The merchant has no authorization to use this API.
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: AUTHORIZATION_REQUIRED
                  messages:
                    type: array
                    items:
                      type: string
                      example: The merchant has no authorization to use this API.
      deprecated: false
components:
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      x-default: <Your public-api-key>
      name: public-api-key
    sec1:
      type: apiKey
      in: header
      x-default: <Your private-secret-key>
      name: private-secret-key
    sec2:
      type: apiKey
      in: header
      x-default: <Your X-Idempotency-Key>
      name: X-Idempotency-Key

````

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