Referência da API · v1

Documentação

API REST pra criar pedidos em cripto, consultar status e receber webhooks assinados. Base: https://api.comcripto.com/v1

Introdução

A ComCripto é um gateway não-custodial. Cada pedido gera um endereço determinístico (CREATE2) na rede escolhida — os fundos vão direto pro recebedor, com split on-chain da taxa da plataforma. Você integra em três passos: criar, consultar e receber o webhook.

Autenticação

As requisições autenticadas usam a chave do merchant no header x-api-key. Sem a chave, o pedido cai no merchant padrão. Chave inválida retorna 401.

# header de autenticação (opcional — ausente = merchant padrão)
x-api-key: cmk_…

Criar pedido

POST/v1/orders

Cria um pedido e retorna o endereço único de pagamento (CREATE2) + a URI EIP-681 pra carteira. O checkout hospedado fica em checkout.comcripto.com/<code>.

Parâmetro	Tipo	Descrição
amountBrlobrigatório	number	Valor do pedido em BRL.
chainKeyobrigatório	string	ethereum · polygon · base · arbitrum · bsc · arc
tokenSymbolobrigatório	string	USDC · USDT · nativo da rede (na Arc, só USDC — o gás da rede também é USDC, o cliente paga só o valor do pedido)
amountCryptoobrigatório	string	Valor exato no token (ex.: "9.20").
productNameobrigatório	string	Nome do produto/plano.
customerNameobrigatório	string	Nome do cliente.
externalRef	string	Sua referência (ecoada no webhook).
customerEmail	string	Opcional. E-mail do cliente pro recibo (enviado só quando o pagamento confirmar). O cliente também pode informá-lo no checkout.

RequisiçãocURL

curl -X POST https://api.comcripto.com/v1/orders \
  -H "x-api-key: cmk_…" \
  -H "content-type: application/json" \
  -d '{
    "amountBrl": 49.90,
    "chainKey": "polygon",
    "tokenSymbol": "USDC",
    "amountCrypto": "9.20",
    "productName": "Plano Pro",
    "customerName": "Fulano",
    "externalRef": "pedido-123"
  }'

Resposta200 OK

{ "order": {
  "code": "ABC123XY",
  "protocolo": "CC-ABC123XY",
  "status": "pending",
  "chainKey": "polygon",
  "tokenSymbol": "USDC",
  "amountCrypto": "9.20",
  "paymentAddress": "0x9509a1c4…9fA9",
  "paymentUri": "ethereum:0x…@137/transfer?address=0x…&uint256=9200000",
  "expiresAt": 1782692040723
} }

Consultar pedido

GET/v1/orders?code=<code>

Retorna o estado atual do pedido. Útil como backup do webhook (polling com backoff).

{ "order": {
  "code": "ABC123XY",
  "protocolo": "CC-ABC123XY",
  "status": "paid",
  "txHash": "0x95…9fA9",
  "forwarderTxHash": "0xde…f01",
  "paidAt": 1782692100000
} }

Status: pending → detected → paid (ou expired / failed).

Protocolo. Todo pedido tem um protocolo (CC- + o code) — o código que o cliente vê no checkout e no recibo. Com ele, o cliente consulta o status em comcripto.com/consulta (público, sem login; mostra status, valor, rede e hash da transação — nunca dados pessoais nem da loja). Peça ao seu cliente que guarde o protocolo pro suporte.

Webhooks

Quando o pagamento confirma (split on-chain feito), enviamos order.paid pro webhook_url do seu merchant, assinado com HMAC-SHA256 no header x-comcripto-signature. Valide a assinatura e RE-CONSULTE o status antes de creditar — não confie no corpo cegamente.

Payloadorder.paid

{
  "event": "order.paid",
  "code": "ABC123XY",
  "protocolo": "CC-ABC123XY",
  "externalRef": "pedido-123",
  "status": "paid",
  "txHash": "0x95…9fA9",
  "forwarderTxHash": "0xde…f01",
  "paidAt": 1782692100000
}

VerificaçãoNode.js

const sig = crypto
  .createHmac("sha256", WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");
if (sig !== req.headers["x-comcripto-signature"])
  return res.status(401).end();

Códigos de erro

Código	Slug	Descrição
400	validation	Campos faltando ou inválidos.
401	api key inválida	x-api-key não corresponde a um merchant ativo.
404	not found	Pedido inexistente.
500	erro ao criar	Falha interna (ex.: rede sem contrato).