Referência da API

Cobrança e pagamento

Faturas do cliente e o botão "Pagar". Seu app nunca marca uma fatura como paga: ela fica paga quando a FINAUTON confirma (resposta 200 do confirm ou evento obligation.paid).

GET/v1/users/:externalUserId/billingSituação de cobrança GET/v1/users/:externalUserId/obligationsFaturas POST/v1/users/:externalUserId/obligations/:obligationId/payment-instructionsPagar: gerar instrução POST/v1/users/:externalUserId/payments/:paymentId/confirmPagar: informar o txHash GET/v1/users/:externalUserId/payments/:paymentIdAcompanhar pagamento

GET/v1/users/:externalUserId/billing

Situação de cobrança

Tela do clienteVer no app modelo: Resultados e faturas ↗

status (ACTIVE, DUE, GRACE, SUSPENDED), regras do contrato (policy), taxa de builder, redes/tokens aceitos para pagamento, faturas em aberto e o que bloqueia novas entradas.

Ciclo: vence → carência de 24 h (entradas seguem) → suspenso (sem novas entradas; posições continuam protegidas) → pago e confirmado → reativado automaticamente (commercial.reactivated).

Parâmetros de caminho

externalUserIdstring (1–120)obrigatório
id do cliente no SEU sistema

Requisição

curl -X GET "$FIN_API/v1/users/cli-1001/billing" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET"

Resposta200

{
  "externalUserId": "cli-1001",
  "tenantId": "TENANT_A",
  "requestId": "req_muyn0wks_szbvrko4",
  "status": "DUE",
  "policy": {
    "contractId": "CTR-TENANT_A",
    "version": 1,
    "effectiveFrom": "2026-10-07T03:30:36.974Z",
    "suspended": false,
    "subscriptionMonthlyUsd": 30,
    "subscriptionProviders": [
      "BINANCE"
    ],
    "currency": "USDT",
    "performanceFeePercent": 0.2,
    "performancePeriod": "MONTHLY",
    "carryPolicy": "CARRY",
    "dueDays": 3,
    "graceHours": 24
  },
  "builder": {
    "source": "CONTRACT",
    "version": 1,
    "feeTenthsBps": 10
  },
  "payment": {
    "networks": [
      "arbitrum"
    ],
    "tokens": [
      "USDT",
      "USDC"
    ]
  },
  "openObligations": [
    {
      "obligationId": "6ac66741a85aa5764408ce17",
      "source": "MONTHLY_PERFORMANCE_FEE",
      "reference": "PS-6ac6663cf825906d709f2b09-HYPERLIQUID-2026-10-07",
      "status": "PENDING",
      "effectiveStatus": "PENDING",
      "amountUsd": 19.2,
      "currency": "USDT",
      "dueAt": "2026-11-04T00:00:00.000Z",
      "graceUntil": "2026-11-05T00:00:00.000Z",
      "blocksNewEntry": true,
      "providers": [
        "HYPERLIQUID"
      ],
      "settledAt": null
    }
  ],
  "newEntriesBlockedBy": []
}

GET/v1/users/:externalUserId/obligations

Faturas

Tela do clienteVer no app modelo: Resultados e faturas ↗

Todas as faturas (abertas e pagas). source: mensalidade ou performance fee; effectiveStatus: PENDING, GRACE, OVERDUE_AFTER_GRACE, PAID…

Parâmetros de caminho

externalUserIdstring (1–120)obrigatório
id do cliente no SEU sistema

Requisição

curl -X GET "$FIN_API/v1/users/cli-1001/obligations" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET"

Resposta200

{
  "externalUserId": "cli-1001",
  "tenantId": "TENANT_A",
  "requestId": "req_muyn0wmd_qbolj860",
  "obligations": [
    {
      "obligationId": "6ac66741a85aa5764408ce17",
      "source": "MONTHLY_PERFORMANCE_FEE",
      "reference": "PS-6ac6663cf825906d709f2b09-HYPERLIQUID-2026-10-07",
      "status": "PENDING",
      "effectiveStatus": "PENDING",
      "amountUsd": 19.2,
      "currency": "USDT",
      "dueAt": "2026-11-04T00:00:00.000Z",
      "graceUntil": "2026-11-05T00:00:00.000Z",
      "blocksNewEntry": true,
      "providers": [
        "HYPERLIQUID"
      ],
      "settledAt": null
    }
  ]
}

POST/v1/users/:externalUserId/obligations/:obligationId/payment-instructions

Pagar: gerar instrução

Tela do clienteIdempotency-Key obrigatórioVer no app modelo: Resultados e faturas ↗

Gera a instrução de pagamento de UMA fatura. EVM_TRANSFER (padrão): devolve o valor EXATO (tokenAmount em unidades mínimas — os centavos extras identificam o pagamento), rede, token, destinatário e validade; o cliente transfere pela carteira dele. HYPERLIQUID_USD_SEND: devolve um paymentUrl (página FINAUTON, uso único, 15 min) onde o cliente assina o usdSend com a carteira principal.

HYPERLIQUID_USD_SEND só fica disponível depois da validação REAL (antes disso a API pode responder RECIPIENT_NOT_CONFIGURED). Corpo: { "method": "HYPERLIQUID_USD_SEND", "returnUrl": "https://…" }.

Seu app não move fundos: só mostra a instrução.

Parâmetros de caminho

externalUserIdstring (1–120)obrigatório
id do cliente no SEU sistema
obligationIdstringobrigatório
da fatura

Corpo (JSON)

methodEVM_TRANSFER | HYPERLIQUID_USD_SENDopcional
padrão EVM_TRANSFER
networkIdstringcondicional
EVM: uma de billing.payment.networks (ex.: arbitrum)
tokenUSDT | USDCcondicional
EVM: um de billing.payment.tokens
payerAddress0x… (40 hex)condicional
EVM: carteira de onde o cliente vai pagar
returnUrlstring httpsopcional
HYPERLIQUID_USD_SEND: botão de volta

Erros comuns

400NETWORK_NOT_ENABLEDrede não aceita
400TOKEN_NOT_SUPPORTEDtoken não aceito
400INVALID_PAYERendereço inválido
409OBLIGATION_NOT_OPENfatura já paga/dispensada
400RECIPIENT_NOT_CONFIGUREDrecebedor FINAUTON não configurado

Requisição

curl -X POST "$FIN_API/v1/users/cli-1001/obligations/6ac66741a85aa5764408ce17/payment-instructions" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET" \
  -H "Idempotency-Key: payment-instructions-cli-1001-$(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
    "method": "EVM_TRANSFER",
    "networkId": "arbitrum",
    "token": "USDT",
    "payerAddress": "0x1111111111111111111111111111111111111111"
  }'

Resposta201

{
  "externalUserId": "cli-1001",
  "tenantId": "TENANT_A",
  "requestId": "req_muyn3xmg_0p74dpzr",
  "payment": {
    "paymentId": "6ac6be5191c7c1927cc1bb30",
    "obligationId": "6ac66741a85aa5764408ce17",
    "method": "EVM_TRANSFER",
    "status": "PENDING",
    "amountUsd": 19.2,
    "tokenSymbol": "USDT",
    "tokenAddress": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
    "tokenDecimals": 6,
    "tokenAmount": "19208526",
    "networkId": "arbitrum",
    "recipient": "0x<carteira recebedora FINAUTON>",
    "receiverVersion": 1,
    "payerAddress": "0x1111111111111111111111111111111111111111",
    "txHash": null,
    "expiresAt": "2026-10-07T22:19:04.981Z",
    "confirmedAt": null,
    "review": null,
    "overpaidTokenAmount": null,
    "failureReason": null
  },
  "instructions": "Envie EXATAMENTE 19208526 unidades mínimas (6 decimais) de USDT na rede arbitrum, a partir de 0x1111…1111, para 0x<carteira recebedora FINAUTON>, antes de 2026-10-07T22:19:04.981Z."
}

POST/v1/users/:externalUserId/payments/:paymentId/confirm

Pagar: informar o txHash

Tela do clienteIdempotency-Key obrigatórioVer no app modelo: Resultados e faturas ↗

O FINAUTON verifica ON-CHAIN (rede, token, destinatário, pagador, valor, confirmações). 200 = confirmado e fatura paga. 202 = ainda não (veja code); pode reenviar o MESMO txHash depois — nunca credita duas vezes.

code no 202: PAYMENT_AWAITING_CONFIRMATIONS (aguarde), PAYMENT_UNDERPAID (valor abaixo: não creditado), PAYMENT_WRONG_SENDER, PAYMENT_WRONG_TOKEN_OR_RECIPIENT, PAYMENT_WRONG_NETWORK, PAYMENT_TX_NOT_FOUND…

Parâmetros de caminho

externalUserIdstring (1–120)obrigatório
id do cliente no SEU sistema
paymentIdstringobrigatório
da instrução

Corpo (JSON)

txHash0x + 64 hexobrigatório
hash da transferência

Erros comuns

409TX_ALREADY_USEDa transação já pagou outra fatura
409PAYMENT_EXPIREDgere uma nova instrução
400INVALID_TX_HASHhash mal formado

Requisição

curl -X POST "$FIN_API/v1/users/cli-1001/payments/6ac6be5191c7c1927cc1bb30/confirm" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET" \
  -H "Idempotency-Key: payment-confirm-cli-1001-$(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
    "txHash": "0x<hash da transferência (64 hex)>"
  }'

Resposta202

{
  "externalUserId": "cli-1001",
  "tenantId": "TENANT_A",
  "requestId": "req_muyn3xu7_cfzfdo47",
  "payment": {
    "paymentId": "6ac6be5191c7c1927cc1bb30",
    "obligationId": "6ac66741a85aa5764408ce17",
    "method": "EVM_TRANSFER",
    "status": "SUBMITTED",
    "amountUsd": 19.2,
    "tokenSymbol": "USDT",
    "tokenAddress": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
    "tokenDecimals": 6,
    "tokenAmount": "19208526",
    "networkId": "arbitrum",
    "recipient": "0x<carteira recebedora FINAUTON>",
    "receiverVersion": 1,
    "payerAddress": "0x1111111111111111111111111111111111111111",
    "txHash": null,
    "expiresAt": "2026-10-07T22:19:04.981Z",
    "confirmedAt": null,
    "review": null,
    "overpaidTokenAmount": null,
    "failureReason": "PAYMENT_WRONG_NETWORK: Transação ainda não encontrada na rede. Aguarde e tente de novo."
  },
  "credited": false,
  "code": "PAYMENT_WRONG_NETWORK",
  "message": "Transação ainda não encontrada na rede. Aguarde e tente de novo."
}

GET/v1/users/:externalUserId/payments/:paymentId

Acompanhar pagamento

Tela do cliente

Estado do pagamento: PENDING, SUBMITTED, CONFIRMED… (mesmo objeto payment).

Parâmetros de caminho

externalUserIdstring (1–120)obrigatório
id do cliente no SEU sistema
paymentIdstringobrigatório
da instrução

Requisição

curl -X GET "$FIN_API/v1/users/cli-1001/payments/6ac6be5191c7c1927cc1bb30" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET"

Resposta200

{
  "externalUserId": "cli-1001",
  "tenantId": "TENANT_A",
  "requestId": "req_muyn3xrw_vvxdqlvc",
  "payment": {
    "paymentId": "6ac6be5191c7c1927cc1bb30",
    "obligationId": "6ac66741a85aa5764408ce17",
    "method": "EVM_TRANSFER",
    "status": "PENDING",
    "amountUsd": 19.2,
    "tokenSymbol": "USDT",
    "tokenAddress": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
    "tokenDecimals": 6,
    "tokenAmount": "19208526",
    "networkId": "arbitrum",
    "recipient": "0x<carteira recebedora FINAUTON>",
    "receiverVersion": 1,
    "payerAddress": "0x1111111111111111111111111111111111111111",
    "txHash": null,
    "expiresAt": "2026-10-07T22:19:04.981Z",
    "confirmedAt": null,
    "review": null,
    "overpaidTokenAmount": null,
    "failureReason": null
  }
}