Referência da API

Base URL: https://triapay.net. Requisições server-to-server autenticam com Authorization: Bearer <api_key>. Sessões de navegador usam o cookie definido por /auth/login mais um token CSRF de /auth/csrf.

Autenticação

Dois níveis de chave por conta:

Prefixo	Uso
pk_live_*	Produção. Não pode ser revelada após a criação. Rotacione para substituir.
pk_test_*	Sandbox. Visível no dashboard. Apenas endpoints de sandbox.

Rotacione chaves e webhook secrets na página Integration. A rotação exige email OTP.

Criar ordem

POST /api/v1/orders
Authorization: Bearer pk_live_...
Content-Type: application/json

{
  "invoiceId": 12345,
  "userId": 678,
  "baseAmount": "10.00",
  "currency": "USD",
  "chain": "bep20",
  "asset": "USDT",
  "idempotencyKey": "01HT8X1V...-uuid",
  "returnUrl": "https://shop.example.com/orders/12345"
}

Field	Tipo	Observações
invoiceId	int	Seu invoice id do DHRU.
userId	int	User id do DHRU para atribuição do crédito.
baseAmount	string	String decimal. Um pequeno sufixo é adicionado ao valor para crypto chains.
currency	string	Moeda de origem.
chain	enum	trc20 | bep20 | binance_pay. BEP20 e TRC20 também aceitam transferências internas (off-chain) da Binance para o mesmo endereço de depósito.
asset	enum	USDT | USDC. TRC20 aceita só USDT.
idempotencyKey	string	UUID. Requisições repetidas com o mesmo payload retornam a mesma ordem.
returnUrl	string	Destino do redirect após a ordem terminar.

Resposta

{
  "orderId": 4711,
  "checkoutToken": "ck_a8f3...",
  "checkoutUrl": "https://triapay.net/checkout/ck_a8f3...",
  "expectedAmount": "10.0001",
  "matchCode": 1,
  "expiresAt": "2026-05-08T05:30:00Z",
  "status": "pending"
}

Redirecione o cliente para checkoutUrl. Use expectedAmount como o valor exato que o cliente deve enviar.

Status da ordem

GET /api/v1/orders/{idempotencyKey}/status
Authorization: Bearer pk_live_...

{
  "orderId": 4711,
  "status": "credited",
  "txHash": "0xabc...",
  "matchedAmount": "10.0001",
  "creditedAt": "2026-05-08T05:18:42Z"
}

Os estados da ordem formam uma state machine black-box:

• pending — aguardando pagamento.
• matched — fundos recebidos, crédito em andamento.
• credited — sucesso terminal. Webhook confirmado.
• expired — terminal. O cliente não pagou a tempo.
• failed — terminal. A entrega do webhook esgotou as tentativas.
• overpaid — terminal. O cliente enviou mais do que o esperado. A ordem é creditada e marcada para revisão manual.

Chegadas tardias (liquidação da chain após expiresAt) não são creditadas automaticamente. Recupere-as em Admin → Orphan transactions.

Helpers de sandbox

Disponíveis somente com pk_test_*. Force estados terminais sem esperar a liquidação da chain:

POST /api/v1/sandbox/orders/{idempotencyKey}/force-match
POST /api/v1/sandbox/orders/{idempotencyKey}/force-credit
POST /api/v1/sandbox/orders/{idempotencyKey}/force-expire
POST /api/v1/sandbox/webhook/replay

Body vazio. Retorna a ordem atualizada. Webhooks de sandbox incluem X-Payment-Mode: sandbox; o plugin DHRU incluído corta esses sem creditar nenhuma fatura.

Checkout para o cliente

Autenticação somente por token. Usada pela página de checkout hospedada:

GET  /api/v1/checkout/{token}/status
GET  /api/v1/checkout/{token}/methods
POST /api/v1/checkout/{token}/select-method

Body de select-method: {"chain": "bep20", "asset": "USDT"}. Retorna a ordem com endereço de depósito, valor esperado, QR data URI e match code.

Erros

Envelope JSON; o status HTTP reflete a classe:

{ "error": "invalid_credentials", "code": "unauthorized" }

HTTP	code	Quando
400	validation_error	Payload em formato inválido, campos obrigatórios ausentes.
401	unauthorized	Bearer ou sessão ausente ou inválida.
403	forbidden	IP fora da allowlist, key live em endpoint somente sandbox.
404	not_found	Token expirado, idempotency key desconhecida.
409	conflict	Idempotency-key reutilizada com payload diferente.
429	rate_limited	Respeite o header Retry-After (segundos).
500	internal	Erro do servidor. Tente novamente com backoff.

Os rate limits são aplicados por conta. Respeite Retry-After a cada 429.

Idempotência

Toda requisição que muda estado exige um idempotencyKey. Repetir a mesma key com o mesmo payload retorna a ordem original. Repetir a mesma key com payload diferente retorna:

{ "error": "idempotency_payload_mismatch", "code": "conflict" }

Gere a key como um UUIDv4 por fatura e persista do seu lado para que retries após uma falha de rede não causem cobrança em dobro.

---

Precisa de mais?

Qualquer coisa além desta página está disponível sob acordo de parceria. Fale com a gente pelo WhatsApp na home.