> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therius.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Envía datos de tarjeta Nivel 2 y Nivel 3

> Envía orden de compra, impuestos y detalle por línea con los pagos con tarjeta para que las tarjetas empresariales, de compras y corporativas califiquen para un interchange menor.

Los datos Nivel 2 y Nivel 3 son detalle adicional de la orden que envías con un pago con tarjeta. Cuando el titular usa una **tarjeta empresarial, de compras o corporativa**, las redes de tarjetas pueden cobrar un interchange menor en las transacciones que lo incluyen. Importa sobre todo en ventas B2B y a gobierno en Estados Unidos, y no tiene efecto en tarjetas de consumo.

| Nivel | Qué envías | Uso típico |
| - | - | - |
| **Nivel 2** | Referencia del cliente (número de orden de compra) y el monto del impuesto a las ventas | Cualquier venta con tarjeta comercial |
| **Nivel 3** | Nivel 2, más cada ítem de línea (código de producto, cantidad, unidad de medida, precio unitario, código de commodity, descuento, impuesto), flete y datos de destino | Bienes físicos enviados a una empresa o agencia |

> [!NOTE]
>
> Therius reenvía los datos. Que un pago califique o no para la tarifa menor lo deciden la red de tarjetas, el emisor y tu adquirente, según el tipo de tarjeta, tu categoría de comercio y los montos.

## Activa con `commercialData`

Agrega un objeto `commercialData` en la raíz de una solicitud de tarjeta `POST /payment/purchase` o `POST /payment/authorization`, junto a `lineItems`. El detalle de Nivel 3 se lee de `lineItems` solo cuando `commercialData` está presente.

| Campo | Tipo | Descripción |
| - | - | - |
| `customerReference` | string | La referencia de tu comprador para la orden, como un número de orden de compra. Hasta 25 caracteres ASCII imprimibles, sin espacio inicial. |
| `taxAmount` | integer | Impuesto total a las ventas incluido en el `amount` del pago, en unidades menores. Omítelo para usar la suma del `taxAmount` de los ítems. Envía `0` para una orden exenta. |
| `freightAmount` | integer | Envío o flete incluido en el `amount` del pago, en unidades menores. |
| `shipFromPostalCode` | string | Código postal de origen del envío, hasta 10 caracteres. |
| `destination` | object | Destino de los bienes: `countryCode` (ISO 3166-1), `postalCode` (hasta 10 caracteres) y `stateOrProvince` (hasta 3 caracteres). |
| `orderDate` | string | Fecha de la orden de compra, `YYYY-MM-DD`. |

Para Nivel 2 basta con `customerReference` y el monto del impuesto. Para Nivel 3, agrega además los siguientes campos a **cada** ítem de `lineItems`:

| Campo | Tipo | Descripción |
| - | - | - |
| `description` | string | Qué es el ítem. Obligatorio. |
| `quantity` | integer | Unidades compradas, de 1 a 9999. Obligatorio. |
| `unitAmount` | integer | Precio de una unidad en unidades menores, antes de descuento e impuesto. Al definirlo en un ítem, la solicitud se trata como Nivel 3, así que defínelo en todos los ítems o en ninguno. |
| `amount` | integer | El total de la línea **incluyendo el impuesto de la línea**. Debe ser igual a `unitAmount × quantity − discountAmount + taxAmount`. |
| `productCode` | string | Código de producto o SKU, hasta 12 caracteres. Por defecto usa `id`. |
| `unitOfMeasure` | string | Código de unidad de medida, como `EA` (cada uno). |
| `commodityCode` | string | Código de commodity del ítem (UNSPSC, NAICS o NAPCS), hasta 12 caracteres. |
| `discountAmount` | integer | Descuento aplicado a la línea, en unidades menores. |
| `taxAmount` | integer | Impuesto de la línea, en unidades menores. |

## Los montos deben cuadrar

Therius verifica la aritmética antes de llamar al proveedor y devuelve un `400` con la diferencia exacta si no cuadra:

```
suma de (unitAmount × quantity − discountAmount) + impuesto total + freightAmount = monto del pago
```

El `amount` de cada línea es su total con impuesto, como en el ejemplo siguiente.

```json theme={"dark"}
{
  "merchantCode": "MERCHANT_001",
  "orderCode": "ORDER-1001",
  "amount": { "currency": "USD", "value": 12800, "exponent": 2 },
  "paymentMethod": { "type": "card", "card": { "nonceData": { "nonce": "<nonce>" } } },
  "commercialData": {
    "customerReference": "PO-2026-9",
    "freightAmount": 300,
    "shipFromPostalCode": "94110",
    "destination": { "countryCode": "US", "postalCode": "94117", "stateOrProvince": "CA" },
    "orderDate": "2026-10-25"
  },
  "lineItems": [
    {
      "description": "Widget", "quantity": 2, "unitAmount": 5000, "discountAmount": 500, "taxAmount": 900,
      "amount": 10400, "productCode": "W-1", "unitOfMeasure": "EA", "commodityCode": "44121706"
    },
    {
      "description": "Gadget", "quantity": 1, "unitAmount": 2000, "taxAmount": 100,
      "amount": 2100, "productCode": "G-2", "unitOfMeasure": "EA", "commodityCode": "44121706"
    }
  ]
}
```

Aquí las líneas netas suman 9,500 + 2,000 = 11,500, el impuesto es 900 + 100 = 1,000 y el flete es 300, para un total de 12,800.

> [!TIP]
>
> Si envías un `taxAmount` a nivel de orden y también valores de `taxAmount` por línea, deben coincidir. Envía el impuesto en un solo nivel si lo prefieres.

## Envíalo en la captura

Si autorizas primero y capturas después, puedes enviar `commercialData` y `lineItems` en el cuerpo de `POST /payment/{id}/capture`. Hazlo cuando no enviaste los datos con la autorización, o cuando el monto capturado o las líneas difieren de ella. Aplican las mismas reglas, verificadas contra el `amount` de la captura.

## Las sesiones de checkout bloquean los datos

Cuando creas una sesión de checkout con `POST /sdk/session`, pasa ahí `commercialData` y `lineItems`. La sesión los bloquea: un pago hecho con el token de la sesión siempre usa los valores bloqueados e ignora cualquier `commercialData` de la llamada de pago, porque esa llamada puede venir del navegador. Un pago que tu servidor hace con una clave de API privada envía su propio `commercialData`.

## Qué envía cada conexión

| Conexión | Nivel 2 | Nivel 3 | Autorización y compra | Captura |
| - | - | - | - | - |
| Adyen | Sí | Sí | Sí | Sí |
| Stripe | Sí | Sí | Sí | Sí |
| NMI | Sí | Sí | Sí | No |

Las demás conexiones de tarjeta ignoran `commercialData`; el pago se procesa normalmente.

Cada adquirente es estricto con lo que acepta, y Therius nunca rechaza ni hace fallar un pago porque falten datos mejorados o sean rechazados. Cuando los datos no alcanzan, Therius envía lo que puede:

* **Adyen** exige `customerReference` e impuesto en ambos niveles, un impuesto distinto de cero para Nivel 2 y, en cada línea, `productCode` (hasta 12 caracteres), `unitOfMeasure` (hasta 3 caracteres) y `commodityCode` (hasta 12 caracteres). Si a una línea le falta alguno, Therius envía solo Nivel 2. Las descripciones se recortan a 26 caracteres.
* **Stripe** usa tu `orderCode` como referencia de la orden y envía el impuesto a nivel de orden. El código de producto, la unidad de medida y el código de commodity son opcionales para la solicitud, pero se necesitan para recibir tarifas de Nivel 3. Si la versión de API de tu cuenta de Stripe aún no admite payment line items, Therius envía el pago sin los datos.
* **NMI** acepta hasta 99 ítems de línea. Con más, Therius envía solo los campos a nivel de orden.

## Qué no se incluye

* Los datos Nivel 2/3 son para pagos con tarjeta. Se ignoran en métodos de pago alternativos y billeteras que se liquidan fuera de las redes de tarjetas.
* Los reembolsos y las cancelaciones no los llevan.
* No se admiten los campos de aranceles, IVA/VAT ni descuento a nivel de orden. Pon los descuentos en los ítems de línea.


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