Envie dados de cartão Nível 2 e Nível 3

Os dados Nível 2 e Nível 3 são detalhes adicionais do pedido que você envia com um pagamento com cartão. Quando o portador usa um cartão empresarial, de compras ou corporativo, as bandeiras podem cobrar um interchange menor nas transações que os incluem. Importam principalmente em vendas B2B e para o governo nos Estados Unidos, e não têm efeito em cartões de consumo.

Nível	O que você envia	Uso típico
Nível 2	Referência do cliente (número do pedido de compra) e o valor do imposto sobre vendas	Qualquer venda com cartão comercial
Nível 3	Nível 2, mais cada item de linha (código do produto, quantidade, unidade de medida, preço unitário, código de commodity, desconto, imposto), frete e dados de destino	Bens físicos enviados a uma empresa ou órgão

A Therius repassa os dados. Se um pagamento realmente se qualifica para a tarifa menor é decisão da bandeira, do emissor e do seu adquirente, conforme o tipo de cartão, sua categoria de comerciante e os valores.

Ative com `commercialData`

Adicione um objeto commercialData na raiz de uma requisição de cartão POST /payment/purchase ou POST /payment/authorization, ao lado de lineItems. O detalhe de Nível 3 é lido de lineItems somente quando commercialData está presente.

Campo	Tipo	Descrição
`customerReference`	string	A referência do seu comprador para o pedido, como um número de pedido de compra. Até 25 caracteres ASCII imprimíveis, sem espaço inicial.
`taxAmount`	integer	Imposto total sobre vendas incluído no `amount` do pagamento, em unidades menores. Omita para usar a soma do `taxAmount` dos itens. Envie `0` para um pedido isento.
`freightAmount`	integer	Frete ou envio incluído no `amount` do pagamento, em unidades menores.
`shipFromPostalCode`	string	CEP/código postal de origem do envio, até 10 caracteres.
`destination`	object	Destino dos bens: `countryCode` (ISO 3166-1), `postalCode` (até 10 caracteres) e `stateOrProvince` (até 3 caracteres).
`orderDate`	string	Data do pedido de compra, `YYYY-MM-DD`.

Para o Nível 2, customerReference e o valor do imposto bastam. Para o Nível 3, adicione também os campos a seguir a cada item de lineItems:

Campo	Tipo	Descrição
`description`	string	O que é o item. Obrigatório.
`quantity`	integer	Unidades compradas, de 1 a 9999. Obrigatório.
`unitAmount`	integer	Preço de uma unidade em unidades menores, antes de desconto e imposto. Definir em um item faz a requisição ser tratada como Nível 3, então defina em todos os itens ou em nenhum.
`amount`	integer	O total da linha incluindo o imposto da linha. Deve ser igual a `unitAmount × quantity − discountAmount + taxAmount`.
`productCode`	string	Código do produto ou SKU, até 12 caracteres. Por padrão usa `id`.
`unitOfMeasure`	string	Código da unidade de medida, como `EA` (cada).
`commodityCode`	string	Código de commodity do item (UNSPSC, NAICS ou NAPCS), até 12 caracteres.
`discountAmount`	integer	Desconto aplicado à linha, em unidades menores.
`taxAmount`	integer	Imposto da linha, em unidades menores.

Os valores precisam fechar

A Therius confere a aritmética antes de chamar o provedor e retorna um 400 com a diferença exata se não fechar:

soma de (unitAmount × quantity − discountAmount) + imposto total + freightAmount = valor do pagamento

O amount de cada linha é seu total com imposto, como no exemplo abaixo.

{
  "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"
    }
  ]
}

Aqui as linhas líquidas somam 9,500 + 2,000 = 11,500, o imposto é 900 + 100 = 1,000 e o frete é 300, totalizando 12,800.

Se você enviar um taxAmount no nível do pedido e também valores de taxAmount por linha, eles precisam coincidir. Envie o imposto em apenas um nível se preferir.

Envie na captura

Se você autoriza primeiro e captura depois, pode enviar commercialData e lineItems no corpo de POST /payment/{id}/capture. Faça isso quando não enviou os dados com a autorização, ou quando o valor capturado ou as linhas diferem dela. Valem as mesmas regras, conferidas contra o amount da captura.

Sessões de checkout bloqueiam os dados

Ao criar uma sessão de checkout com POST /sdk/session, passe commercialData e lineItems ali. A sessão os bloqueia: um pagamento feito com o token da sessão sempre usa os valores bloqueados e ignora qualquer commercialData da chamada de pagamento, porque essa chamada pode vir do navegador. Um pagamento que o seu servidor faz com uma chave de API privada envia o próprio commercialData.

O que cada conexão envia

Conexão	Nível 2	Nível 3	Autorização e compra	Captura
Adyen	Sim	Sim	Sim	Sim
Stripe	Sim	Sim	Sim	Sim
NMI	Sim	Sim	Sim	Não

As demais conexões de cartão ignoram commercialData; o pagamento é processado normalmente. Cada adquirente é rígido quanto ao que aceita, e a Therius nunca recusa nem faz falhar um pagamento porque faltam dados aprimorados ou eles são rejeitados. Quando os dados ficam aquém, a Therius envia o que consegue:

Adyen exige customerReference e imposto nos dois níveis, imposto diferente de zero no Nível 2 e, em cada linha, productCode (até 12 caracteres), unitOfMeasure (até 3 caracteres) e commodityCode (até 12 caracteres). Se uma linha não tiver algum deles, a Therius envia somente o Nível 2. As descrições são cortadas em 26 caracteres.
Stripe usa o seu orderCode como referência do pedido e envia o imposto no nível do pedido. Código do produto, unidade de medida e código de commodity são opcionais para a requisição, mas necessários para receber tarifas de Nível 3. Se a versão de API da sua conta Stripe ainda não suportar payment line items, a Therius envia o pagamento sem os dados.
NMI aceita até 99 itens de linha. Com mais, a Therius envia apenas os campos no nível do pedido.

O que não está incluído

Os dados Nível 2/3 são para pagamentos com cartão. São ignorados em métodos de pagamento alternativos e carteiras que liquidam fora das bandeiras.
Estornos e cancelamentos não os carregam.
Campos de tarifas de importação, IVA/VAT e desconto no nível do pedido não são suportados. Coloque os descontos nos itens de linha.

Primeiros passos

Conceitos básicos

Guias

Webhooks

Assistente de IA

Plugins de e-commerce

Envie dados de cartão Nível 2 e Nível 3

Ative com `commercialData`

Os valores precisam fechar

Envie na captura

Sessões de checkout bloqueiam os dados

O que cada conexão envia

O que não está incluído

​Ative com commercialData

​Os valores precisam fechar

​Envie na captura

​Sessões de checkout bloqueiam os dados

​O que cada conexão envia

​O que não está incluído

Ative com `commercialData`

Os valores precisam fechar

Envie na captura

Sessões de checkout bloqueiam os dados

O que cada conexão envia

O que não está incluído