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

# Como funciona

> Camada de conformidade, ciclo de vida das transações e fluxo de fundos em todas as quatro variantes do Ramps.

## Templates primeiro

Cada transação de ramp roda sobre um Template. Você configura os Templates — as regras de um corredor — e as transações simplesmente seguem essas regras quando são iniciadas.

Pense em um Template como uma configuração de produto: "PIX-para-USDT, taxa de X%, mínimo de R$50, máximo de R$50.000." Uma vez configurado, cada transação nesse corredor herda essas regras automaticamente.

## Camada de conformidade — aplica-se às quatro variantes

Todas as quatro variantes do Ramps compartilham os mesmos requisitos de conformidade. Eles são executados automaticamente e não podem ser ignorados.

### Verificação de identidade

Cada transação exige o CPF (pessoa física) ou CNPJ (empresa) do beneficiário antes de prosseguir. O documento é validado quanto ao formato e depois consultado em uma base de dados de identidade brasileira.

* Se o documento for inválido ou não registrado, a transação é cancelada antes de qualquer movimentação de dinheiro.
* Documentos empresariais (CNPJ) passam por uma verificação adicional de identidade empresarial.
* Um cliente que já transacionou anteriormente é reconhecido pelo seu documento — a verificação é mais rápida em transações repetidas.

### Titularidade (variantes de onramp)

Em transações em que o cliente paga via PIX, a Noxpay verifica se o CPF do remetente PIX coincide com o documento coletado na verificação de identidade. Pagamentos de conta de terceiro são bloqueados e a transação é marcada como `UNCOMPLIANT`.

### Limite diário por beneficiário

O valor máximo em BRL equivalente que um único beneficiário (identificado por CPF/CNPJ) pode transacionar em todas as variantes de ramp em uma janela de 24 horas é **R\$ 50.000**. Transações que excedam esse limite são rejeitadas na iniciação.

### Faixas de KYC mensais por beneficiário

A Noxpay aplica um requisito progressivo de conformidade baseado no volume mensal acumulado em BRL por beneficiário:

| Volume mensal (por beneficiário) | Requisito                                                                                            |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Até R\$ 50.000                   | Verificação de identidade padrão (CPF/CNPJ)                                                          |
| R$ 50.001 – R$ 500.000           | KYC aprimorado: beneficiário deve enviar documentação financeira antes de a transação ser processada |
| Acima de R\$ 500.000             | Bloqueado — entre em contato com a Noxpay para discutir arranjos institucionais                      |

Quando um beneficiário ultrapassa o limite mensal de R\$ 50.000, a próxima transação é retida na etapa de verificação de identidade até que os documentos aprimorados sejam analisados. Você recebe uma notificação via webhook com o motivo da retenção e as instruções para o beneficiário.

***

## Ciclo de vida da transação

| Status            | O que significa                                                                                                    |
| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| `Created`         | Transação iniciada, aguardando ação do cliente                                                                     |
| `Pending`         | Verificação de identidade ou confirmação de depósito em andamento                                                  |
| `Processing`      | Conversão ou transferência PIX em andamento                                                                        |
| `Success`         | Concluído — cripto creditado, saldo debitado ou PIX entregue                                                       |
| `Partial Success` | Conversão concluída, mas entrega on-chain falhou (apenas Onramp para Endereço Externo) — cripto creditado no saldo |
| `Expired`         | Cliente não pagou ou depositou dentro da janela da cotação                                                         |
| `Failed`          | Erro de sistema                                                                                                    |
| `Cancelled`       | Verificação de identidade falhou ou documento inválido                                                             |
| `UNCOMPLIANT`     | CPF do remetente PIX não coincide com o documento do pré-KYC                                                       |

***

## Como os fundos fluem — por variante

**Onramp para Conta Global** — Cliente paga BRL via PIX → Noxpay converte → cripto creditado no seu saldo disponível da Noxpay. Nenhuma transação on-chain ocorre; o crédito é interno.

**Onramp para Endereço Externo** — Cliente paga BRL via PIX → Noxpay converte → cripto transmitido on-chain para o endereço de carteira especificado na criação da transação. Se a entrega on-chain falhar após uma conversão bem-sucedida, a transação liquida como `Partial Success` e o cripto é creditado no seu saldo.

**Offramp da Conta Global** — A Noxpay reserva o cripto necessário do seu saldo disponível na criação da cotação → converte para BRL → envia BRL via PIX ao beneficiário. Se a transação falhar ou expirar, o cripto reservado é liberado de volta ao disponível.

**Offramp de Endereço Externo** — Um endereço de depósito único é gerado para a transação. O pagador deposita cripto on-chain nesse endereço → Noxpay converte → BRL enviado via PIX ao beneficiário. Seu saldo Noxpay não é utilizado.

***

## Sua conta como backbone de liquidez (Offramp)

Para a variante padrão de Offramp, sua Conta Global é o que torna tudo possível. Quando uma transação é iniciada, a Noxpay move o cripto necessário do seu saldo **disponível** para **bloqueado**. Com a conversão e a entrega PIX bem-sucedidas, esse valor é debitado definitivamente. Se a transação falhar ou expirar, retorna ao disponível.

Mantenha sua Conta Global financiada com stablecoin suficiente para cobrir o seu volume esperado de offramp. Saldo insuficiente fará com que novas transações de offramp sejam rejeitadas.

<Tip>
  Monitore regularmente o saldo da sua Conta Global se operar fluxos de offramp de alto volume. Ficar sem saldo interromperá a capacidade de saque dos seus usuários.
</Tip>

***

## Dashboard

Transações de onramp aparecem em **Noxpay Infra → Onramps**. Transações de offramp aparecem em **Noxpay Infra → Offramps**. Cada linha exibe o ID da transação `NOX...`, o status, os valores em BRL e cripto, a moeda e o timestamp.

Transações liquidadas também aparecem em **Conta → Extrato** como lançamentos de débito ou crédito vinculados ao ID `NOX...` de origem.

***

## Webhooks

Um webhook é enviado a cada transição de etapa em todas as variantes. O payload segue o formato padrão da Noxpay e inclui valores, taxas, tarifas, o documento do beneficiário e — onde aplicável — hashes de transação on-chain. Configure a URL do webhook por Template ou por transação no momento da criação.
