Limites por Nível de Confiança

O sistema de Nível de Confiança (Nível de Conformidade) controla quanto um remetente está autorizado a transacionar. Níveis mais altos exigem mais dados e documentos de KYC, mas desbloqueiam limites de transação maiores em três janelas de tempo móveis: 24 horas, 30 dias e 180 dias.

Verificando o Nível de Conformidade

Endpoint: GET /organizations/{tenant}/participants/{participantId}/complianceLevels
Autenticação: Nível de tenant (x-api-key)

curl --request GET \
  --url https://{FQDN}/organizations/$TENANT/participants/$SENDER_ID/complianceLevels \
  --header "x-api-key: $API_KEY"

Este endpoint retorna:

• O nível de conformidade atual do participante e seus limites
• O próximo nível disponível e seus campos obrigatórios
• Os campos que ainda faltam ao participante para atingir o próximo nível

Exemplo de Resposta

Um participante em LEVEL_0 (ainda não pode transacionar) com caminho de upgrade para LEVEL_1:

{
  "participantId": "48066496-9445-41b7-acbe-85e069a77cb7",
  "currentComplianceLevel": {
    "level": "LEVEL_0",
    "limits": {
      "oneDayLimit": { "amount": "0.00", "currency": "USD" },
      "thirtyDaysLimit": { "amount": "0.00", "currency": "USD" },
      "oneHundredAndEightyDaysLimit": { "amount": "0.00", "currency": "USD" }
    },
    "requiredFields": [],
    "perTransactionFields": []
  },
  "nextComplianceLevel": {
    "level": "LEVEL_1",
    "limits": {
      "oneDayLimit": { "amount": "2999.00", "currency": "USD" },
      "thirtyDaysLimit": { "amount": "6000.00", "currency": "USD" },
      "oneHundredAndEightyDaysLimit": { "amount": "9999.00", "currency": "USD" }
    },
    "requiredFields": [
      "firstName",
      "lastName",
      "phoneNumber",
      "residentialAddress"
    ],
    "perTransactionFields": []
  },
  "missingFieldsForNextComplianceLevel": [
    "phoneNumber",
    "residentialAddress"
  ]
}

Campos-chave:

• currentComplianceLevel — o nível para o qual o participante se qualifica neste momento (LEVEL_0 com limites zerados quando nenhum dado foi fornecido)
• nextComplianceLevel.requiredFields — tudo o que o próximo nível exige
• missingFieldsForNextComplianceLevel — o subconjunto que o participante ainda não forneceu — use esta lista para conduzir sua UI de onboarding progressivo

Visão Geral dos Níveis de Conformidade

Estes níveis são personalizáveis por tenant. Seus campos obrigatórios e limites específicos são definidos durante o processo de onboarding da Inyo e podem diferir dos padrões mostrados acima.

Verificando Limites de Transação e Uso

Para ver quanto do limite um remetente já utilizou:

Endpoint: GET /organizations/{tenant}/fx/participants/{participantId}/limits
Autenticação: Nível de agente (x-api-key + x-agent-id + x-agent-api-key)

curl --request GET \
  --url https://{FQDN}/organizations/$TENANT/fx/participants/$SENDER_ID/limits \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY"

Exemplo de Resposta:

{
  "oneDayLimit": {
    "limit": { "amount": "2999.00", "currency": "USD" },
    "used": { "amount": "500.00", "currency": "USD" },
    "available": { "amount": "2499.00", "currency": "USD" }
  },
  "thirtyDaysLimit": {
    "limit": { "amount": "6000.00", "currency": "USD" },
    "used": { "amount": "2959.99", "currency": "USD" },
    "available": { "amount": "3040.01", "currency": "USD" }
  },
  "oneHundredAndEightyDaysLimit": {
    "limit": { "amount": "9999.00", "currency": "USD" },
    "used": { "amount": "5000.00", "currency": "USD" },
    "available": { "amount": "4999.00", "currency": "USD" }
  }
}

Campos-chave:

• limit — Valor máximo para esta janela de tempo (do nível de conformidade atual do participante)
• used — Valor já consumido na janela móvel (apenas transações que contam para os limites — recusadas/canceladas não contam)
• available — Capacidade restante (limit - used)

Os limites reportados aqui permanecem sincronizados com GET /participants/{id}/complianceLevels — ambos os endpoints respondem com os mesmos números, e available é calculado com as mesmas regras que o validador de transações aplica.

Elevando o Nível de um Remetente

Para mover um remetente de um nível para o próximo:

1. Verifique o nível atual — GET /participants/{id}/complianceLevels
2. Identifique os campos faltantes — Consulte missingFieldsForNextComplianceLevel
3. Colete os dados — Atualize o perfil do remetente com os campos faltantes:
   • Use PATCH /people/{personId} para campos de perfil (SSN, occupation, etc.)
   • Use PUT /people/{personId}/address para atualizações de endereço
   • Use os endpoints de envio de documentos para documentos de identidade e origem dos fundos
4. Verifique o upgrade — Chame o endpoint de níveis de conformidade novamente para confirmar que o nível aumentou

          LEVEL_0                 LEVEL_1                 LEVEL_2                 LEVEL_3
     ┌──────────────┐       ┌──────────────┐       ┌──────────────┐       ┌──────────────┐
     │  Cannot      │  Add  │  Standard    │  Add  │  Enhanced    │  Add  │  Maximum     │
     │  transact    │──────▶│  limits      │──────▶│  limits      │──────▶│  limits      │
     │              │ name, │              │ SSN,  │              │ proof │              │
     │  $0 / $0 / $0│ addr, │  $X/$X/$X    │ docs, │  $X/$X/$X    │ of    │  $X/$X/$X    │
     └──────────────┘ phone └──────────────┘ occup └──────────────┘ funds └──────────────┘

Casos de Uso

• Onboarding progressivo — Comece com dados mínimos (Nível 1) e solicite mais apenas quando o usuário precisar de limites maiores.
• Avisos de limite — Mostre aos usuários a capacidade restante antes de iniciarem uma transação.
• Solicitações de upgrade — Quando uma transação exceder o limite atual, mostre exatamente quais campos estão faltando e oriente o usuário a completá-los.
• Dashboard de conformidade — Exiba uma barra de progresso visual mostrando o nível do usuário e o que é necessário para o próximo tier.

Acompanhando a Revisão de Documentos

Para mostrar aos usuários que seus documentos estão em análise, acompanhe o status de verificação por documento — veja Enviando Documentos — ou assine o webhook DocumentUpdatedEvents.

Documentação Interativa da API