Todos os endpoints

URL base https://hub.stablezact.com. Coloque /api/v1 antes de cada caminho. Consulte Versionamento.

A maioria destes endpoints exige autenticação. Alguns não exigem, porque uma página de checkout no navegador do cliente tem de lhes aceder: /payments/public/{paymentId}, /payments/contract/{chainId}, /deposits/chains, /payments/cross-chain/sources, /currency/rates e /payments/health.

Nota

Esta é a lista completa do que existe. A maioria destes endpoints tem o detalhe completo de pedido e resposta na Referência da API; alguns ainda não têm, e estão listados aqui para que nada pareça estar em falta.

Pagamentos

Método	Caminho	Finalidade
POST	/payments/create	criar um pagamento
GET	/payments/{paymentId}	ler um pagamento, incluindo o progresso da transferência
GET	/payments/{paymentId}/status	o cliente já pagou
GET	/payments/status/{paymentId}	o mesmo, caminho alternativo
GET	/payments/public/{paymentId}	detalhe limitado, seguro para uma página de checkout
POST	/payments/process	submeter uma transação on-chain para verificação
POST	/payments/fail	marcar um pagamento como falhado, cancelado ou expirado
POST	/payments/verify-qr	verificar um pagamento iniciado por QR
GET	/payments/contract/{chainId}	endereço do contrato e ABI de uma rede
GET	/payments/merchant/list	os seus pagamentos, paginados (chave de API e segredo)
GET	/payments/merchant/stats	totais da sua conta (chave de API e segredo)
GET	/payments/health	estado do serviço

Repetir com segurança

A criação de pagamentos é idempotente. O servidor decide se um pedido é uma repetição usando o primeiro destes elementos que encontrar:

1. um cabeçalho de pedido Idempotency-Key, que é o mecanismo preferencial
2. um orderId no corpo
3. uma impressão digital (fingerprint) de todo o corpo do pedido

Assim, uma repetição idêntica é reconhecida mesmo que não envie nenhum dos dois, mas confiar nisso é frágil: altere um campo e passa a ser um novo pagamento. Envie um Idempotency-Key em tudo o que possa vir a repetir.

Idempotency-Key: order-1234-attempt-1

As chaves estão limitadas à sua conta e ao endpoint, e os caminhos com e sem versão partilham a mesma chave, por isso repetir em /api/payments/create depois de /api/v1/payments/create não cria um segundo pagamento.

Endereços de depósito

Um pagamento por endereço de depósito dá ao cliente um endereço único para onde enviar, e os fundos são reencaminhados para a sua wallet de liquidação.

Método	Caminho	Finalidade
POST	/deposits/create	criar um pagamento por endereço de depósito
GET	/deposits/status/{paymentId}	estado do depósito
GET	/deposits/balance/{paymentId}	o que chegou até agora
GET	/deposits/chains	redes que suportam endereços de depósito
POST	/deposits/refund-request/{paymentId}	indicar um endereço para um reembolso

Cross-chain

Para clientes que pagam a partir de uma rede diferente da faturada.

Método	Caminho	Finalidade
POST	/payments/cross-chain/create	criar um pagamento cross-chain
GET	/payments/cross-chain/sources	redes a partir das quais um cliente pode pagar
GET	/payments/cross-chain/status/{paymentId}	progresso na bridge

Redes e taxas de câmbio

Método	Caminho	Finalidade
GET	/networks	todas as redes suportadas
GET	/networks/payable	redes que neste momento podem aceitar pagamentos
GET	/networks/stablecoins	tokens suportados
GET	/networks/payable/stablecoins	tokens nas redes que aceitam pagamentos
GET	/currency/rates	taxas de câmbio usadas na conversão

Serviço

Método	Caminho	Finalidade
GET	/api/health	o serviço está ativo, sem versão
GET	/api/versions	versões suportadas, sem versão

Estes dois são a exceção à regra do /api/v1. Verificar se o serviço está ativo e perguntar que versões existem não pode exigir que já se conheça uma versão. /api/v1/health devolve 404 propositadamente.