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

> Reusable configurations that control how a ramp behaves — set up once, apply across every transaction.

## What is a Template?

A Template is a reusable configuration that controls how a payment flow behaves: which currency is settled, who pays the fees, and whether a portion of each payment is automatically split to a secondary address.

Every ramp — whether created via the dashboard or the API — is backed by a Template. The Template acts as the policy for that ramp: change the Template and all ramps using it immediately reflect the new settings.

Noxpay provides built-in default Templates for common use cases. You can create custom Templates to override fee behaviour, change the settlement currency, or configure split payments.

## Managing Templates

Templates are managed under **Noxpay Infra → Templates**.

<Note>
  Templates are only available to merchants with the **Infrastructure** product enabled on their account.
</Note>

## Creating a Template

When creating a Template you choose:

1. A **name** — your internal label, visible only in the dashboard. Must be unique within your account.
2. A **settlement currency** — the cryptocurrency your customers' BRL is converted into. This is locked after creation and cannot be changed.
3. **Fee settings** — who pays the Noxpay fee, whether the network fee is passed to the customer, and whether split payments are enabled.

The express options (USDT, USDC, BTC) pre-fill the currency and sensible fee defaults to get you started quickly.

## Fee Settings

### Noxpay fee

The Noxpay fee is a percentage of the transaction value charged on every successful payment. Your fee rate is determined by your tier — see **My Company → Fees** for the current rate and tier structure.

Who pays it is controlled by the `fee_behavior` setting on the Template:

| Setting              | What happens                                                                                                                                               |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Customer pays**    | The Noxpay fee is added on top of the quoted amount. The customer sees and pays the full amount including fees. You receive the full quoted crypto amount. |
| **Merchant absorbs** | The customer pays only the nominal amount. The Noxpay fee is deducted from the crypto amount you receive.                                                  |

**Example:** A customer pays R\$ 100. The Noxpay fee is 1%.

* Customer pays → customer pays R\$ 101, you receive 100 USDT worth of value.
* Merchant absorbs → customer pays R\$ 100, you receive \~99 USDT worth of value.

### Network fee

The network fee is the blockchain gas cost for on-chain delivery. It only applies to transactions where crypto is sent to an external wallet (Onramp to address). For standard onramps that credit your Noxpay balance, no network fee is incurred.

This setting is only active when `fee_behavior` is set to **Customer pays**.

| Setting                  | What happens                                                                                       |
| ------------------------ | -------------------------------------------------------------------------------------------------- |
| **Paid by customer**     | The blockchain gas cost is added to the customer's quoted amount.                                  |
| **Absorbed by merchant** | You cover the blockchain gas cost; it is deducted from the crypto amount credited to your balance. |

### Merchant fee (markup)

In addition to the Noxpay fee, you can add a custom markup — for example, to build margin into the checkout price. Merchant fee configuration is available on Template creation.

When `fee_behavior` is **Customer pays**, any merchant fee you configure is also added to the customer's amount. When **Merchant absorbs**, it is deducted from what you receive.

## Split Payments

Split payments are only available for crypto settlements (USDT, USDC, BTC, etc.). They are not available for fiat-settled Templates.

### How a split works

You configure two values:

* **Split percentage** (0.01–99.99%) — the share of the net crypto amount routed to the secondary address.
* **Flat fee** (optional) — a fixed crypto amount deducted first, then the remainder is split by percentage.

**Example:** A transaction settles 100 USDT. Split percentage = 10%, flat fee = 1 USDT, Noxpay fee = 1%.

1. Noxpay fee deducted: 100 − 1 = 99 USDT
2. Your flat fee deducted: 99 − 1 = 98 USDT
3. 10% of 98 + your flat fee of 1 USDT = 10.8 USDT → your Global Account
4. 90% of 98 = 88.2 USDT → sent to the external account at settlement

The split happens at settlement time. Both amounts appear on your statement as separate line items.

### Split destination

The revenue from the split stays in your Global Account. When sending onramp funds immediately to external addresses, the proceeds from the split remain in your account.

## Editing a Template

You can update a Template at any time from the dashboard. However, changes only apply to new transactions created after the update. Any transaction already in progress continues to use the rules that were active when it was created.

<Warning>
  Think carefully before changing fees or limits on a live Template. If your users have been told to expect certain rates and the Template changes mid-session, their experience will be inconsistent. Consider creating a new Template for the new configuration rather than editing an existing one.
</Warning>

## Disabling and re-enabling a Template

You can disable a Template without deleting it. A disabled Template will not accept new transactions — any attempt to create a transaction from it will be rejected. Transactions already in progress are not affected.

Re-enabling a Template makes it available for new transactions immediately.

## Applying different fee configs per use case

A common pattern is to create separate Templates for different products or customer segments:

| Template            | Currency      | Fee behavior     | Network fee      | Split          |
| ------------------- | ------------- | ---------------- | ---------------- | -------------- |
| `checkout-standard` | USDT (TRX)    | Customer pays    | Paid by customer | —              |
| `checkout-absorb`   | USDT (TRX)    | Merchant absorbs | —                | —              |
| `checkout-partner`  | USDT (TRX)    | Customer pays    | Paid by customer | 15% to partner |
| `btc-payments`      | BTC (Mainnet) | Customer pays    | Paid by customer | —              |

Each payment link or API call then specifies which Template to use. This lets you A/B test fee models, serve different customer segments differently, or run partner programmes — all without changing your integration code.