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

# Payloads y ejemplos

> Documenta los atributos del payload de los webhooks con ejemplos JSON de pagos, contracargos, inscripciones, payouts y suscripciones

## Atributos del webhook

A continuación se listan los atributos JSON de los webhooks de Yuno. Consulta [Events and Triggers](https://docs.y.uno/es/docs/webhooks/events.md) para ver el campo trigger que selecciona cada evento.

**account\_id** `string`

El identificador único de la cuenta en Yuno (MAX 64, MIN 36).

**type** `string`

Especifica el tipo de notificación.

**type\_event** `string`

Especifica el tipo de notificación del evento.

**version** `string`

Especifica la versión del webhook enviado. Actualmente 2.

**retry** `string`

Especifica el número de reintentos de esa notificación.

**data** `object`

Especifica el [pago](https://docs.y.uno/reference/payments/the-payment-object.md) (para el tipo payment) o el [objeto de método de pago](https://docs.y.uno/reference/payment-methods-direct-workflow/the-payment-method-object-api.md) (para inscripciones y otros objetos).

**propiedades**

**idempotency\_key** `string`

Identificador que se usa para omitir entregas duplicadas. Se mantiene estable en todos los reintentos del mismo evento. Su ubicación depende del evento: los eventos de pago ordinarios (incluidos reembolso y contracargo) lo incluyen en `data.payment.idempotency_key`, `payment.split_update` lo incluye en `data.split_update.idempotency_key` y los eventos de suscripción lo incluyen en `data.idempotency_key`. En los eventos `subscription.*` identifica la suscripción y no el evento, por lo que debes eliminar los duplicados de esos eventos usando `type_event` junto con esta clave. Consulta [De-duplication](https://docs.y.uno/docs/webhooks.md#de-duplication) para ver los detalles de cobertura.

**x-hmac-signature** `string`

Opcional. La firma HMAC-SHA256 que se envía en el encabezado HTTP para la verificación del webhook cuando la autenticación HMAC está habilitada.

## Webhooks de actualización de split

Estos ejemplos abreviados muestran solo los campos necesarios para interpretar `payment.split_update`; también se incluyen los campos normales del pago. Este evento requiere una suscripción explícita y está pendiente de disponibilidad en el catálogo de producción.

En v2, el sobre identifica `type_event: "payment.split_update"` y el bloque de la operación es `data.split_update`:

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "payment",
  "type_event": "payment.split_update",
  "version": 2,
  "retry": 0,
  "data": {
    "split_update": {
      "idempotency_key": "4a518553-a6e7-4717-a415-06084ea85c99",
      "updated_at": "2026-09-22T04:20:00Z"
    },
    "payment": {
      "transactions": {
        "split_marketplace": []
      }
    }
  }
}
```

Este ejemplo borra el split, por lo que el `split_marketplace` de la operación es `[]`. Un reemplazo aplicado incluye en su lugar las entradas de split de esa operación. `transactions` es un único objeto, no un arreglo.

El v1 heredado envía el cuerpo del pago sin el sobre v2 ni `type_event`. Identifica este evento por el bloque `split_update` junto a `payment`:

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "split_update": {
    "idempotency_key": "4a518553-a6e7-4717-a415-06084ea85c99",
    "updated_at": "2026-09-22T04:20:00Z"
  },
  "payment": {
    "transactions": {
      "split_marketplace": []
    }
  }
}
```

| Campo | Significado |
| - | - |
| `split_update.idempotency_key` | La clave de la solicitud original de actualización de split. Úsala para distinguir operaciones y eliminar entregas duplicadas, dentro del alcance de la cuenta y el tipo de evento. |
| `split_update.updated_at` | La hora de finalización registrada de la operación, que se conserva en la resolución repetida y en la notificación retrasada. |
| `payment.transactions.split_marketplace` | La instantánea del split de la operación seleccionada, incluido `[]` cuando se borra. |

Si `transactions_history` está habilitado, su entrada para la transacción afectada incluye el mismo split de la operación. El evento no habilita el historial ni reemplaza el `payment.split_marketplace` a nivel de pago; no uses ese campo a nivel de pago como la instantánea de esta operación. Los demás campos reflejan la lectura del pago cuando se prepara la notificación y pueden incluir cambios posteriores. Usa `GET /v1/payments/{payment_id}` para obtener el estado más reciente del pago.

No se garantiza que la instantánea de la operación se serialice igual que una lectura posterior del pago. La escala numérica puede variar (por ejemplo, `5` frente a `5.0`) y un objeto de responsabilidad que contenga solo `chargebacks` puede representarse de forma distinta en el mapeo del pago activo. Compara los valores y su significado, en lugar de exigir igualdad byte por byte del JSON. Estas diferencias de representación no identifican una nueva operación de split.

Solo este evento agrega `split_update`; los payloads de compra y de reembolso no incorporan el bloque. Consulta [Split update notifications](https://docs.y.uno/docs/webhooks.md#split-update-notifications) para conocer el comportamiento de suscripción, emisión, orden y entrega.

## Ejemplos

Yuno ofrece varios webhooks relacionados con notificaciones de inscripción y de pago. Aquí encontrarás algunos ejemplos de estructuras de datos relacionadas con cada evento.

> [card] [Webhook de pago V2](#payment-webhook-v2)

> [card] [Webhook de pago V1](#payment-webhook-v1)

> [card] [Webhook de contracargo V2](#chargeback-webhook-v2)

> [card] [Webhook de contracargo V1](#chargeback-webhook-v1)

> [card] [Inscripción](#enrollment)

> [card] [Payouts](#payouts)

> [card] [Suscripciones](#subscriptions)

> [card] [Onboardings](#onboardings)

> [card] [Reembolsos](#refunds)

> [card] [Transferencias de split de marketplace](#marketplace-split-transfers)

> [card] [HMAC - Autorización](#hmac---authorization)

## Pago

### Webhook de pago V2

Payload de ejemplo:

> [!NOTE]
>
> Los payloads de webhook de los eventos correspondientes a un método de pago de transferencia bancaria incluyen `payment.payment_method.payment_method_detail.bank_transfer.bank_id`. El campo refleja el `bank_id` enviado en la solicitud de pago original y se omite cuando no se seleccionó ningún banco.

> [!NOTE]
>
> Cuando el pago incluye una selección de envío (por ejemplo, elegida dentro de un widget de billetera con [Fast Checkout shipping](https://docs.y.uno/es/docs/payment-features/fast-checkout-shipping.md)), el payload incluye un nodo `payment.shipping` de nivel superior (con la misma forma que en [el objeto de pago](https://docs.y.uno/reference/payments/the-payment-object.md)) tanto en la versión V1 como en la V2, y `payment.customer_payer.shipping_address` se completa a partir de él cuando el pagador no tenía ninguna. La clave `shipping` se omite cuando el pago no tiene una selección.

> [!NOTE]
>
> Cada transacción incluye `connection_data`, que identifica la conexión del proveedor que la procesó. Usa `connection_data.id` como identificador estable para atribuir las transacciones a una conexión específica cuando operas varias conexiones para el mismo proveedor. `connection_data.name` es el nombre para mostrar configurado en el Dashboard de Yuno y puede ser `null` en algunos eventos, como las transacciones de seguimiento.

> [!NOTE]
>
> El campo `transactions` tiene un significado distinto según la superficie. En los payloads de webhook, `data.payment.transactions` es un **único objeto** (la transacción que activó el evento), y `transactions_history` incluye la lista completa de las transacciones del pago cuando está habilitado para el pago (consulta la nota siguiente). En los endpoints de consulta de pagos (`GET /payments/{payment_id}` y `GET /payments?merchant_order_id=`), `transactions` es un **arreglo** que contiene todas las transacciones del pago.

> [!NOTE]
>
> `transactions_history` es **opt-in**: solo se completa cuando el pago se creó con `response_additional_data.transactions_history: true` en la solicitud de [Create Payment](https://docs.y.uno/es/reference/payments/create-payment.md). De lo contrario, los webhooks lo entregan como un arreglo vacío `[]` (el valor predeterminado, que mantiene pequeño el tamaño de los payloads). Esto importa en los pagos que tu enrutamiento reintenta entre proveedores: sin el indicador, el webhook final muestra solo la última transacción, y los intentos anteriores solo se ven mediante `GET /payments/{payment_id}`. Los pagos creados por flujos administrados por Yuno que no establecen el indicador (por ejemplo, las renovaciones de suscripción) también entregan `[]`. Los eventos de contracargo siempre incluyen el historial completo.

> [!NOTE]
>
> Nombre de los campos: la geolocalización del cliente se serializa como `geo_location` en los payloads de webhook y como `geolocation` en los endpoints de consulta de pagos. Procesa cada superficie según corresponda.

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
    "type": "payment",
    "type_event": "payment.purchase",
    "account_id": "2c05976d-1234-1234-1234-6421883de48d",
    "retry": 0,
    "version": 2,
    "data": {
        "payment": {
            "id": "a546c566-1703-4fba-b334-c46e89bc97f7",
            "account_id": "2c05976d-1234-1234-1234-6421883de48d",
            "description": "Testing Yuno",
            "country": "UY",
            "status": "SUCCEEDED",
            "sub_status": "APPROVED",
            "order_id": "Order1234",
            "merchant_order_id": "Test1234",
            "created_at": "2024-07-19T16:31:59.528561Z",
            "updated_at": "2024-07-19T16:32:02.203776Z",
            "idempotency_key": "9e2aba6a-1234-1234-1234-03a0a67ee15f",
            "amount": {
                "currency": "UYU",
                "value": 1458,
                "refunded": 0,
                "captured": 0
            },
            "checkout": {
                "session": "2f3423dd-1234-1234-1234-2c7da5ad1caf",
                "sdk_action_required": false
            },
            "customer_payer": {
                "id": "96bf8513-1234-1234-1234-0087b2a60535",
                "merchant_customer_id": "user1234",
                "first_name": "harry ",
                "last_name": "potter ",
                "gender": "",
                "date_of_birth": null,
                "email": "testing6@y.uno",
                "nationality": null,
                "ip_address": "123.123.123.27",
                "device_fingerprint": null,
                "third_party_session_id": "third_party_session_id",
                "merchant_customer_created_at": "2019-01-08T18:38:55.617Z",
                "browser_info": {
                    "user_agent": "Yuno's/20979 CFNetwork/1496.0.7 Darwin/23.5.0",
                    "accept_header": "*/*",
                    "color_depth": null,
                    "screen_height": "844.0",
                    "screen_width": "390.0",
                    "javascript_enabled": null,
                    "language": "es-UY",
                    "accept_content": null,
                    "accept_browser": null,
                    "java_enabled": null,
                    "browser_time_difference": null
                },
                "document": {
                    "document_number": "99999999",
                    "document_type": "CI"
                },
                "billing_address": {
                    "address_line_1": "GEANT - Av. A la Playa y calle de 17",
                    "address_line_2": "",
                    "city": "Canelones",
                    "country": "UY",
                    "state": "Canelones",
                    "zip_code": "-",
                    "neighborhood": null
                },
                "shipping_address": {
                    "address_line_1": "GEANT - Av. A la Playa y calle de 17",
                    "address_line_2": "",
                    "city": "Canelones",
                    "country": "UY",
                    "state": "Canelones",
                    "zip_code": "-",
                    "neighborhood": null
                },
                "phone": {
                    "country_code": "598",
                    "number": "12345678"
                }
            },
            "shipping": {
                "method": {
                    "id": "express",
                    "label": "Express shipping",
                    "amount": {
                        "currency": "GBP",
                        "value": 5.00
                    }
                },
                "address": {
                    "address_line_1": "221B Baker Street",
                    "address_line_2": "Flat 2",
                    "city": "London",
                    "state": "England",
                    "zip_code": "NW1 6XE",
                    "country": "GB"
                }
            },
            "additional_data": {
                "order": {
                    "shipping_amount": 0,
                    "fee_amount": null,
                    "tip_amount": null,
                    "items": [
                        {
                            "id": "item123",
                            "name": "Yuno Testing",
                            "quantity": 1,
                            "unit_amount": 1458,
                            "category": "services",
                            "brand": null,
                            "sku_code": null,
                            "manufacture_part_number": null,
                            "image_url": null
                        }
                    ],
                    "taxes": [],
                    "discounts": []
                },
                "airline": null,
                "seller_details": null
            },
            "transactions": {
                "id": "3a35add9-89d6-4b11-9f17-24a76f4d046e",
                "type": "PURCHASE",
                "status": "SUCCEEDED",
                "category": "CARD",
                "amount": 1458,
                "provider_id": "YUNO_TEST_PAYMENT_GW",
                "response_code": "SUCCEEDED",
                "merchant_reference": "Test1234",
                "response_message": "Transaction successful",
                "reason": null,
                "description": "Testing Yuno",
                "created_at": "2024-07-19T16:31:59.617130Z",
                "updated_at": "2024-07-19T16:32:02.138835Z",
                "payment_method": {
                    "token": "902f17f9-1234-1234-1234-3322f5ebdbb5",
                    "type": "CARD",
                    "vaulted_token": "795b4f2e-1234-1234-1234-fcc1930d5d4c",
                    "vault_on_success": false,
                    "payment_method_detail": {
                        "card": {
                            "verify": null,
                            "capture": true,
                            "installments": 1,
                            "installments_plan_id": null,
                            "first_installment_deferral": null,
                            "installments_amount": null,
                            "installments_type": null,
                            "soft_descriptor": "",
                            "authorization_code": "123456",
                            "retrieval_reference_number": "",
                            "acquirer_reference_number": "",
                            "voucher": null,
                            "card_data": {
                                "holder_name": "HARRY POTTER",
                                "iin": "51584511",
                                "lfd": "1234",
                                "number_length": 16,
                                "security_code_length": 3,
                                "brand": "MASTERCARD",
                                "issuer_name": "ECONSTAR SA",
                                "issuer_code": null,
                                "category": "MRG - Prepaid MasterCard Card",
                                "type": "CREDIT",
                                "three_d_secure": {
                                    "version": null,
                                    "electronic_commerce_indicator": null,
                                    "cryptogram": null,
                                    "transaction_id": null,
                                    "directory_server_transaction_id": null,
                                    "pares_status": null,
                                    "acs_id": null
                                },
                                "network_token": null,
                                "fingerprint": null
                            },
                            "stored_credentials": {
                                "reason": null,
                                "usage": null
                            }
                        },
                        "wallet": null,
                        "bnpl": null,
                        "bank_transfer": null,
                        "ticket": null,
                        "payment_link": null
                    }
                },
                "provider": {
                    "provider_transaction_id": "YUNO-51056-b673b951-aaa-aaa-aaa-123489aee2e0"
                },
                "provider_data": {
                    "raw_response": {
                        "value": "provider raw response"
                    },
                    "id": "DLOCAL",
                    "transaction_id": "YUNO-51056-b673b951-aaa-aaa-aaa-123489aee2e0",
                    "account_id": "699ec8d444",
                    "status": "PAID",
                    "status_detail": null,
                    "response_message": "The payment was paid.",
                    "response_code": "200",
                    "third_party_transaction_id": "",
                    "third_party_account_id": ""
                },
                "connection_data": {
                    "id": "88292fd3-bf5b-4b23-bb95-7186ba4e7f88",
                    "name": "dLocal US"
                },
                "simplified_mode": false,
                "third_party_session_id": "third_party_session_id"
            },
            "transactions_history": [
                {
                    "id": "3a35add9-89d6-4b11-9f17-24a76f4d046e",
                    "type": "PURCHASE",
                    "status": "SUCCEEDED",
                    "category": "CARD",
                    "amount": 1458,
                    "provider_id": "YUNO_TEST_PAYMENT_GW",
                    "response_code": "SUCCEEDED",
                    "merchant_reference": "Test1234",
                    "response_message": "Transaction successful",
                    "reason": null,
                    "description": "Testing Yuno",
                    "created_at": "2024-07-19T16:31:59.617130Z",
                    "updated_at": "2024-07-19T16:32:02.138835Z",
                    "payment_method": {
                        "token": "902f17f9-1234-1234-1234-3322f5ebdbb5",
                        "type": "CARD",
                        "vaulted_token": "795b4f2e-1234-1234-1234-fcc1930d5d4c",
                        "vault_on_success": false,
                        "payment_method_detail": {
                            "card": {
                                "verify": null,
                                "capture": true,
                                "installments": 1,
                                "installments_plan_id": null,
                                "first_installment_deferral": null,
                                "installments_amount": null,
                                "installments_type": null,
                                "soft_descriptor": "",
                                "authorization_code": "123456",
                                "retrieval_reference_number": "",
                                "acquirer_reference_number": "",
                                "voucher": null,
                                "card_data": {
                                    "holder_name": "HARRY POTTER",
                                    "iin": "51584511",
                                    "lfd": "1234",
                                    "number_length": 16,
                                    "security_code_length": 3,
                                    "brand": "MASTERCARD",
                                    "issuer_name": "ECONSTAR SA",
                                    "issuer_code": null,
                                    "category": "MRG - Prepaid MasterCard Card",
                                    "type": "CREDIT",
                                    "three_d_secure": {
                                        "version": null,
                                        "electronic_commerce_indicator": null,
                                        "cryptogram": null,
                                        "transaction_id": null,
                                        "directory_server_transaction_id": null,
                                        "pares_status": null,
                                        "acs_id": null
                                    },
                                    "network_token": null,
                                    "fingerprint": null
                                },
                                "stored_credentials": {
                                    "reason": null,
                                    "usage": null
                                }
                            },
                            "wallet": null,
                            "bnpl": null,
                            "bank_transfer": null,
                            "ticket": null,
                            "payment_link": null
                        }
                    },
                    "provider": {
                        "provider_transaction_id": "YUNO-51056-b673b951-aaa-aaa-aaa-123489aee2e0"
                    },
                    "provider_data": {
                        "raw_response": {
                            "value": "raw_response"
                        },
                        "id": "DLOCAL",
                        "transaction_id": "YUNO-51056-b673b951-aaa-aaa-aaa-123489aee2e0",
                        "account_id": "699ec8d444",
                        "status": "PAID",
                        "status_detail": null,
                        "response_message": "The payment was paid.",
                        "response_code": "200",
                        "third_party_transaction_id": "",
                        "third_party_account_id": ""
                    },
                    "connection_data": {
                        "id": "88292fd3-bf5b-4b23-bb95-7186ba4e7f88",
                        "name": "dLocal US"
                    },
                    "simplified_mode": false,
                    "third_party_session_id": "json object"
                }
            ],
            "callback_url": null,
            "workflow": "SDK_CHECKOUT",
            "split": [],
            "payment_link_code": "",
            "subscription_id": null,
            "fraud_screening": null,
            "metadata": [],
            "routing_rules": {
                "condition": {
                    "id": 222770,
                    "name": null,
                    "description": null
                }
            }
        }
    }
}
```

> [!NOTE]
>
> Los pagos creados con un objeto `external_subscription` (consulta [Create payment](https://docs.y.uno/es/reference/payments/create-payment.md)) lo incluyen en el payload del webhook dentro del objeto de pago (`data.payment` en el payload v2), como una clave `external_subscription` con `id` y `customer_id`. La clave se **omite** (no se envía como `null`) cuando el pago se creó sin ella, por eso el ejemplo anterior no la muestra. Ambas versiones del webhook incluyen el campo.
>
> Los pagos creados con un objeto `external_invoice` (consulta [Pay a Stripe invoice (top-ups)](https://docs.y.uno/es/docs/payment-features/subscriptions/stripe-billing-top-ups.md)) lo incluyen en los webhooks de pago, por ejemplo `payment.purchase`, como una clave `external_invoice` con `id` y `customer_id`. En el payload v2 anterior, la clave está dentro de `data.payment`. Se **omite** cuando el pago se creó sin ella.

> [!NOTE]
>
> Cuando el pago incluye una [promoción de Yuno](https://docs.y.uno/docs/payment-features/promotions), el payload también incluye `payment.discount_amount` (`currency` y `value`, el descuento total), ubicado justo después de `amount`. La línea de descuento de Yuno aparece primero en `payment.additional_data.order.discounts` (`type: YUNO_PROMOTION`, `quote_id`, `id`, `unit_amount` y `name` cuando Yuno lo tiene), y tus propias líneas de descuento van a continuación con `type: MERCHANT`. `payment.amount.value` sigue siendo el monto que enviaste, y `payment.transactions.amount` es el monto cobrado. Sin una promoción, `discount_amount` se omite y las líneas de descuento son exactamente las que enviaste. Ambas versiones del webhook incluyen el campo. El extracto siguiente muestra solo los campos que cambian.

```json Payment with a Yuno promotion (excerpt) theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
    "type": "payment",
    "type_event": "payment.purchase",
    "version": 2,
    "data": {
        "payment": {
            "status": "SUCCEEDED",
            "sub_status": "APPROVED",
            "amount": {
                "currency": "USD",
                "value": 250.0,
                "refunded": 0.0,
                "captured": 0.0
            },
            "discount_amount": {
                "currency": "USD",
                "value": 25.0
            },
            "additional_data": {
                "order": {
                    "discounts": [
                        {
                            "type": "YUNO_PROMOTION",
                            "id": "b7c1a4f2-6e0d-4a3b-9c55-1f2e7d8a0b31",
                            "name": "10% off with credit cards - Mother's Day",
                            "unit_amount": 25.0,
                            "quote_id": "qte_…",
                            "discount_indicator": null,
                            "discount_rate": null
                        },
                        {
                            "type": "MERCHANT",
                            "id": "LOYALTY-5",
                            "name": "Loyalty 5%",
                            "unit_amount": 12.5,
                            "discount_indicator": null,
                            "discount_rate": null
                        }
                    ]
                }
            },
            "transactions": {
                "type": "PURCHASE",
                "status": "SUCCEEDED",
                "amount": 225.0
            }
        }
    }
}
```

### Webhook de pago V1

Payload de ejemplo:

```json JSON theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
   "payment":{
      "code":"b3da6717-7949-454e-8699-e449bfaccb69",
      "id":"b3da6717-7949-454e-8699-e449bfaccb69",
      "idempotency_key":"28f14927-421b-4424-b4d2-5de4d83ca138",
      "organization_code":"9c99108c-7681-4d48-acca-bce037685e99",
      "account_code":"c004cfd7-0c65-4add-b9b3-3d7e3949c9f1",
      "account_id":"c004cfd7-0c65-4add-b9b3-3d7e3949c9f1",
      "description":"test description",
      "country":"CO",
      "status":"SUCCEEDED",
      "sub_status":"APPROVED",
      "order_id":"1679531154456",
      "merchant_order_id":"1679531154456",
      "created_at":"2023-03-23T00:26:38.093810Z",
      "updated_at":"2023-03-23T00:26:51.285333Z",
      "amount":{
         "currency":"COP",
         "value":2000.0,
         "refunded":0.0,
         "captured":0.0
      },
      "checkout":{
         "session":"fb98b19d-39c0-42d2-bed6-438605458964",
         "sdk_action_required":false
      },
      "customer_payer":{
         "code":"8122d1f5-c07d-4d88-9dfe-a09ccdaeda0b",
         "id":"8122d1f5-c07d-4d88-9dfe-a09ccdaeda0b",
         "organization_customer_external_id":"1679531154456",
         "merchant_customer_id":"1679531154456",
         "first_name":"Aaron",
         "last_name":"Hegmann",
         "gender":"F",
         "date_of_birth":"1990-02-28",
         "email":"andrea@y.uno",
         "nationality":"CO",
         "ip_address":"192.168.123.167",
         "device_fingerprint":"278994bb-9ece-5c63-8c44-c03481851625",
         "browser_info":null,
         "document":{
            "document_number":"1032765432",
            "document_type":"CC"
         },
         "billing_address":{
            "address_line_1":"Calle 34 # 56 - 78",
            "address_line_2":"Apartamento 502, Torre I",
            "city":"Bogotá",
            "country":"CO",
            "state":"Cundinamarca",
            "zip_code":"111111"
         },
         "shipping_address":{
            "address_line_1":"Calle 34 # 56 - 78",
            "address_line_2":"Apartamento 502, Torre I",
            "city":"Bogotá",
            "country":"CO",
            "state":"Cundinamarca",
            "zip_code":"111111"
         },
         "phone":{
            "country_code":"57",
            "number":"3991111111"
         }
      },
      "shipping":{
         "method":{
            "id":"express",
            "label":"Express shipping",
            "amount":{
               "currency":"GBP",
               "value":5.00
            }
         },
         "address":{
            "address_line_1":"221B Baker Street",
            "address_line_2":"Flat 2",
            "city":"London",
            "state":"England",
            "zip_code":"NW1 6XE",
            "country":"GB"
         }
      },
      "additional_data":{
         "order":{
            "shipping_amount":0.0,
            "fee_amount":0.0,
            "items":[
               {
                  "id":"123AD",
                  "name":"Skirt",
                  "quantity":1,
                  "unit_amount":2000.0,
                  "category":"Clothes",
                  "brand":"XYZ",
                  "sku_code":"8765432109",
                  "manufacture_part_number":"XYZ123456",
                  "image_url":null
               }
            ],
            "discounts":[]
         },
         "airline":null
      },
      "transactions":{
         "code":"98c80022-fe05-4b9b-b478-2e102fc72cc3",
         "id":"98c80022-fe05-4b9b-b478-2e102fc72cc3",
         "type":"PURCHASE",
         "status":"SUCCEEDED",
         "category":"CARD",
         "amount":2000.0,
         "provider_id":"KUSHKI",
         "response_code":"SUCCEEDED",
         "merchant_reference":null,
         "response_message":"Transaction successful",
         "reason":null,
         "description":"test description",
         "created_at":"2023-03-23T00:26:38.290239Z",
         "updated_at":"2023-03-23T00:26:51.258039Z",
         "payment_method":{
            "token":"e12440ca-920c-4aab-b656-6ed63f9ed5ac",
            "type":"CARD",
            "vaulted_token":null,
            "vault_on_success":false,
            "payment_method_detail":{
               "card":{
                  "verify":null,
                  "capture":false,
                  "installments":1,
                  "first_installment_deferral":null,
                  "installments_amount":null,
                  "installments_type":null,
                  "soft_descriptor":"",
                  "authorization_code":"",
                  "retrieval_reference_number":"",
                  "acquirer_reference_number":"",
                  "voucher":null,
                  "card_data":{
                     "holder_name":"APROBADO",
                     "iin":"54519515",
                     "lfd":"5480",
                     "number_length":16,
                     "security_code_length":3,
                     "brand":"MASTERCARD",
                     "issuer_name":"BANCO DE LA PRODUCCION S.A. (PRODUBANCO)",
                     "issuer_code":null,
                     "category":"BLACK",
                     "type":"CREDIT"
                  }
               },
               "wallet":null,
               "bnpl":null,
               "bank_transfer":null,
               "payment_link":null
            }
         },
         "provider":{
            "provider_transaction_id":"488990863216107201"
         },
         "provider_data":{
            "raw_response":{
               "details":{
                  "amount":{
                     "currency":"COP",
                     "ice":0,
                     "iva":0,
                     "subtotalIva":0,
                     "subtotalIva0":2000
                  },
                  "approvalCode":"000000",
                  "approvedTransactionAmount":2000,
                  "binInfo":{
                     "bank":"Banco de la Produccion S.A. (PRODUBANCO)",
                     "bindCard":"545195",
                     "cardCountry":"Ecuador",
                     "lastFourDigits":"5480",
                     "type":"credit"
                  },
                  "cardHolderName":"APROBADO",
                  "created":1679531210000,
                  "merchantId":"20000000107058310000",
                  "merchantName":"kushkiCOSBX Colombia",
                  "paymentBrand":"Mastercard",
                  "processorBankName":"0032~BANCO INTERNACIONAL",
                  "requestAmount":2000,
                  "responseCode":"000",
                  "responseText":"Transacción aprobada",
                  "transactionId":"091607275430589119",
                  "transactionReference":"eb6eb9e1-68d3-46be-8a0b-41ec8ff3ad73",
                  "transactionStatus":"APPROVAL",
                  "transactionType":"SALE"
               },
               "ticketNumber":"488990863216107201",
               "transactionReference":"eb6eb9e1-68d3-46be-8a0b-41ec8ff3ad73"
            },
            "id":"KUSHKI",
            "transaction_id":"488990863216107201",
            "account_id":null,
            "status":"APPROVAL",
            "status_detail":"Transacción aprobada",
            "response_message":"Transacción aprobada"
         },
         "connection_data":{
            "id":"88292fd3-bf5b-4b23-bb95-7186ba4e7f88",
            "name":"Kushki Colombia"
         }
      },
      "callback_url":null,
      "workflow":"CHECKOUT",
      "split":[ 
      ],
     "subscription_id":null,
     "payment_link_id":null
   }
}
```

### Webhook de contracargo V2

Payload de ejemplo:

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
   "type":"payment",
   "type_event":"payment.chargeback",
   "account_id":"a4441009-df56-4a59-a515-ca9b949c4ce3",
   "retry":0,
   "version":2,
   "data":{
      "payment":{
         "id":"ae70d7f9-e0a2-4e37-a12f-765e8af87924",
         "account_id":"a4441009-df56-4a59-a515-ca9b949c4ce3",
         "description":"test Ecommerce",
         "country":"MX",
         "status":"IN_DISPUTE",
         "sub_status":"RECEIVED",
         "order_id":"584-67f854a2eb05a22320e86071",
         "merchant_order_id":"584-67f854a2eb05a22320e86071",
         "created_at":"2025-04-10T23:30:53.210656Z",
         "updated_at":"2025-04-17T04:46:49.640765Z",
         "idempotency_key":"485d3965-6deb-4fc5-81de-4a7211c835bc",
         "amount":{
            "currency":"MXN",
            "value":418.0,
            "refunded":0.0,
            "captured":0.0,
            "currency_conversion": {
               "code": "ccv_01HVK3Z9M2...",
               "cardholder_currency": "QAR",
               "cardholder_amount": 3640.00,
               "cardholder_accepted": true,
               "rate": 3.6400,
               "rate_margin_percentage": 3.75,
               "rate_source": "ECB",
               "provider": "FEXCO",
               "description": "You have chosen to pay in QAR. Amount: 3640.00 QAR. Rate: 3.6400.",
               "created_at": "2026-04-24T14:30:00Z",
               "expires_at": "2026-04-24T15:30:00Z",
               "status": "APPLIED",
               "error_reason": null,
               "provider_data": {
                 "acquirer_id": "MPGS_01"
               }
            }
         },
         "checkout":{
            "session":"4f335b32-79de-41a7-b30b-f478620bc7a8",
            "sdk_action_required":false
         },
         "customer_payer":{
            "id":"4476c479-9a32-4910-83d8-b74b7b8eb86f",
            "merchant_customer_id":"67f854536e2a02461a1a8f5f",
            "first_name":"merit",
            "last_name":"amador",
            "gender":"",
            "date_of_birth":null,
            "email":"bolitas.nuca9b@icloud.com",
            "nationality":null,
            "ip_address":"200.68.159.190",
            "device_fingerprint":null,
            "third_party_session_id":null,
            "device_fingerprints":[
               
            ],
            "merchant_customer_created_at":"2025-04-10T23:23:46.357Z",
            "browser_info":{
               "user_agent":"Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Mobile/15E148 Safari/604.1",
               "accept_header":"*/*",
               "color_depth":"24",
               "screen_height":"852",
               "screen_width":"393",
               "javascript_enabled":true,
               "language":"es",
               "accept_content":"*/*",
               "accept_browser":"*/*",
               "java_enabled":false,
               "browser_time_difference":"360"
            },
            "document":null,
            "billing_address":{
               "address_line_1":"Av. test test No. 193 Local C-1-2-3 Plaza Galerias Col. test test C.P11300 test D.F",
               "address_line_2":"",
               "city":"test",
               "country":"MX",
               "state":"-",
               "zip_code":"-",
               "neighborhood":null
            },
            "shipping_address":{
               "address_line_1":"Av. test test No. 193 Local C-1-2-3 test test Col. test test C.P11300 test D.F",
               "address_line_2":"",
               "city":"CDMX",
               "country":"MX",
               "state":"-",
               "zip_code":"-",
               "neighborhood":null
            },
            "phone":{
               "country_code":"52",
               "number":"5659708369"
            }
         },
         "additional_data":{
            "order":{
               "shipping_amount":0.0,
               "fee_amount":0.0,
               "tip_amount":null,
               "items":[
                  {
                     "id":"26609",
                     "name":"McTrío Grande Signature BBQ Crispy Onion",
                     "quantity":2,
                     "unit_amount":193.0,
                     "category":"others",
                     "brand":null,
                     "sku_code":"26609",
                     "manufacture_part_number":null,
                     "image_url":null
                  }
               ],
               "taxes":[
                  
               ],
               "shipping":null,
               "account_funding":null,
               "tickets":[
                  
               ],
               "fulfillment":null,
               "discounts":[
                  
               ]
            },
            "airline":null,
            "seller_details":null
         },
         "transactions":{
            "id":"5f354190-ffe8-4b25-a73d-55fe25821067",
            "type":"CHARGEBACK",
            "status":"CREATED",
            "category":"CARD",
            "amount":418.0,
            "provider_id":"ADYEN",
            "response_code":"ACTION_REQUIRED",
            "merchant_reference":"YU00000058467f854a2eb05a22320e86071",
            "response_message":"Chargeback or Inquiry received. Decision or documentation must be provided",
            "reason":"REQUESTED_BY_CUSTOMER",
            "description":"webhook transaction",
            "created_at":"2025-04-17T04:46:49.591869Z",
            "updated_at":"2025-04-17T04:46:49.616143Z",
            "payment_method":{
               "token":"592c7a1c-e34c-4dc1-851f-5bd41bc32c68",
               "type":"CARD",
               "vaulted_token":"2146a9c4-56c9-43a5-a35b-916bf15f7772",
               "vault_on_success":false,
               "parent_payment_method_type":null,
               "payment_method_detail":{
                  "card":{
                     "verify":false,
                     "capture":false,
                     "installments":1,
                     "installments_plan_id":null,
                     "first_installment_deferral":null,
                     "installments_amount":null,
                     "installments_type":null,
                     "soft_descriptor":"",
                     "authorization_code":"373761",
                     "retrieval_reference_number":"",
                     "acquirer_reference_number":"",
                     "voucher":null,
                     "card_data":{
                        "holder_name":"YOANA CALAM",
                        "iin":"55123824",
                        "lfd":"2451",
                        "number_length":16,
                        "security_code_length":3,
                        "brand":"MASTERCARD",
                        "issuer_name":"BANCO AZTECA INSTITUCION BANCA MULTIPLE",
                        "issuer_code":null,
                        "country_code":"MX",
                        "category":"DEBIT MASTERCARD",
                        "type":"DEBIT",
                        "three_d_secure":{
                           "version":null,
                           "electronic_commerce_indicator":null,
                           "cryptogram":null,
                           "transaction_id":null,
                           "directory_server_transaction_id":null,
                           "pares_status":null,
                           "acs_id":null
                        },
                        "network_token":null,
                        "fingerprint":"355e7384-7e75-4a32-94b9-26031a4faab5",
                        "expiration_month":12,
                        "expiration_year":26
                     },
                     "stored_credentials":{
                        "reason":null,
                        "usage":null,
                        "subscription_agreement_id":null,
                        "network_transaction_id":null
                     }
                  },
                  "wallet":null,
                  "bnpl":null,
                  "bank_transfer":null,
                  "ticket":null,
                  "payment_link":null
               }
            },
            "provider":{
               "provider_transaction_id":"L2JC9B5K995BJDF6"
            },
            "provider_data":{
               "raw_response":null,
               "id":"ADYEN",
               "transaction_id":"L2JC9B5K995BJDF6",
               "account_id":null,
               "status":"NOTIFICATION_OF_CHARGEBACK",
               "status_detail":null,
               "response_message":null,
               "response_code":null,
               "third_party_transaction_id":null,
               "third_party_account_id":null,
               "iso8583_response_code":null,
               "iso8583_response_message":null
            },
            "connection_data":{
               "id":null,
               "name":null
            },
            "device_fingerprint":null,
            "simplified_mode":false,
            "third_party_session_id":null
         },
         "transactions_history":[
            {
               "id":"5f354190-ffe8-4b25-a73d-55fe25821067",
               "type":"CHARGEBACK",
               "status":"CREATED",
               "category":"CARD",
               "amount":418.0,
               "provider_id":"ADYEN",
               "response_code":"ACTION_REQUIRED",
               "merchant_reference":"YU00000058467f854a2eb05a22320e86071",
               "response_message":"Chargeback or Inquiry received. Decision or documentation must be provided",
               "reason":"REQUESTED_BY_CUSTOMER",
               "description":"webhook transaction",
               "created_at":"2025-04-17T04:46:49.591869Z",
               "updated_at":"2025-04-17T04:46:49.616143Z",
               "payment_method":{
                  "token":"592c7a1c-e34c-4dc1-851f-5bd41bc32c68",
                  "type":"CARD",
                  "vaulted_token":"2146a9c4-56c9-43a5-a35b-916bf15f7772",
                  "vault_on_success":false,
                  "parent_payment_method_type":null,
                  "payment_method_detail":{
                     "card":{
                        "verify":false,
                        "capture":false,
                        "installments":1,
                        "installments_plan_id":null,
                        "first_installment_deferral":null,
                        "installments_amount":null,
                        "installments_type":null,
                        "soft_descriptor":"",
                        "authorization_code":"373761",
                        "retrieval_reference_number":"",
                        "acquirer_reference_number":"",
                        "voucher":null,
                        "card_data":{
                           "holder_name":"YOANA CALAM",
                           "iin":"55123824",
                           "lfd":"2451",
                           "number_length":16,
                           "security_code_length":3,
                           "brand":"MASTERCARD",
                           "issuer_name":"BANCO AZTECA INSTITUCION BANCA MULTIPLE",
                           "issuer_code":null,
                           "country_code":"MX",
                           "category":"DEBIT MASTERCARD",
                           "type":"DEBIT",
                           "three_d_secure":{
                              "version":null,
                              "electronic_commerce_indicator":null,
                              "cryptogram":null,
                              "transaction_id":null,
                              "directory_server_transaction_id":null,
                              "pares_status":null,
                              "acs_id":null
                           },
                           "network_token":null,
                           "fingerprint":"355e7384-7e75-4a32-94b9-26031a4faab5",
                           "expiration_month":12,
                           "expiration_year":26
                        },
                        "stored_credentials":{
                           "reason":null,
                           "usage":null,
                           "subscription_agreement_id":null,
                           "network_transaction_id":null
                        }
                     },
                     "wallet":null,
                     "bnpl":null,
                     "bank_transfer":null,
                     "ticket":null,
                     "payment_link":null
                  }
               },
               "provider":{
                  "provider_transaction_id":"L2JC9B5K995BJDF6"
               },
               "provider_data":{
                  "raw_response":null,
                  "id":"ADYEN",
                  "transaction_id":"L2JC9B5K995BJDF6",
                  "account_id":null,
                  "status":"NOTIFICATION_OF_CHARGEBACK",
                  "status_detail":null,
                  "response_message":null,
                  "response_code":null,
                  "third_party_transaction_id":null,
                  "third_party_account_id":null,
                  "iso8583_response_code":null,
                  "iso8583_response_message":null
               },
               "connection_data":{
                  "id":null,
                  "name":null
               },
               "device_fingerprint":null,
               "simplified_mode":false,
               "third_party_session_id":null
            },
            {
               "id":"4d508842-5ffc-438a-a864-deeceb9935ca",
               "type":"PURCHASE",
               "status":"SUCCEEDED",
               "category":"CARD",
               "amount":418.0,
               "provider_id":"ADYEN",
               "response_code":"SUCCEEDED",
               "merchant_reference":"YU00000058467f854a2eb05a22320e86071",
               "response_message":"Transaction successful",
               "reason":null,
               "description":"McDonalds Ecommerce",
               "created_at":"2025-04-10T23:30:53.319251Z",
               "updated_at":"2025-04-10T23:30:54.496131Z",
               "payment_method":{
                  "token":"592c7a1c-e34c-4dc1-851f-5bd41bc32c68",
                  "type":"CARD",
                  "vaulted_token":"2146a9c4-56c9-43a5-a35b-916bf15f7772",
                  "vault_on_success":false,
                  "parent_payment_method_type":null,
                  "payment_method_detail":{
                     "card":{
                        "verify":false,
                        "capture":true,
                        "installments":1,
                        "installments_plan_id":null,
                        "first_installment_deferral":null,
                        "installments_amount":null,
                        "installments_type":null,
                        "soft_descriptor":"",
                        "authorization_code":"373761",
                        "retrieval_reference_number":"",
                        "acquirer_reference_number":"",
                        "voucher":null,
                        "card_data":{
                           "holder_name":"YOANA CALAM",
                           "iin":"55123824",
                           "lfd":"2451",
                           "number_length":16,
                           "security_code_length":3,
                           "brand":"MASTERCARD",
                           "issuer_name":"BANCO AZTECA INSTITUCION BANCA MULTIPLE",
                           "issuer_code":null,
                           "country_code":"MX",
                           "category":"DEBIT MASTERCARD",
                           "type":"DEBIT",
                           "three_d_secure":{
                              "version":null,
                              "electronic_commerce_indicator":null,
                              "cryptogram":null,
                              "transaction_id":null,
                              "directory_server_transaction_id":null,
                              "pares_status":null,
                              "acs_id":null
                           },
                           "network_token":null,
                           "fingerprint":"355e7384-7e75-4a32-94b9-26031a4faab5",
                           "expiration_month":12,
                           "expiration_year":26
                        },
                        "stored_credentials":{
                           "reason":null,
                           "usage":null,
                           "subscription_agreement_id":null,
                           "network_transaction_id":null
                        }
                     },
                     "wallet":null,
                     "bnpl":null,
                     "bank_transfer":null,
                     "ticket":null,
                     "payment_link":null
                  }
               },
               "provider":{
                  "provider_transaction_id":"L2JC9B5K995BJDF6"
               },
               "provider_data":{
                  "raw_response":{
                     "additionalData":{
                        "acquirerAccountCode":"AdyenProsa_ArcosDouradosPlataforma-MX_Cvv",
                        "acquirerCode":"AdyenProsa",
                        "acquirerReference":"373761",
                        "authCode":"373761",
                        "authorisationMid":"9024452",
                        "avsResult":"0 Unknown",
                        "cardFunction":"Consumer",
                        "cavv":"N/A",
                        "cavvAlgorithm":"N/A",
                        "cvcResult":"1 Matches",
                        "cvcResultRaw":"1 Matches",
                        "eci":"N/A",
                        "liabilityShift":"false",
                        "paymentMethod":"mc",
                        "paymentMethodVariant":"mcstandarddebit",
                        "refusalReasonRaw":"00 : Approved or completed successfully",
                        "threeDAuthenticated":"false",
                        "threeDAuthenticatedResponse":"N/A",
                        "threeDOffered":"false",
                        "threeDOfferedResponse":"N/A",
                        "threeds2.cardEnrolled":"true",
                        "xid":"N/A"
                     },
                     "amount":{
                        "currency":"MXN",
                        "value":41800
                     },
                     "merchantReference":"584-67f854a2eb05a22320e86071",
                     "paymentMethod":{
                        "brand":"mc",
                        "type":"scheme"
                     },
                     "pspReference":"L2JC9B5K995BJDF6",
                     "resultCode":"Authorised"
                  },
                  "id":"ADYEN",
                  "transaction_id":"L2JC9B5K995BJDF6",
                  "account_id":"test-account",
                  "status":"Authorised",
                  "status_detail":"Authorised",
                  "response_message":null,
                  "response_code":null,
                  "third_party_transaction_id":"L2JC9B5K995BJDF6",
                  "third_party_account_id":"",
                  "iso8583_response_code":"00 ",
                  "iso8583_response_message":null
               },
               "connection_data":{
                  "id":"72f2adb3-ed95-4bca-be01-20bbe4d5a1cb",
                  "name":null
               },
               "device_fingerprint":null,
               "simplified_mode":false,
               "third_party_session_id":null
            }
         ],
         "callback_url":"https://test.com.mx/api/callback/my-orders?path=%2Fmi-cuenta%2Fmis-pedidos%2F67f854a2eb05a22320e86071&checkoutSession=5f446b32-79de-41a7-b30b-f478620bc7a8",
         "workflow":"SDK_CHECKOUT",
         "split_marketplace":[
            
         ],
         "payment_link_code":"",
         "subscription_id":null,
         "fraud_screening":null,
         "metadata":[
            {
               "key":"riskdata.deliveryMethod",
               "value":"MOP"
            },
            {
               "key":"riskdata.storeId",
               "value":"584"
            },
            {
               "key":"riskdata.basket.item1.amountPerItem",
               "value":"41800"
            },
            {
               "key":"riskdata.basket.item1.itemID",
               "value":"26609"
            },
            {
               "key":"riskdata.basket.item1.category",
               "value":"test value"
            },
            {
               "key":"riskdata.basket.item1.currency",
               "value":"MXN"
            },
            {
               "key":"riskdata.basket.item1.quantity",
               "value":"2"
            },
            {
               "key":"riskdata.basket.item1.productTitle",
               "value":"test value"
            }
         ],
         "routing_rules":{
            "smart_routing":false,
            "monitors":false,
            "condition":{
               "id":537769,
               "name":null,
               "description":null
            }
         }
      }
   }
}
```

### Webhook de contracargo V1

Payload de ejemplo:

```json JSON theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
   "payment":{
      "code":"b3da6717-7949-454e-8699-e449bfaccb69",
      "id":"b3da6717-7949-454e-8699-e449bfaccb69",
      "idempotency_key":"28f14927-421b-4424-b4d2-5de4d83ca138",
      "organization_code":"9c99108c-7681-4d48-acca-bce037685e99",
      "account_code":"c004cfd7-0c65-4add-b9b3-3d7e3949c9f1",
      "account_id":"c004cfd7-0c65-4add-b9b3-3d7e3949c9f1",
      "description":"test description",
      "country":"CO",
      "status":"CHARGEBACK",
      "sub_status":"LOST",
      "order_id":"1679531154456",
      "merchant_order_id":"1679531154456",
      "created_at":"2023-03-23T00:26:38.093810Z",
      "updated_at":"2023-03-23T00:26:51.285333Z",
      "amount":{
         "currency":"COP",
         "value":2000.0,
         "refunded":0.0,
         "captured":0.0
      },
      "checkout":{
         "session":"fb98b19d-39c0-42d2-bed6-438605458964",
         "sdk_action_required":false
      },
      "customer_payer":{
         "code":"8122d1f5-c07d-4d88-9dfe-a09ccdaeda0b",
         "id":"8122d1f5-c07d-4d88-9dfe-a09ccdaeda0b",
         "organization_customer_external_id":"1679531154456",
         "merchant_customer_id":"1679531154456",
         "first_name":"Aaron",
         "last_name":"Hegmann",
         "gender":"F",
         "date_of_birth":"1990-02-28",
         "email":"andrea@y.uno",
         "nationality":"CO",
         "ip_address":"192.168.123.167",
         "device_fingerprint":"278994bb-9ece-5c63-8c44-c03481851625",
         "browser_info":null,
         "document":{
            "document_number":"1032765432",
            "document_type":"CC"
         },
         "billing_address":{
            "address_line_1":"Calle 34 # 56 - 78",
            "address_line_2":"Apartamento 502, Torre I",
            "city":"Bogotá",
            "country":"CO",
            "state":"Cundinamarca",
            "zip_code":"111111"
         },
         "shipping_address":{
            "address_line_1":"Calle 34 # 56 - 78",
            "address_line_2":"Apartamento 502, Torre I",
            "city":"Bogotá",
            "country":"CO",
            "state":"Cundinamarca",
            "zip_code":"111111"
         },
         "phone":{
            "country_code":"57",
            "number":"3991111111"
         }
      },
      "additional_data":{
         "order":{
            "shipping_amount":0.0,
            "fee_amount":0.0,
            "items":[
               {
                  "id":"123AD",
                  "name":"Skirt",
                  "quantity":1,
                  "unit_amount":2000.0,
                  "category":"Clothes",
                  "brand":"XYZ",
                  "sku_code":"8765432109",
                  "manufacture_part_number":"XYZ123456",
                  "image_url":null
               }
            ]
         },
         "airline":null
      },
      "transactions":{
         "code":"98c80022-fe05-4b9b-b478-2e102fc72cc3",
         "id":"98c80022-fe05-4b9b-b478-2e102fc72cc3",
         "type":"CHARGEBACK",
         "status":"LOST",
         "category":"CARD",
         "amount":2000.0,
         "provider_id":"KUSHKI",
         "response_code":"CHARGEBACK",
         "merchant_reference":null,
         "response_message":"Transaction successful",
         "reason":null,
         "description":"test description",
         "created_at":"2023-03-23T00:26:38.290239Z",
         "updated_at":"2023-03-23T00:26:51.258039Z",
         "payment_method":{
            "token":"e12440ca-920c-4aab-b656-6ed63f9ed5ac",
            "type":"CARD",
            "vaulted_token":null,
            "vault_on_success":false,
            "payment_method_detail":{
               "card":{
                  "verify":null,
                  "capture":false,
                  "installments":1,
                  "first_installment_deferral":null,
                  "installments_amount":null,
                  "installments_type":null,
                  "soft_descriptor":"",
                  "authorization_code":"",
                  "retrieval_reference_number":"",
                  "acquirer_reference_number":"",
                  "voucher":null,
                  "card_data":{
                     "holder_name":"APROBADO",
                     "iin":"54519515",
                     "lfd":"5480",
                     "number_length":16,
                     "security_code_length":3,
                     "brand":"MASTERCARD",
                     "issuer_name":"BANCO DE LA PRODUCCION S.A. (PRODUBANCO)",
                     "issuer_code":null,
                     "category":"BLACK",
                     "type":"CREDIT"
                  }
               },
               "wallet":null,
               "bnpl":null,
               "bank_transfer":null,
               "payment_link":null
            }
         },
         "provider":{
            "provider_transaction_id":"488990863216107201"
         },
         "provider_data":{
            "raw_response":{
               },
            "id":"KUSHKI",
            "transaction_id":"488990863216107201",
            "account_id":null,
            "status":"CHARGEBACK",
            "status_detail":"",
            "response_message":""
         }
      },
      "callback_url":null,
      "workflow":"SDK_CHECKOUT",
      "split":[
         
      ]
   }
}
```

### payment.pre\_chargeback

Se envía cuando se recibe un aviso de precontracargo o una alerta de fraude para un pago, antes de un contracargo completo. Actualmente se envía a cualquier webhook con al menos un valor en `payment_triggers`, sin importar si `PRECHARGEBACK` está seleccionado; se planea un trigger dedicado para una versión futura.

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "payment",
  "type_event": "payment.pre_chargeback",
  "account_id": "2c05976d-1234-1234-1234-6421883de48d",
  "retry": 0,
  "version": 2,
  "data": {
    "payment": {
      "id": "8f3a1b6c-4d2e-4f8a-9b1c-7e5d3a2f6b04",
      "account_id": "2c05976d-1234-1234-1234-6421883de48d",
      "description": "Order 12578185913914",
      "country": "BR",
      "status": "SUCCEEDED",
      "sub_status": "APPROVED",
      "order_id": "ORDER-12578185913914",
      "merchant_order_id": "ORDER-12578185913914",
      "created_at": "2026-07-11T05:04:49.855791Z",
      "updated_at": "2026-08-17T16:32:03.145543Z",
      "idempotency_key": "4a6f2d18-9b73-4c51-a2e9-6d3b8f1c07a4",
      "amount": {
        "currency": "BRL",
        "value": 24.9,
        "refunded": 0.0,
        "captured": 0.0,
        "currency_conversion": null
      },
      "workflow": "DIRECT",
      "fraud_screening": null,
      "transactions": {
        "id": "3d5e8c92-1f47-4a63-b8d0-5c2a9e7f14b6",
        "type": "PRE_CHARGEBACK",
        "status": "CREATED",
        "category": "CARD",
        "amount": 24.9,
        "provider_id": "ADYEN",
        "response_code": "ACTION_REQUIRED",
        "merchant_reference": "ORDER-12578185913914",
        "response_message": "Chargeback or Inquiry received. Decision or documentation must be provided",
        "reason": "FRAUDULENT",
        "description": "webhook transaction",
        "created_at": "2026-08-17T16:32:03.075632Z",
        "updated_at": "2026-08-17T16:32:03.103778Z",
        "provider": { "provider_transaction_id": "PROVIDER_CASE_ID" },
        "provider_data": {
          "id": "ADYEN",
          "transaction_id": "PROVIDER_CASE_ID",
          "account_id": "merchant_account_name",
          "status": "NOTIFICATION_OF_FRAUD",
          "raw_response": null,
          "status_detail": null,
          "response_message": null,
          "response_code": null,
          "reason_code": null,
          "reason_description": null
        },
        "connection_data": { "id": "6c4b2f79-8e13-4d5a-9f27-0a3e6b8d51c9", "name": "connection_name" }
      }
    }
  }
}
```

## Inscripción

El siguiente objeto JSON presenta un ejemplo de una estructura de datos relacionada con un evento de inscripción.

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "enrollment",
  "type_event": "enrollment.enroll",
  "account_id": "493e9374-510a-4201-9e09-de669d75f256",
  "retry": 0,
  "version": 2,
  "data": {
    "payment_method": {
      "id": "03c3aae1-ed42-4be6-bc24-de5487f58491",
      "account_id": "493e9374-510a-4201-9e09-de669d75f256",
      "name": "VISA ****1111",
      "description": "VISA ****1111",
      "type": "CARD",
      "category": "CARD",
      "country": "CO",
      "status": "ENROLLED",
      "customer_id": "2f38972e-2427-43b7-95be-ee4cf21cef1b",
      "created_at": "2024-09-10T15:04:10.453741Z",
      "updated_at": "2024-09-10T15:04:10.453745Z",
      "enrollment": {
        "session": null,
        "sdk_action_required": false
      },
      "verify": {
        "vault_on_success": false,
        "currency": null,
        "payment": null
      },
      "metadata": [
        {
          "key": "on_behalf_of",
          "value": "acct_1A2b3C4d5E6f7G8h"
        },
        {
          "key": "order_ref",
          "value": "ABC-123"
        }
      ],
      "detail": {
        "card": {
          "holder_name": "Pepito Perez",
          "expiration_month": 3,
          "expiration_year": 26,
          "iin": "41111111",
          "lfd": "1111",
          "security_code_length": 3,
          "number_length": 16,
          "brand": "VISA",
          "issuer_name": "JPMORGAN CHASE BANK N A",
          "issuer_code": null,
          "type": "CREDIT",
          "category": "CREDIT",
          "country_code": "US",
          "country_name": "United States of America",
          "fingerprint_code": "d244e20d-43a1-43f7-9b48-0a76423be35e",
          "created_at": "2024-09-10T15:04:10.453799Z",
          "updated_at": "2024-09-10T15:04:10.453800Z"
        }
      }
    }
  }
}

```

> [!NOTE]
>
> Cuando una inscripción se crea con `verify.external_subscription` (consulta [Enroll payment method](https://docs.y.uno/reference/payment-methods-direct-workflow/enroll-payment-method-api.md)), el objeto se devuelve en la **respuesta de la inscripción** y se conserva en el **pago de verificación**; no forma parte del payload del webhook de inscripción. Para correlacionarlo después, usa el pago de verificación: su id viene en la respuesta de la inscripción (`verify.payment.id`) y el objeto se devuelve en [Retrieve payment](https://docs.y.uno/reference/payments/retrieve-payment-by-id) y en los webhooks de pago.

## Payouts

El siguiente objeto JSON presenta un ejemplo de una estructura de datos relacionada con un evento de payout.

```json JSON theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "payout",
  "type_event": "payout.payout",
  "account_id": "f7c5fe77-721b-49c2-84d3-957748df3c2c",
  "retry": 0,
  "version": 2,
  "data": {
    "id": "0cbc7bd4-04f3-4897-b3c6-4d5f36a6b9a7",
    "status": "SUCCEEDED",
    "merchant_reference": "MR-12345",
    "description": null,
    "country": "BR",
    "account_code": "f7c5fe77-721b-49c2-84d3-957748df3c2c",
    "organization_code": "6c6a6b2c-c9c0-4104-9dd0-4237e6f00047",
    "purpose": null,
    "amount": {
      "currency": "BRL",
      "value": 100
    },
    "beneficiary": {
      "merchant_beneficiary_id": "test_merchant_deposit_id",
      "national_entity": null,
      "first_name": null,
      "last_name": null,
      "legal_name": null,
      "email": null,
      "country": "BR",
      "date_of_birth": null,
      "document": null,
      "phone": null,
      "address": null
    },
    "transactions": [
      {
        "id": "2be03290-70a9-414a-a285-8c573d26de5a",
        "status": "SUCCEEDED",
        "type": "ASTROPAY_PAYOUT",
        "response_code": "SUCCEEDED",
        "purpose": null,
        "description": null,
        "amount": {
          "currency": "BRL",
          "value": 100
        },
        "withdrawal_method": {
          "type": "ASTROPAY_PAYOUT",
          "provider_id": null,
          "detail": {
            "bank_transfer": null,
            "wallet": {
              "code": "h15sg84U6rCl",
              "email": null,
              "country": null,
              "document": null,
              "phone": null
            }
          }
        },
        "provider_data": {
          "id": "ASTROPAY",
          "transaction_id": "32389",
          "account_id": "",
          "beneficiary_id": "test_merchant_deposit_id",
          "raw_response": "\"{\\n  \\\"cashout_id\\\" : 32389,\\n  \\\"merchant_cashout_id\\\" : \\\"2be03290-70a9-414a-a285-8c573d26de5a\\\",\\n  \\\"status\\\" : \\\"APPROVED\\\",\\n  \\\"user_id\\\" : \\\"h15sg84U6rCl\\\"\\n}\"",
          "status_detail": "APPROVED",
          "provider_status": null
        },
        "created_at": "2024-05-27T19:10:32.723578Z",
        "updated_at": "2024-05-27T19:10:33.757137Z"
      }
    ],
    "metadata": [],
    "created_at": "2024-05-27T19:10:32.494514Z",
    "updated_at": "2024-05-27T19:10:33.757143Z"
  }
}
```

## Reportes

`report_triggers` suscribe a los eventos del ciclo de vida de los reportes. Actualmente solo `report.update` es emitido por algún servicio; `report.create` se puede suscribir, pero aún no tiene emisor.

```json JSON theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "report",
  "type_event": "report.update",
  "account_id": "2c05976d-1234-1234-1234-6421883de48d",
  "retry": 0,
  "version": 2,
  "data": {
    "report_id": "7b1c9d3e-5a24-4f68-9c02-3e8d1f6a4b57",
    "organization_code": "9f2e1a44-3c7b-4d15-8e60-1b4a7c9d2f88",
    "account_code": "2c05976d-1234-1234-1234-6421883de48d",
    "type": "TRANSACTIONS",
    "s3_link": "reports/ON_DEMAND/TRANSACTIONS/date=2026-08-17/organization_code=9f2e1a44-3c7b-4d15-8e60-1b4a7c9d2f88/report=7b1c9d3e-5a24-4f68-9c02-3e8d1f6a4b57/7b1c9d3e-5a24-4f68-9c02-3e8d1f6a4b57.csv",
    "merchant_reference_id": "",
    "start_date": "2026-08-01T03:00:00Z",
    "end_date": "2026-08-17T07:30:00Z",
    "created_at": "2026-08-17T07:33:04.372231Z",
    "updated_at": "2026-08-17T07:35:18.49869Z",
    "status": "SUCCEEDED",
    "user_code": ""
  }
}
```

## Suscripciones

El siguiente objeto JSON presenta un ejemplo de una estructura de datos relacionada con un evento `subscription.create`.

```json JSON theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "subscription",
  "type_event": "subscription.create",
  "account_id": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
  "retry": 0,
  "version": 2,
  "data": {
    "subscription": {
      "code": "8fc8a985-bc18-4f9a-9403-d0cf6fc64e94",
      "name": "Subscription",
      "description": "retries activos",
      "country": "CO",
      "account_code": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
      "merchant_reference": "subscription-ref-merchant-002",
      "status": "CREATED",
      "amount": {
        "currency": "COP",
        "value": 36000
      },
      "frequency": null,
      "billing_date": {
        "type": "DAY",
        "day": 30
      },
      "billing_cycles": {
        "total": 5,
        "current": 1,
        "next_at": "2026-02-28T18:25:49.995376Z"
      },
      "current_period_start": "2026-01-28T18:25:49.995376Z",
      "current_period_end": "2026-02-28T18:25:49.995376Z",
      "current_phase_end": null,
      "customer_payer": {
        "code": "a9f9140a-1216-481c-8356-1a125078f905"
      },
      "payment_method": {
        "type": "CARD",
        "vaulted_token": "7eeb8d32-d5c3-45a8-955b-30accc625d1f"
      },
      "availability": {
        "start_at": "2026-02-01T18:25:49.995376Z",
        "finish_at": null
      },
      "retries": {
        "retry_on_decline": false,
        "amount": 6
      },
      "metadata": [
        {
          "key": "Canal 1",
          "value": "Soccer"
        }
      ],
      "additional_data": null,
      "payments": [],
      "trial_period": {
        "billing_cycles": 1,
        "amount": {
          "currency": null,
          "value": null
        }
      },
      "initial_payment_validation": true,
      "subscription_agreement_id": null,
      "created_at": "2025-05-21T15:33:16.662026Z",
      "updated_at": "2025-05-21T15:33:16.662026Z"
    }
  }
}
```

### subscription.active

Se envía cuando una suscripción pasa de cualquier otro estado válido a `ACTIVE`. Usa este evento para activar procesos posteriores a la activación sin necesidad de sondeo.

```json JSON theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "subscription",
  "type_event": "subscription.active",
  "account_id": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
  "retry": 0,
  "version": 2,
  "data": {
    "subscription": {
      "code": "e98ef674-9baa-4f7a-8da4-4c812c4749a4",
      "name": "Subscription",
      "description": "retries activos",
      "country": "CO",
      "account_code": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
      "merchant_reference": "subscription-ref-merchant-002",
      "status": "ACTIVE",
      "amount": {
        "currency": "COP",
        "type": "FIXED",
        "value": 36000
      },
      "frequency": {
        "type": "MINUTES",
        "value": 3,
        "monthly_billing_day": null,
        "execution": "YUNO"
      },
      "billing_date": null,
      "billing_cycles": {
        "total": 5,
        "current": 2,
        "next_at": "2025-12-04T00:32:25.485281Z"
      },
      "current_period_start": "2025-12-04T00:29:25.485281Z",
      "current_period_end": "2025-12-04T00:32:25.485281Z",
      "current_phase_end": null,
      "customer_payer": {
        "code": "a9f9140a-1216-481c-8356-1a125078f905"
      },
      "payment_method": {
        "type": "CARD",
        "vaulted_token": "7eeb8d32-d5c3-45a8-955b-30accc625d1f",
        "card": {
          "installments": null,
          "network_transaction_id": "651161211088410"
        }
      },
      "availability": {
        "start_at": "2025-12-04T00:29:25.485281Z",
        "finish_at": null
      },
      "retries": {
        "retry_on_decline": true,
        "amount": 6
      },
      "metadata": [
        {
          "key": "Canal 1",
          "value": "Soccer"
        }
      ],
      "additional_data": null,
      "payments": [],
      "trial_period": {
        "billing_cycles": 1,
        "amount": {
          "currency": null,
          "value": null
        }
      },
      "initial_payment_validation": true,
      "provider_subscription_id": null,
      "subscription_agreement_id": null,
      "created_at": "2025-12-04T00:29:25.485281Z",
      "updated_at": "2025-12-04T00:29:59.216998Z"
    }
  }
}
```

### subscription.trialing

Se envía cuando una suscripción entra en la fase de prueba de un plan desde otro estado. Entrar en la prueba al momento de la creación se informa como `subscription.create`, y salir de una pausa hacia la prueba, como `subscription.resume`.

```json JSON theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "subscription",
  "type_event": "subscription.trialing",
  "account_id": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
  "retry": 0,
  "version": 2,
  "data": {
    "subscription": {
      "code": "e98ef674-9baa-4f7a-8da4-4c812c4749a4",
      "name": "Subscription",
      "country": "CO",
      "account_code": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
      "merchant_reference": "subscription-ref-merchant-002",
      "status": "TRIALING",
      "plan_id": "0b0a2f7a-3d19-4a52-8f0e-3f1a3d5a3f21",
      "current_phase": "TRIAL",
      "amount": {
        "currency": "COP",
        "type": "FIXED",
        "value": 36000
      },
      "billing_cycles": {
        "total": 5,
        "current": 2,
        "next_at": "2025-12-04T00:32:25.485281Z"
      },
      "current_period_start": "2025-12-04T00:29:25.485281Z",
      "current_period_end": "2025-12-04T00:32:25.485281Z",
      "current_phase_end": "2025-12-04T00:32:25.485281Z",
      "customer_payer": {
        "code": "a9f9140a-1216-481c-8356-1a125078f905"
      },
      "payments": [],
      "created_at": "2025-12-04T00:29:25.485281Z",
      "updated_at": "2025-12-04T00:29:59.216998Z"
    }
  }
}
```

### subscription.past\_due

Se envía cuando un cobro recurrente falla y la suscripción pasa a `PAST_DUE`. La suscripción sigue facturando mientras se ejecutan los reintentos y aún se puede cancelar. Cuando un cobro posterior es exitoso, vuelve a `ACTIVE` (o a `TRIALING` si la fase de prueba sigue en curso) y se envía el evento correspondiente, `subscription.active` o `subscription.trialing`.

Este evento solo se emite para las cuentas que tienen habilitado el estado `PAST_DUE`. Donde no lo está, un cobro fallido deja la suscripción en `ACTIVE` y solo el webhook `payment.purchase` informa el rechazo. Consulta [Subscription Status](https://docs.y.uno/reference/subscriptions/status-subscriptions.md).

```json JSON theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "subscription",
  "type_event": "subscription.past_due",
  "account_id": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
  "retry": 0,
  "version": 2,
  "data": {
    "subscription": {
      "code": "e98ef674-9baa-4f7a-8da4-4c812c4749a4",
      "name": "Subscription",
      "country": "CO",
      "account_code": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
      "merchant_reference": "subscription-ref-merchant-002",
      "status": "PAST_DUE",
      "amount": {
        "currency": "COP",
        "type": "FIXED",
        "value": 36000
      },
      "billing_cycles": {
        "total": 5,
        "current": 3,
        "next_at": "2025-12-04T00:35:25.485281Z"
      },
      "current_period_start": "2025-12-04T00:32:25.485281Z",
      "current_period_end": "2025-12-04T00:35:25.485281Z",
      "current_phase_end": null,
      "customer_payer": {
        "code": "a9f9140a-1216-481c-8356-1a125078f905"
      },
      "retries": {
        "retry_on_decline": true,
        "amount": 6
      },
      "payments": [],
      "created_at": "2025-12-04T00:29:25.485281Z",
      "updated_at": "2025-12-04T00:35:25.485281Z"
    }
  }
}
```

### subscription.pause

Se envía cuando una suscripción se pausa. Usa este evento para actualizar el estado en tu sistema y pausar los servicios relacionados.

> [!NOTE]
>
> **La ventana de una suscripción pausada queda congelada donde estaba, no se mueve hacia adelante.** `current_period_start`/`current_period_end` (y `current_phase_end`, si la suscripción está dentro de una fase) conservan la ventana que estaba vigente en el momento de la pausa: Yuno no los avanza mientras la facturación está suspendida. Cuanto más tiempo permanece pausada una suscripción, más se aleja `current_period_end` en el pasado; en producción, la gran mayoría de las suscripciones actualmente pausadas ya muestran una ventana vencida. No trates `current_period_end` como "la próxima fecha de cobro" sin revisar también `status`: para una suscripción pausada, no lo es.

```json JSON theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "subscription",
  "type_event": "subscription.pause",
  "account_id": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
  "retry": 0,
  "version": 2,
  "data": {
    "subscription": {
      "code": "e98ef674-9baa-4f7a-8da4-4c812c4749a4",
      "name": "Subscription",
      "status": "PAUSED",
      "amount": {
        "currency": "COP",
        "type": "FIXED",
        "value": 36000
      },
      "billing_cycles": {
        "total": 5,
        "current": 3,
        "next_at": "2025-12-04T00:35:25.485281Z"
      },
      "current_period_start": "2025-12-04T00:32:25.485281Z",
      "current_period_end": "2025-12-04T00:35:25.485281Z",
      "current_phase_end": null,
      "customer_payer": {
        "code": "a9f9140a-1216-481c-8356-1a125078f905"
      }
    }
  }
}
```

### subscription.resume

Se envía cuando una suscripción pausada se reanuda y vuelve al estado con el que facturaba: `ACTIVE`, o `TRIALING` si todavía está dentro de una fase de prueba.

El payload incluye `resume_reason`, presente solo en este evento: `MERCHANT` cuando se llamó a [Resume Subscription](https://docs.y.uno/reference/subscriptions/resume-subscription.md), `SCHEDULED` cuando la pausa llegó a su `pause_until` y la suscripción volvió por sí sola. El evento también incluye el `billing_cycles.next_at` resultante.

Los payloads de suscripción incluyen `refund_rule` y `pause_until` siempre que el objeto de suscripción los incluya. Consulta [the Subscription object](https://docs.y.uno/reference/subscriptions/the-subscription-object.md).

```json JSON theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "subscription",
  "type_event": "subscription.resume",
  "account_id": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
  "retry": 0,
  "version": 2,
  "data": {
    "subscription": {
      "code": "e98ef674-9baa-4f7a-8da4-4c812c4749a4",
      "name": "Monthly Plan",
      "description": "Monthly subscription",
      "country": "US",
      "account_code": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
      "merchant_reference": "subscription-ref-merchant-002",
      "status": "ACTIVE",
      "amount": {
        "currency": "USD",
        "type": "FIXED",
        "value": 42.46
      },
      "frequency": {
        "type": "MONTH",
        "value": 1,
        "monthly_billing_day": null,
        "execution": "YUNO"
      },
      "billing_date": null,
      "billing_cycles": {
        "total": null,
        "current": 2,
        "next_at": "2026-07-14T19:19:31.914Z"
      },
      "current_period_start": "2026-06-14T19:19:31.914Z",
      "current_period_end": "2026-07-14T19:19:31.914Z",
      "current_phase_end": null,
      "customer_payer": {
        "code": "a9f9140a-1216-481c-8356-1a125078f905"
      },
      "payment_method": {
        "type": "CARD",
        "vaulted_token": "4ba74a56-14d4-4161-a0ba-8036e9b8abf6",
        "card": {
          "installments": null,
          "network_transaction_id": "000000000000000",
          "usage": "USED"
        }
      },
      "availability": {
        "start_at": "2026-06-14T19:19:31.914Z",
        "finish_at": null
      },
      "retries": {
        "retry_on_decline": true,
        "amount": 4,
        "strategy": "DEFAULT",
        "schedule": null,
        "stop_on_hard_decline": null,
        "cancel_on_exhausted_retries": null
      },
      "metadata": [
        {
          "key": "plan_id",
          "value": "monthly_plan"
        }
      ],
      "additional_data": null,
      "payments": [],
      "trial_period": {
        "billing_cycles": 1,
        "amount": {
          "currency": null,
          "value": null
        }
      },
      "initial_payment_validation": false,
      "provider_subscription_id": null,
      "reason": null,
      "resume_reason": "MERCHANT",
      "subscription_agreement_id": null,
      "soft_descriptor": null,
      "renewal_notification_days": null,
      "cancellation_time": null,
      "cancellation_source": null,
      "ending_time": null,
      "created_at": "2026-05-14T19:19:32.117629Z",
      "updated_at": "2026-06-15T07:11:52.504031Z",
      "history": null
    }
  }
}
```

Una reanudación programada (la pausa que llega a su `pause_until` por sí sola) envía el mismo evento con `"resume_reason": "SCHEDULED"` en su lugar, sin ninguna otra diferencia estructural en el payload (la variante `SCHEDULED` se describe a partir de la definición del evento del servicio, no de una entrega capturada).

### subscription.reactivate

Se envía cuando una suscripción `CANCELED` o `COMPLETED` vuelve a `ACTIVE` (o a `TRIALING` cuando una fase de prueba cubre el ciclo reactivado) mediante [Reactivate Subscription](https://docs.y.uno/reference/subscriptions/reactivate-subscription.md). El payload es el objeto de suscripción.

```json JSON theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "subscription",
  "type_event": "subscription.reactivate",
  "account_id": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
  "retry": 0,
  "version": 2,
  "data": {
    "subscription": {
      "code": "e98ef674-9baa-4f7a-8da4-4c812c4749a4",
      "name": "SUB-111 win-back subject",
      "description": null,
      "country": "CO",
      "account_code": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
      "merchant_reference": "sub111a-1789487996637-802344",
      "status": "ACTIVE",
      "amount": {
        "currency": "COP",
        "type": "FIXED",
        "value": 45000
      },
      "frequency": {
        "type": "MONTH",
        "value": 1,
        "monthly_billing_day": null,
        "execution": "YUNO"
      },
      "billing_date": null,
      "billing_cycles": {
        "total": 12,
        "current": 2,
        "next_at": "2026-10-15T15:59:57.366916Z"
      },
      "current_period_start": "2026-09-15T15:59:57.366916Z",
      "current_period_end": "2026-10-15T15:59:57.366916Z",
      "current_phase_end": null,
      "customer_payer": {
        "code": "a9f9140a-1216-481c-8356-1a125078f905"
      },
      "payment_method": {
        "type": "CARD",
        "vaulted_token": "96a73f83-8039-455c-97c6-7757d036450a",
        "card": {
          "installments": null,
          "network_transaction_id": null,
          "usage": "USED"
        }
      },
      "availability": {
        "start_at": "2026-09-15T15:59:57.366916Z",
        "finish_at": null
      },
      "retries": {
        "retry_on_decline": false,
        "amount": 6,
        "strategy": "DEFAULT",
        "schedule": null,
        "stop_on_hard_decline": null,
        "cancel_on_exhausted_retries": null
      },
      "metadata": null,
      "additional_data": null,
      "payments": [],
      "trial_period": {
        "billing_cycles": 1,
        "amount": {
          "currency": null,
          "value": null
        }
      },
      "initial_payment_validation": false,
      "provider_subscription_id": null,
      "reason": null,
      "subscription_agreement_id": null,
      "soft_descriptor": null,
      "renewal_notification_days": null,
      "cancellation_time": null,
      "cancellation_source": null,
      "ending_time": null,
      "created_at": "2026-09-15T15:59:57.366916Z",
      "updated_at": "2026-09-15T15:59:58.65775Z",
      "history": null
    }
  }
}
```

### subscription.auto\_resume\_failed

Se envía cuando la reanudación automática de una suscripción pausada no pudo completarse después de sus reintentos; la suscripción permanece `PAUSED`. El payload es el objeto de suscripción. Disponible para las organizaciones habilitadas; contacta a Yuno.

> [!NOTE]
>
> Todavía no existe una captura real de este evento. El ejemplo siguiente reutiliza el cuerpo de una suscripción `PAUSED` capturada (la misma forma que muestra [`subscription.pause`](#subscription-pause), con `pause_until` de una pausa basada en duración), con los identificadores reemplazados por los de la suscripción de ejemplo de esta página.

```json JSON theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "subscription",
  "type_event": "subscription.auto_resume_failed",
  "account_id": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
  "retry": 0,
  "version": 2,
  "data": {
    "subscription": {
      "code": "e98ef674-9baa-4f7a-8da4-4c812c4749a4",
      "name": "SUB-112 passthrough subject",
      "description": null,
      "country": "CO",
      "account_code": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
      "merchant_reference": "pa-sub112pt-1789487657670-794215",
      "status": "PAUSED",
      "amount": {
        "currency": "COP",
        "value": 45000
      },
      "frequency": {
        "type": "MONTH",
        "value": 1
      },
      "billing_cycles": {
        "total": null,
        "current": 2,
        "paid": 1,
        "next_at": "2026-10-15T15:54:18.312843Z"
      },
      "current_period_start": "2026-09-15T15:54:18.312843Z",
      "current_period_end": "2026-10-15T15:54:18.312843Z",
      "customer_payer": {
        "code": "a9f9140a-1216-481c-8356-1a125078f905"
      },
      "payment_method": {
        "type": "CARD",
        "vaulted_token": "589c51a6-050d-4b9b-a00c-856e064e5f50",
        "card": {
          "installments": null,
          "network_transaction_id": "615803391389209",
          "usage": "USED"
        }
      },
      "availability": {
        "start_at": "2026-09-15T15:54:18.312843Z",
        "finish_at": null
      },
      "retries": {
        "retry_on_decline": false,
        "amount": 6,
        "strategy": "SMART",
        "schedule": null,
        "stop_on_hard_decline": null,
        "cancel_on_exhausted_retries": null
      },
      "metadata": null,
      "additional_data": null,
      "initial_payment_validation": false,
      "reason": null,
      "subscription_agreement_id": null,
      "created_at": "2026-09-15T15:54:18.312843Z",
      "updated_at": "2026-09-15T15:54:22.783678Z",
      "pause_until": "2026-10-15T15:54:22.780166Z"
    }
  }
}
```

`auto_resume_failed` no es un estado en sí mismo: la suscripción lo es, y sigue siendo `PAUSED`. Llama a [Resume Subscription](https://docs.y.uno/reference/subscriptions/resume-subscription.md) para terminar la pausa manualmente una vez que llegue este evento.

### subscription.creation\_failed

Se envía para los pagos de [Stripe Billing](https://docs.y.uno/es/docs/payment-features/subscriptions/stripe-billing.md) cuando un pago `SUCCEEDED` que incluye `external_subscription` no pudo crear su suscripción de Stripe. El dinero está capturado y no se creó ni se activó ninguna suscripción de Stripe. Se envía una vez por cada falla. No se envía cuando el pago ya está reembolsado o reembolsado parcialmente. Suscríbete con el valor `CREATION_FAILED` en `subscription_triggers`.

A diferencia de los demás eventos de suscripción, `data` no incluye un objeto de suscripción de Yuno, porque no existe ninguno:

| Campo | Tipo | Descripción |
| :- | :- | :- |
| `payment_id` | string (UUID) | El pago de Yuno que fue capturado. |
| `external_subscription` | object | El objeto `external_subscription` exactamente como lo enviaste en el pago. |
| `dead_letter_kind` | string | Por qué no se creó la suscripción, por ejemplo `incomplete_payload`, `tax_quote_expired`, `tax_not_calculated` o `stripe_resource_missing`. Trátalo como un valor abierto: se pueden agregar nuevos valores. |
| `reason` | string | Una descripción breve y legible de `dead_letter_kind`. No la analices programáticamente. |
| `occurred_at` | string (ISO 8601, UTC) | Cuándo Yuno dejó de intentar crear la suscripción. |

> [!NOTE]
>
> Todavía no existe una captura real de este evento. El ejemplo siguiente se construye a partir del contrato del evento; los identificadores son ilustrativos.

```json JSON theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "subscription",
  "type_event": "subscription.creation_failed",
  "account_id": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
  "retry": 0,
  "version": 2,
  "data": {
    "payment_id": "4f2b8a3e-6d1c-4b7a-9e2f-8c5d3a1b7e60",
    "external_subscription": {
      "id": "sub_1QwZzz",
      "customer_id": "cus_RplXYZ"
    },
    "dead_letter_kind": "tax_quote_expired",
    "reason": "The tax quote expired",
    "occurred_at": "2026-11-05T14:32:07.512Z"
  }
}
```

El pago permanece `SUCCEEDED`: Yuno no lo reembolsa. Corrige la causa y reintenta el registro con un nuevo pago, reembolsando el original, o reembolsa el original. Consulta [If the subscription cannot be created](https://docs.y.uno/es/docs/payment-features/subscriptions/stripe-billing.md#if-the-subscription-cannot-be-created).

### subscription.cancel

Se envía cuando una suscripción se cancela. Una suscripción cancelada se puede recuperar con [Reactivate Subscription](https://docs.y.uno/reference/subscriptions/reactivate-subscription.md), que conserva la misma suscripción y su historial de pagos.

El objeto de suscripción incluye un campo `cancellation_source` que describe qué desencadenó la cancelación: `MERCHANT`, `SYSTEM`, `PLAN_CHANGE` o `RETRIES_EXHAUSTED`. Consulta [the subscription object](https://docs.y.uno/reference/subscriptions/the-subscription-object.md) para ver qué significa cada valor.

> [!NOTE]
>
> Trata `cancellation_source` como un valor abierto. Se pueden agregar nuevos valores a medida que Yuno introduzca nuevos comportamientos de cancelación, así que maneja un valor no reconocido de forma controlada en lugar de usar un switch exhaustivo sobre la lista actual. `RETRIES_EXHAUSTED` es la incorporación más reciente: se envía cuando los reintentos de un ciclo de facturación terminan sin un pago exitoso en una suscripción creada con `retries.cancel_on_exhausted_retries` establecido en `true`.

```json JSON theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "subscription",
  "type_event": "subscription.cancel",
  "account_id": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
  "retry": 0,
  "version": 2,
  "data": {
    "subscription": {
      "code": "e98ef674-9baa-4f7a-8da4-4c812c4749a4",
      "name": "Subscription",
      "status": "CANCELED",
      "amount": {
        "currency": "COP",
        "type": "FIXED",
        "value": 36000
      },
      "billing_cycles": {
        "total": 5,
        "current": 5,
        "next_at": "2026-01-04T00:35:25.485281Z"
      },
      "current_period_start": "2025-12-04T00:35:25.485281Z",
      "current_period_end": "2026-01-04T00:35:25.485281Z",
      "current_phase_end": null,
      "customer_payer": {
        "code": "a9f9140a-1216-481c-8356-1a125078f905"
      }
    }
  }
}
```

Una suscripción en estado terminal informa su período de facturación final en lugar de uno vacío: el par anterior queda congelado en la ventana que estaba vigente cuando la suscripción llegó a `CANCELED`, de la misma forma en que una suscripción `PAUSED` congela su ventana (consulta la nota de [`subscription.pause`](#subscription-pause)).

### subscription.complete

Se envía cuando una suscripción llega a su fecha de finalización o a su total de ciclos de facturación y pasa al estado `COMPLETED`.

```json JSON theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "subscription",
  "type_event": "subscription.complete",
  "account_id": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
  "retry": 0,
  "version": 2,
  "data": {
    "subscription": {
      "code": "e98ef674-9baa-4f7a-8da4-4c812c4749a4",
      "name": "Subscription",
      "status": "COMPLETED",
      "amount": {
        "currency": "COP",
        "type": "FIXED",
        "value": 36000
      },
      "billing_cycles": {
        "total": 5,
        "current": 5,
        "next_at": "2026-01-04T00:35:25.485281Z"
      },
      "current_period_start": "2025-12-04T00:35:25.485281Z",
      "current_period_end": "2026-01-04T00:35:25.485281Z",
      "current_phase_end": null,
      "customer_payer": {
        "code": "a9f9140a-1216-481c-8356-1a125078f905"
      }
    }
  }
}
```

### subscription.close\_to\_renewal

Se envía antes de una renovación próxima. El momento lo controla `renewal_notification_days` en la suscripción.

```json JSON theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "subscription",
  "type_event": "subscription.close_to_renewal",
  "account_id": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
  "retry": 0,
  "version": 2,
  "data": {
    "subscription": {
      "code": "e98ef674-9baa-4f7a-8da4-4c812c4749a4",
      "name": "Monthly Plan",
      "description": "Monthly subscription",
      "country": "US",
      "account_code": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
      "merchant_reference": "subscription-ref-merchant-002",
      "status": "ACTIVE",
      "amount": {
        "currency": "USD",
        "type": "FIXED",
        "value": 42.46
      },
      "frequency": {
        "type": "MONTH",
        "value": 1,
        "monthly_billing_day": null,
        "execution": "YUNO"
      },
      "billing_date": null,
      "billing_cycles": {
        "total": null,
        "current": 2,
        "next_at": "2026-07-14T19:19:31.914Z"
      },
      "current_period_start": "2026-06-14T19:19:31.914Z",
      "current_period_end": "2026-07-14T19:19:31.914Z",
      "current_phase_end": null,
      "customer_payer": {
        "code": "a9f9140a-1216-481c-8356-1a125078f905"
      },
      "payment_method": {
        "type": "CARD",
        "vaulted_token": "4ba74a56-14d4-4161-a0ba-8036e9b8abf6",
        "card": {
          "installments": null,
          "network_transaction_id": "000000000000000",
          "usage": "USED"
        }
      },
      "availability": {
        "start_at": "2026-06-14T19:19:31.914Z",
        "finish_at": null
      },
      "retries": {
        "retry_on_decline": true,
        "amount": 4,
        "strategy": "DEFAULT",
        "schedule": null,
        "stop_on_hard_decline": null,
        "cancel_on_exhausted_retries": null
      },
      "metadata": [
        {
          "key": "plan_id",
          "value": "monthly_plan"
        }
      ],
      "additional_data": null,
      "payments": [],
      "trial_period": {
        "billing_cycles": 1,
        "amount": {
          "currency": null,
          "value": null
        }
      },
      "initial_payment_validation": false,
      "provider_subscription_id": null,
      "reason": null,
      "subscription_agreement_id": null,
      "soft_descriptor": null,
      "renewal_notification_days": 3,
      "cancellation_time": null,
      "cancellation_source": null,
      "ending_time": null,
      "created_at": "2026-05-14T19:19:32.117629Z",
      "updated_at": "2026-06-15T07:11:52.504031Z",
      "history": null
    }
  }
}
```

### subscription.cycle\_executed

Se envía para las suscripciones basadas en planes cuando se ejecuta un ciclo de `$0`, ya sea un ciclo de prueba o uno con descuento total. Esos ciclos no generan un webhook `payment.purchase`, por lo que este evento es el único comprobante de ellos. `reason` es `TRIAL` o `FULL_DISCOUNT`, `phase` es la fase a la que pertenece el ciclo y `breakdown` incluye el mismo detalle de líneas que un ciclo pagado, con un total de cero.

```json JSON theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "subscription",
  "type_event": "subscription.cycle_executed",
  "account_id": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
  "retry": 0,
  "version": 2,
  "data": {
    "subscription": {
      "code": "e98ef674-9baa-4f7a-8da4-4c812c4749a4",
      "name": "Monthly Plan",
      "status": "TRIALING",
      "plan_id": "0b0a2f7a-3d19-4a52-8f0e-3f1a3d5a3f21",
      "current_phase": "TRIAL",
      "billing_cycles": {
        "total": null,
        "current": 2,
        "next_at": "2026-07-14T19:19:31.914Z"
      },
      "current_period_start": "2026-06-14T19:19:31.914Z",
      "current_period_end": "2026-07-14T19:19:31.914Z",
      "current_phase_end": "2026-07-14T19:19:31.914Z",
      "payments": []
    },
    "cycle": 1,
    "reason": "TRIAL",
    "phase": "TRIAL",
    "plan_id": "0b0a2f7a-3d19-4a52-8f0e-3f1a3d5a3f21",
    "phase_payment": 1,
    "billing_cycle": 1,
    "breakdown": {
      "currency": "USD",
      "subtotal": 0,
      "total": 0,
      "plan_id": "0b0a2f7a-3d19-4a52-8f0e-3f1a3d5a3f21",
      "line_items": [
        {
          "type": "PLAN",
          "label": "Trial",
          "service_period": {
            "start": "2026-06-14T19:19:31.914Z",
            "end": "2026-07-14T19:19:31.914Z"
          },
          "amount": {
            "currency": "USD",
            "value": 0
          }
        }
      ]
    }
  }
}
```

### subscription.phase\_completed

Se envía para las suscripciones basadas en planes cuando termina una fase de facturación, inmediatamente antes del `subscription.phase_started` de la fase que la reemplaza. No se envía para la primera fase, que no tiene antecesora. `phase` es la fase que acaba de terminar.

```json JSON theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "subscription",
  "type_event": "subscription.phase_completed",
  "account_id": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
  "retry": 0,
  "version": 2,
  "data": {
    "subscription": {
      "code": "e98ef674-9baa-4f7a-8da4-4c812c4749a4",
      "name": "Monthly Plan",
      "status": "ACTIVE",
      "plan_id": "0b0a2f7a-3d19-4a52-8f0e-3f1a3d5a3f21",
      "current_phase": "REGULAR",
      "payments": []
    },
    "phase": "TRIAL"
  }
}
```

### subscription.phase\_started

Se envía para las suscripciones basadas en planes cuando comienza una fase de facturación, incluida la primera. `phase` es la fase que está comenzando y `previous_phase` es la que reemplaza, o `null` para la primera fase.

```json JSON theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "subscription",
  "type_event": "subscription.phase_started",
  "account_id": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
  "retry": 0,
  "version": 2,
  "data": {
    "subscription": {
      "code": "e98ef674-9baa-4f7a-8da4-4c812c4749a4",
      "name": "Monthly Plan",
      "status": "ACTIVE",
      "plan_id": "0b0a2f7a-3d19-4a52-8f0e-3f1a3d5a3f21",
      "current_phase": "REGULAR",
      "payments": []
    },
    "phase": "REGULAR",
    "previous_phase": "TRIAL"
  }
}
```

### subscription.plan\_change\_scheduled

Se envía cuando se programa un cambio de plan para el próximo ciclo de facturación. El bloque `plan_change` describe el cambio pendiente; `applies_at` es la próxima fecha de facturación en la que el cambio entrará en vigor.

```json JSON theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "subscription",
  "type_event": "subscription.plan_change_scheduled",
  "account_id": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
  "retry": 0,
  "version": 2,
  "data": {
    "subscription": {
      "code": "e98ef674-9baa-4f7a-8da4-4c812c4749a4",
      "name": "Subscription",
      "status": "ACTIVE",
      "amount": {
        "currency": "USD",
        "type": "FIXED",
        "value": 9.99
      },
      "customer_payer": {
        "code": "a9f9140a-1216-481c-8356-1a125078f905"
      }
    },
    "plan_change": {
      "plan_id": "1904911d-5df9-429e-8488-ad41abea1a4d",
      "plan_name": "Pro",
      "direction": "UPGRADE",
      "effective": "NEXT_BILLING_CYCLE",
      "phases_behavior": "START_FROM_REGULAR",
      "applies_at": "2026-08-15T00:00:00Z",
      "requested_at": "2026-07-28T14:02:11Z"
    }
  }
}
```

### subscription.plan\_change\_canceled

Se envía cuando un cambio de plan pendiente se deshace o se aborta. El `reason` dentro de `plan_change` es `MERCHANT_UNDO` cuando el comercio envió `"plan_change": null`, o `TARGET_PLAN_CANCELED` cuando el plan de destino se canceló antes de que se aplicara el cambio; en ambos casos la suscripción permanece en su plan actual. Si la propia suscripción se cancela, el cambio pendiente se descarta silenciosamente y solo se envía `subscription.cancel`.

```json JSON theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "subscription",
  "type_event": "subscription.plan_change_canceled",
  "account_id": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
  "retry": 0,
  "version": 2,
  "data": {
    "subscription": {
      "code": "e98ef674-9baa-4f7a-8da4-4c812c4749a4",
      "name": "Subscription",
      "status": "ACTIVE",
      "amount": {
        "currency": "USD",
        "type": "FIXED",
        "value": 9.99
      },
      "customer_payer": {
        "code": "a9f9140a-1216-481c-8356-1a125078f905"
      }
    },
    "plan_change": {
      "plan_id": "1904911d-5df9-429e-8488-ad41abea1a4d",
      "plan_name": "Pro",
      "reason": "MERCHANT_UNDO"
    }
  }
}
```

### subscription.plan\_changed

Se envía cuando un cambio de plan entra en vigor. `previous_plan_id` identifica el plan del que se alejó la suscripción; la suscripción incluida ya refleja el nuevo plan.

Un cambio programado se aplica en la renovación que factura por primera vez el nuevo plan, en el mismo lugar: la suscripción incluida conserva el mismo `code`. En cambio, `POST /v1/subscriptions/{id}/plan` reemplaza la suscripción: el payload incluye un nuevo `code` con `previous_subscription_id` establecido, y se dispara un `subscription.cancel` aparte (`cancellation_source: PLAN_CHANGE`) para la original.

```json JSON theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "subscription",
  "type_event": "subscription.plan_changed",
  "account_id": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
  "retry": 0,
  "version": 2,
  "data": {
    "subscription": {
      "code": "e98ef674-9baa-4f7a-8da4-4c812c4749a4",
      "name": "Subscription",
      "status": "ACTIVE",
      "plan_id": "1904911d-5df9-429e-8488-ad41abea1a4d",
      "amount": {
        "currency": "USD",
        "type": "FIXED",
        "value": 29.99
      },
      "customer_payer": {
        "code": "a9f9140a-1216-481c-8356-1a125078f905"
      }
    },
    "previous_plan_id": "0804911d-5df9-429e-8488-ad41abea1a4c"
  }
}
```

### subscription.cancel\_scheduled

Se envía cuando se programa una cancelación mediante `POST /v1/subscriptions/{id}/cancel` con un bloque `schedule`. `cancel_scheduled` describe la programación pendiente. Consulta [Cancel Subscription](https://docs.y.uno/reference/subscriptions/cancel-subscription.md#scheduling-a-cancellation-instead).

```json JSON theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "subscription",
  "type_event": "subscription.cancel_scheduled",
  "account_id": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
  "retry": 0,
  "version": 2,
  "data": {
    "subscription": {
      "code": "e98ef674-9baa-4f7a-8da4-4c812c4749a4",
      "name": "Subscription",
      "status": "ACTIVE",
      "amount": {
        "currency": "USD",
        "type": "FIXED",
        "value": 9.99
      },
      "customer_payer": {
        "code": "a9f9140a-1216-481c-8356-1a125078f905"
      }
    },
    "cancel_scheduled": {
      "mode": "AFTER_CYCLES",
      "after_cycles": 3,
      "at": "<example>",
      "requested_at": "<example>",
      "past_due_behavior": "EXHAUST_RETRIES"
    }
  }
}
```

### subscription.cancel\_schedule\_canceled

Se envía cuando una cancelación programada pendiente se deshace mediante `"schedule": null` en `POST /v1/subscriptions/{id}/cancel`. No se envía cuando la programación se ejecuta; en ese caso se dispara `subscription.cancel`.

```json JSON theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "subscription",
  "type_event": "subscription.cancel_schedule_canceled",
  "account_id": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
  "retry": 0,
  "version": 2,
  "data": {
    "subscription": {
      "code": "e98ef674-9baa-4f7a-8da4-4c812c4749a4",
      "name": "Subscription",
      "status": "ACTIVE",
      "amount": {
        "currency": "USD",
        "type": "FIXED",
        "value": 9.99
      },
      "customer_payer": {
        "code": "a9f9140a-1216-481c-8356-1a125078f905"
      }
    }
  }
}
```

### Cobros de renovación y fallas (sin `subscription.error`)

> [!WARNING]
>
> **No existe un webhook `subscription.error`**. Yuno no emite un evento de suscripción cuando falla un cobro de renovación. Los resultados de los cobros de renovación, tanto los recobros exitosos como los intentos fallidos o rechazados, se entregan como webhooks `payment.purchase` vinculados a la suscripción, con el resultado en los campos `status`/`sub_status`. Suscríbete a `payment.purchase` para seguir los resultados de las renovaciones. Los ciclos de `$0`/prueba no emiten ningún webhook de pago; en las suscripciones basadas en planes se informan como [`subscription.cycle_executed`](#subscription-cycle_executed).

> [!NOTE]
>
> El **cobro** de la renovación siempre se señala mediante un webhook `payment.purchase`, nunca mediante un webhook de suscripción. El arreglo `payments` dentro del objeto de suscripción está siempre vacío actualmente en los payloads de webhook. `subscription.active` se envía cuando la suscripción se activa por primera vez (en `billing_cycles.current` = 2), no en cada renovación; solo se envía de nuevo cuando una suscripción se recupera de `PAST_DUE`.

> [!NOTE]
>
> Una renovación fallida sí genera un webhook de suscripción en dos casos. Donde el estado `PAST_DUE` está habilitado para la cuenta, el primer cobro fallido de un ciclo pasa la suscripción a `PAST_DUE` y emite [`subscription.past_due`](#subscription-past_due). Y si la suscripción tiene `retries.cancel_on_exhausted_retries` establecido en `true`, cuando los reintentos de ese ciclo terminan sin un pago exitoso la suscripción se cancela y se emite un único [`subscription.cancel`](#subscription-cancel) con `cancellation_source` establecido en `RETRIES_EXHAUSTED`. Esto sigue sin ser un `subscription.error`: los intentos fallidos individuales siguen siendo webhooks `payment.purchase`. Solo la cancelación final se señala en la suscripción.

## Onboardings

El siguiente objeto JSON presenta un ejemplo de una estructura de datos relacionada con un evento de onboarding, en este caso `onboarding.error`.

```json Example theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
    "type": "onboarding",
    "type_event": "onboarding.error",
    "account_id": "c2721496-89c3-497a-8e24-0872c2e1386c",
    "retry": 0,
    "version": 2,
    "data": {
        "id": "d1fbb1d7-321d-4855-b603-135cd4f4ab82",
        "type": "TWO_STEP_ONBOARDING",
        "workflow": "DIRECT",
        "description": null,
        "status": "ERROR",
        "response_message": null,
        "callback_url": "https://merchant.example.com/webhook/onboarding",
        "provider": {
            "id": "STRIPE",
            "connection_id": "caaeba00-05c8-4295-815f-1736c2b0b622",
            "redirect_url": null,
            "recipient_id": "",
            "onboarding_url": "",
            "legal_entity": null
        },
        "documentation": [],
        "legal_representatives": [],
        "withdrawal_methods": {
            "bank": {
                "code": "002",
                "branch": "002",
                "branch_digit": null,
                "account": "9876543210",
                "account_digit": null,
                "account_type": "CHECKINGS",
                "routing": "021000022",
                "country": "US",
                "currency": "USD",
                "payout_schedule": null
            }
        },
        "requirements": [
            {
                "field": "withdrawal_methods.bank.routing",
                "message": "Invalid routing number",
                "status": "REJECTED"
            }
        ],
        "terms_of_service": null,
        "metadata": [],
        "recipient": {
            "id": "c5e0d5d5-5346-4fea-9b3e-97e825b11b07",
            "national_entity": "INDIVIDUAL",
            "merchant_recipient_id": "12b2b154-3ac9-4255-848a-46c8e3a70476",
            "entity_type": "PRIVATE",
            "first_name": "Juan",
            "last_name": "Pérez",
            "legal_name": null,
            "email": "juan.perez@example.com",
            "date_of_birth": "1990-01-15",
            "country": "CO",
            "website": "https://juanperez.com",
            "industry": "Technology",
            "merchant_category_code": "5734",
            "document": {
                "document_number": "1234567890",
                "document_type": "CC"
            },
            "phone": {
                "country_code": "57",
                "number": "3001234567"
            },
            "address": {
                "address_line_1": "Carrera 7 # 32-16",
                "address_line_2": "Oficina 201",
                "city": "Bogotá",
                "country": "CO",
                "state": "Cundinamarca",
                "zip_code": "110311",
                "neighborhood": "Centro"
            },
            "withdrawal_methods": {
                "bank": {
                    "code": "001",
                    "branch": "004",
                    "branch_digit": "123",
                    "account": "1234567890",
                    "account_digit": "123",
                    "account_type": "SAVINGS",
                    "routing": "021000021",
                    "country": "CO",
                    "currency": "COP",
                    "payout_schedule": null
                }
            },
            "documentation": [],
            "legal_representatives": [
                {
                    "merchant_reference": "REP_001",
                    "first_name": "María",
                    "last_name": "González",
                    "email": "maria.gonzalez@example.com",
                    "date_of_birth": "1985-05-20",
                    "country": "CO",
                    "nationality": "CO",
                    "title": "CEO",
                    "publicly_exposed_person": false,
                    "ultimate_beneficial_owner": true,
                    "document": {
                        "document_number": "0987654321",
                        "document_type": "CC"
                    },
                    "phone": {
                        "country_code": "+57",
                        "number": "3109876543"
                    },
                    "address": {
                        "address_line_1": "Calle 26 # 13-19",
                        "address_line_2": null,
                        "city": "Bogotá",
                        "country": "CO",
                        "state": "Cundinamarca",
                        "zip_code": "110311",
                        "neighborhood": null
                    }
                }
            ],
            "created_at": "2025-10-21T16:29:36.997492Z",
            "updated_at": "2025-10-21T16:29:36.997505Z"
        },
        "created_at": "2025-10-21T16:29:41.88055Z",
        "updated_at": "2025-10-21T16:29:42.571531Z",
        "expires_at": null
    }
}
```

## Transferencias de split de marketplace

Las notificaciones de transferencias independientes incluyen el `direction` guardado en el nivel superior del cuerpo JSON entregado. Las transferencias existentes usan `PLATFORM_TO_RECIPIENT`. La disponibilidad de destinatario a plataforma sigue lo indicado en el [endpoint de creación](https://docs.y.uno/reference/transfers/create-standalone-transfer.md).

Los ejemplos siguientes muestran campos seleccionados del cuerpo entregado. Los encabezados son los tipos de evento de suscripción; el cuerpo entregado es el propio objeto de transferencia, sin sobre y sin un campo de tipo de evento. Identifica una notificación de reversión por su `status` (`REVERSED` o `REVERSED_PARTIAL`) y por una transacción de tipo `SPLIT_TRANSFER_REVERSE`. `provider_data` describe la cuenta del proveedor que procesó la transferencia; el `raw_response` de cada transacción incluye la respuesta sin procesar del proveedor, serializada en JSON como una cadena.

> [!NOTE]
>
> Según ingeniería, el `type_event` bajo el cual se registran internamente estos dos eventos es `transfer.transfer`; el cuerpo del webhook entregado no incluye ningún sobre `type`/`type_event`, como se indicó antes.

### split\_transfer.succeeded

Se envía cuando una transferencia de split de marketplace se completa correctamente.

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "recipient_id": "d246d578-266c-47c3-92b6-1748d780711b",
  "direction": "PLATFORM_TO_RECIPIENT",
  "amount": {
    "currency": "USD",
    "value": 4
  },
  "status": "SUCCEEDED",
  "description": "Weekly marketplace earnings",
  "merchant_reference": null,
  "metadata": null,
  "provider_data": {
    "id": "STRIPE",
    "recipient_id": "acct_1H2c3d4E5f6G7h8I",
    "transfer_id": "tr_example",
    "response_code": null,
    "response_message": null
  },
  "transactions": [
    {
      "code": "cb5fd244-90fd-49b0-a160-a9d9f764eb9e",
      "type": "SPLIT_TRANSFER",
      "status": "SUCCEEDED",
      "parent_transaction_code": null,
      "provider_transfer_id": "tr_example",
      "provider_response_code": null,
      "provider_response_message": null,
      "raw_response": "{\"id\":\"tr_example\",\"status\":\"paid\"}",
      "reason": null,
      "created_at": "2026-09-15T10:00:00Z",
      "updated_at": "2026-09-15T10:00:00Z"
    }
  ],
  "created_at": "2026-09-15T10:00:00Z",
  "updated_at": "2026-09-15T10:00:00Z",
  "completed_at": "2026-09-15T10:00:00Z"
}
```

### split\_transfer\_reverse.succeeded

La notificación identifica la transferencia original, conserva su dirección e incluye tanto la transacción original como la de reversión. En este ejemplo de reversión parcial, `status` es `REVERSED_PARTIAL` y `amount` es el monto de reversión de USD 1. La transacción de reversión apunta a la transacción original mediante `parent_transaction_code`. Esta notificación es distinta de la respuesta HTTP de la reversión, que no incluye la dirección. Se entrega bajo el `id` de la transferencia original; `description` y `merchant_reference` contienen los valores enviados en la solicitud de reversión.

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "recipient_id": "d246d578-266c-47c3-92b6-1748d780711b",
  "direction": "PLATFORM_TO_RECIPIENT",
  "amount": {
    "currency": "USD",
    "value": 1
  },
  "status": "REVERSED_PARTIAL",
  "description": "Reversal due to order cancelled",
  "merchant_reference": "reverse-merchant-ref",
  "metadata": null,
  "provider_data": {
    "id": "STRIPE",
    "recipient_id": "acct_1H2c3d4E5f6G7h8I",
    "transfer_id": "trr_example",
    "response_code": null,
    "response_message": null
  },
  "transactions": [
    {
      "code": "cb5fd244-90fd-49b0-a160-a9d9f764eb9e",
      "type": "SPLIT_TRANSFER",
      "status": "SUCCEEDED",
      "parent_transaction_code": null,
      "provider_transfer_id": "tr_example",
      "provider_response_code": null,
      "provider_response_message": null,
      "raw_response": "{\"id\":\"tr_example\",\"status\":\"paid\"}",
      "reason": null,
      "created_at": "2026-09-15T10:00:00Z",
      "updated_at": "2026-09-15T10:00:00Z"
    },
    {
      "code": "0e5b4d60-4811-4a48-90c1-398d28dbce8c",
      "type": "SPLIT_TRANSFER_REVERSE",
      "status": "SUCCEEDED",
      "parent_transaction_code": "cb5fd244-90fd-49b0-a160-a9d9f764eb9e",
      "provider_transfer_id": "trr_example",
      "provider_response_code": null,
      "provider_response_message": null,
      "raw_response": "{\"id\":\"trr_example\",\"status\":\"reversed\"}",
      "reason": "ORDER_CANCELLED",
      "created_at": "2026-09-15T10:05:00Z",
      "updated_at": "2026-09-15T10:05:00Z"
    }
  ],
  "created_at": "2026-09-15T10:00:00Z",
  "updated_at": "2026-09-15T10:05:00Z",
  "completed_at": "2026-09-15T10:05:00Z"
}
```

## Reembolsos

El siguiente objeto JSON presenta un ejemplo de una estructura de datos relacionada con un evento `payment.refund`.

```json Example theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "payment",
  "type_event": "payment.refund",
  "account_id": "2e7bc710-32db-43b2-a7aa-21c3bd031f8f",
  "retry": 0,
  "version": 2,
  "data": {
    "payment": {
    "code": "f7bcf40d-7255-4e13-9dba-df6fa09be6b2",
    "id": "f7bcf40d-7255-4e13-9dba-df6fa09be6b2",
    "idempotency_key": "49eda7f2-bb05-437f-9676-7c8bb6df94a9",
    "organization_code": "c60f4657-6ec5-487c-b9d5-a5fdbc887a1f",
    "account_code": "2e7bc710-32db-43b2-a7aa-21c3bd031f8f",
    "account_id": "2e7bc710-32db-43b2-a7aa-21c3bd031f8f",
    "description": "Test goold",
    "country": "CO",
    "status": "REFUNDED",
    "sub_status": "REFUNDED",
    "order_id": "0000023",
    "merchant_order_id": "0000023",
    "created_at": "2025-09-03T21:51:08.633533Z",
    "updated_at": "2025-09-03T21:53:40.368707Z",
    "amount": {
      "currency": "COP",
      "value": 30000,
      "refunded": 30000,
      "captured": 0,
      "currency_conversion": {
        "code": "ccv_01HVK3Z9M2...",
        "cardholder_currency": "USD",
        "cardholder_amount": 7.50,
        "cardholder_accepted": true,
        "rate": 4000.00,
        "rate_margin_percentage": 3.0,
        "rate_source": "BLOOMBERG",
        "provider": "PLANET",
        "description": "DCC quote for retail shopping.",
        "created_at": "2026-04-24T14:30:00Z",
        "expires_at": "2026-04-24T15:30:00Z",
        "status": "APPLIED",
        "error_reason": null,
        "provider_data": {
          "terminal_id": "TERM_99"
        }
      }
    },
    "checkout": {
      "session": null,
      "sdk_action_required": false
    },
    "customer_payer": {
      "code": "1ca7351f-8855-4765-bbe5-bd5110809cf2",
      "id": "1ca7351f-8855-4765-bbe5-bd5110809cf2",
      "organization_customer_external_id": "1756936266",
      "merchant_customer_id": "1756936266",
      "first_name": "Willintong",
      "last_name": "Ramirez",
      "gender": "M",
      "date_of_birth": "1990-02-28",
      "email": "willintong.ramirez@y.uno",
      "nationality": "AR",
      "ip_address": null,
      "device_fingerprint": null,
      "third_party_session_id": null,
      "device_fingerprints": [],
      "browser_info": null,
      "document": {
        "document_number": "123554332",
        "document_type": "PASS"
      },
      "billing_address": {
        "address_line_1": "Calle 34 # 56 - 78",
        "address_line_2": "Apartamento 502, Torre I",
        "city": "Bogotá",
        "country": "CO",
        "state": "Cundinamarca",
        "zip_code": "111111",
        "neighborhood": null
      },
      "shipping_address": {
        "address_line_1": "Calle 34 # 56 - 78",
        "address_line_2": "Apartamento 502, Torre I",
        "city": "Bogotá",
        "country": "CO",
        "state": "Cundinamarca",
        "zip_code": "111111",
        "neighborhood": null
      },
      "phone": {
        "country_code": "57",
        "number": "3132450765"
      },
      "merchant_customer_created_at": null,
      "geo_location": {
        "latitude": null,
        "longitude": null
      },
      "merchant_customer_validations": {
        "account_is_verified": true,
        "email_is_verified": true,
        "phone_is_verified": true
      }
    },
    "additional_data": {
      "order": {
        "shipping_amount": 10.35,
        "fee_amount": 40.5,
        "tip_amount": null,
        "items": [
          {
            "id": "123AD",
            "name": "Skirt",
            "quantity": 3,
            "unit_amount": 20,
            "category": "Clothes",
            "brand": "XYZ",
            "sku_code": "8765432109",
            "manufacture_part_number": "XYZ123456",
            "image_url": null
          }
        ],
        "taxes": [],
        "shipping": null,
        "account_funding": null,
        "tickets": [],
        "fulfillment": null,
        "discounts": [],
        "sales_channel": null
      },
      "airline": null,
      "transportations": null,
      "seller_details": null
    },
    "transactions": {
      "code": "14a2ca8a-07bd-47b2-9070-4868ab176ac8",
      "id": "14a2ca8a-07bd-47b2-9070-4868ab176ac8",
      "type": "REFUND",
      "status": "SUCCEEDED",
      "category": "CARD",
      "amount": 30000,
      "provider_id": "YUNO_TEST_PAYMENT_GW",
      "response_code": "SUCCEEDED",
      "merchant_reference": "REFUND_001",
      "response_message": "Transaction successful",
      "reason": "REQUESTED_BY_CUSTOMER",
      "description": "Test refund",
      "created_at": "2025-09-03T21:53:40.230290Z",
      "updated_at": "2025-09-03T21:53:40.346884Z",
      "payment_method": {
        "token": null,
        "type": "CARD",
        "vaulted_token": null,
        "vault_on_success": false,
        "parent_payment_method_type": null,
        "payment_method_detail": {
          "card": {
            "verify": false,
            "capture": false,
            "installments": 1,
            "installments_plan_id": null,
            "first_installment_deferral": null,
            "installments_amount": null,
            "installments_type": null,
            "soft_descriptor": "",
            "authorization_code": "658571",
            "retrieval_reference_number": "",
            "acquirer_reference_number": "",
            "voucher": null,
            "card_data": {
              "holder_name": "Pepito Perez",
              "iin": "41111111",
              "lfd": "1111",
              "number_length": 16,
              "security_code_length": 3,
              "brand": "VISA",
              "issuer_name": "CONOTOXIA SP Z O O",
              "issuer_code": null,
              "country_code": "PL",
              "category": "CLASSIC",
              "type": "DEBIT",
              "three_d_secure": {
                "version": null,
                "electronic_commerce_indicator": null,
                "cryptogram": null,
                "transaction_id": null,
                "directory_server_transaction_id": null,
                "pares_status": null,
                "acs_id": null,
                "strong_customer_authentication_exemptions": null
              },
              "network_token": null,
              "fingerprint": "3d49ec9d-e941-4eaf-80eb-251469d66108",
              "expiration_month": 3,
              "expiration_year": 26
            },
            "stored_credentials": {
              "reason": null,
              "usage": null,
              "subscription_agreement_id": null,
              "network_transaction_id": null
            }
          },
          "wallet": null,
          "bnpl": null,
          "bank_transfer": null,
          "ticket": null,
          "payment_link": null
        }
      },
      "provider": {
        "provider_transaction_id": "a9908f18-71ca-458b-9f94-f63e55bdc94a"
      },
      "provider_data": {
        "raw_response": {
          "message": "provider response"
        },
        "id": "YUNO_TEST_PAYMENT_GW",
        "transaction_id": "a9908f18-71ca-458b-9f94-f63e55bdc94a",
        "account_id": null,
        "status": null,
        "status_detail": null,
        "response_message": null,
        "response_code": "SUCCEEDED",
        "third_party_transaction_id": null,
        "third_party_account_id": null,
        "iso8583_response_code": null,
        "iso8583_response_message": null
      },
      "connection_data": {
        "id": null,
        "name": null
      },
      "simplified_mode": false,
      "third_party_session_id": null,
      "receipt": false,
      "receipt_language": null,
      "receipt_url": null,
      "device_fingerprint": null
    },
    "transactions_history": [],
    "callback_url": null,
    "workflow": "DIRECT",
    "split_marketplace": [],
    "payment_link_code": "",
    "subscription_id": null,
    "subscription": null,
    "fraud_screening": null,
    "metadata": [],
    "routing_rules": {
      "smart_routing": false,
      "monitors": false,
      "condition": {
        "id": 148781,
        "name": null,
        "description": null
      }
    }
    }
  }
}
```

## HMAC - Autorización

El siguiente ejemplo muestra una solicitud de webhook sin procesar con el encabezado `x-hmac-signature` que Yuno incluye cuando la autenticación HMAC está habilitada.

```http theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
POST /your-webhook-endpoint HTTP/1.1
Host: your-server.com
Content-Type: application/json
x-api-key: your-api-key
x-secret: your-secret
x-hmac-signature: YwPQ1b2RcBkDGo32XvDS7R+/nMDuDIRjvQlsak72EMBY=

{
  "live": "false",
  "notificationItems": [
    {
      "NotificationRequestItem": {
        "additionalData": {
          "expiryDate": "12/2012",
          "authCode": "1234",
          "cardSummary": "7777",
          "totalFraudScore": "10"
        },
        "amount": {
          "currency": "EUR",
          "value": 10100
        },
        "eventCode": "AUTHORISATION",
        "eventDate": "2022-11-15T20:04:11+01:00",
        "merchantAccountCode": "AcmeCorp",
        "merchantReference": "2931874530016873",
        "paymentMethod": "visa",
        "pspReference": "CU4KVBAYAPFG0ZZKR",
        "success": "true"
      }
    }
  ]
}
```


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