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

# Templates

> Configurações reutilizáveis que controlam como um ramp se comporta — configure uma vez, aplique em todas as transações.

## O que é um Template?

Um Template é uma configuração reutilizável que controla como um fluxo de pagamento se comporta: qual moeda é liquidada, quem paga as tarifas e se uma parte de cada pagamento é automaticamente dividida para um endereço secundário.

Todo ramp — seja criado pelo dashboard ou via API — é baseado em um Template. O Template age como a política daquele ramp: altere o Template e todos os ramps que o utilizam refletem imediatamente as novas configurações.

A Noxpay oferece Templates padrão prontos para os casos de uso mais comuns. Você pode criar Templates personalizados para substituir o comportamento de tarifas, alterar a moeda de liquidação ou configurar pagamentos divididos.

## Gerenciando Templates

Os Templates são gerenciados em **Noxpay Infra → Templates**.

<Note>
  Os Templates estão disponíveis apenas para lojistas com o produto **Infrastructure** habilitado na conta.
</Note>

## Criando um Template

Ao criar um Template, você escolhe:

1. Um **nome** — seu rótulo interno, visível apenas no dashboard. Deve ser único dentro da sua conta.
2. Uma **moeda de liquidação** — a criptomoeda para a qual o BRL dos seus clientes é convertido. Este campo é bloqueado após a criação e não pode ser alterado.
3. **Configurações de tarifa** — quem paga a tarifa da Noxpay, se a taxa de rede é repassada ao cliente e se os pagamentos divididos estão habilitados.

As opções express (USDT, USDC, BTC) pré-preenchem a moeda e padrões de tarifa adequados para que você comece rapidamente.

## Configurações de Tarifa

### Tarifa Noxpay

A tarifa Noxpay é uma porcentagem do valor da transação cobrada em cada pagamento bem-sucedido. Sua taxa é determinada pelo seu tier — veja **My Company → Fees** para a taxa atual e a estrutura de tiers.

Quem paga é controlado pela configuração `fee_behavior` no Template:

| Configuração        | O que acontece                                                                                                                                    |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Cliente paga**    | A tarifa Noxpay é adicionada ao valor cotado. O cliente vê e paga o valor total incluindo as tarifas. Você recebe o valor total em cripto cotado. |
| **Lojista absorve** | O cliente paga apenas o valor nominal. A tarifa Noxpay é deduzida do valor em cripto que você recebe.                                             |

**Exemplo:** Um cliente paga R\$ 100. A tarifa Noxpay é de 1%.

* Cliente paga → cliente paga R\$ 101, você recebe o equivalente a 100 USDT.
* Lojista absorve → cliente paga R\$ 100, você recebe \~99 USDT.

### Taxa de rede

A taxa de rede é o custo de gas blockchain para a entrega on-chain. Aplica-se apenas a transações em que o cripto é enviado para uma carteira externa (Onramp para endereço). Para onramps padrão que creditam seu saldo Noxpay, nenhuma taxa de rede é cobrada.

Esta configuração só está ativa quando `fee_behavior` está definido como **Cliente paga**.

| Configuração               | O que acontece                                                                                     |
| -------------------------- | -------------------------------------------------------------------------------------------------- |
| **Pago pelo cliente**      | O custo de gas blockchain é adicionado ao valor cotado do cliente.                                 |
| **Absorvido pelo lojista** | Você arca com o custo de gas blockchain; ele é deduzido do valor em cripto creditado ao seu saldo. |

### Tarifa do lojista (markup)

Além da tarifa Noxpay, você pode adicionar um markup personalizado — por exemplo, para embutir margem no preço de checkout. A configuração de tarifa do lojista está disponível na criação do Template.

Quando `fee_behavior` é **Cliente paga**, qualquer tarifa do lojista configurada também é adicionada ao valor do cliente. Quando **Lojista absorve**, é deduzida do que você recebe.

## Pagamentos Divididos (Split)

Pagamentos divididos estão disponíveis apenas para liquidações em cripto (USDT, USDC, BTC, etc.). Não estão disponíveis para Templates com liquidação em fiat.

### Como funciona um split

Você configura dois valores:

* **Percentual de split** (0,01–99,99%) — a parcela do valor líquido em cripto direcionada ao endereço secundário.
* **Taxa fixa** (opcional) — um valor fixo em cripto deduzido primeiro; o restante é dividido pelo percentual.

**Exemplo:** Uma transação liquida 100 USDT. Percentual de split = 10%, taxa fixa = 1 USDT, tarifa Noxpay = 1%.

1. Tarifa Noxpay deduzida: 100 − 1 = 99 USDT
2. Sua taxa fixa deduzida: 99 − 1 = 98 USDT
3. 10% de 98 + sua taxa fixa de 1 USDT = 10,8 USDT → sua Conta Global
4. 90% de 98 = 88,2 USDT → enviado à conta externa na liquidação

O split ocorre no momento da liquidação. Ambos os valores aparecem no extrato como lançamentos separados.

### Destino do split

A receita do split permanece na sua Conta Global. Ao enviar fundos de onramp imediatamente para endereços externos, os valores provenientes do split permanecem na sua conta.

## Editando um Template

Você pode atualizar um Template a qualquer momento pelo dashboard. No entanto, as alterações só se aplicam a novas transações criadas após a atualização. Qualquer transação já em andamento continua usando as regras que estavam ativas quando foi criada.

<Warning>
  Pense bem antes de alterar tarifas ou limites em um Template ativo. Se seus usuários foram informados de certas taxas e o Template muda durante a sessão, a experiência deles será inconsistente. Considere criar um novo Template para a nova configuração em vez de editar um existente.
</Warning>

## Desabilitando e reabilitando um Template

Você pode desabilitar um Template sem excluí-lo. Um Template desabilitado não aceitará novas transações — qualquer tentativa de criar uma transação a partir dele será rejeitada. As transações já em andamento não são afetadas.

Reabilitar um Template o torna disponível para novas transações imediatamente.

## Aplicando diferentes configurações de tarifa por caso de uso

Um padrão comum é criar Templates separados para diferentes produtos ou segmentos de clientes:

| Template            | Moeda         | Comportamento de tarifa | Taxa de rede      | Split           |
| ------------------- | ------------- | ----------------------- | ----------------- | --------------- |
| `checkout-standard` | USDT (TRX)    | Cliente paga            | Pago pelo cliente | —               |
| `checkout-absorb`   | USDT (TRX)    | Lojista absorve         | —                 | —               |
| `checkout-partner`  | USDT (TRX)    | Cliente paga            | Pago pelo cliente | 15% ao parceiro |
| `btc-payments`      | BTC (Mainnet) | Cliente paga            | Pago pelo cliente | —               |

Cada link de pagamento ou chamada de API especifica qual Template usar. Isso permite testar modelos de tarifa, atender diferentes segmentos de clientes ou executar programas de parceiros — tudo sem alterar o código da sua integração.