Envía datos de tarjeta Nivel 2 y Nivel 3

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

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.

{
  "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.

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.

Primeros pasos

Conceptos básicos

Guías

Webhooks

Asistente de IA

Plugins de e-commerce

Envía datos de tarjeta Nivel 2 y Nivel 3

Activa con `commercialData`

Los montos deben cuadrar

Envíalo en la captura

Las sesiones de checkout bloquean los datos

Qué envía cada conexión

Qué no se incluye

​Activa con commercialData

​Los montos deben cuadrar

​Envíalo en la captura

​Las sesiones de checkout bloquean los datos

​Qué envía cada conexión

​Qué no se incluye

Activa con `commercialData`

Los montos deben cuadrar

Envíalo en la captura

Las sesiones de checkout bloquean los datos

Qué envía cada conexión

Qué no se incluye