Desenvolvedores

Integre pagamentos em stablecoins em uma requisição

A API é livre: sem conta, sem chave e sem cadastro. Informe a carteira do lojista — o smart contract liquida a taxa on-chain. Uma API key opcional conecta as vendas à sua dashboard.

Criar pedido Assinaturas SDK / modal Webhooks

Autenticação: nenhuma (e opcional)

Criar pedidos e assinaturas não exige conta nem chave. Informe a carteira do lojista no corpo da requisição — o contrato impõe a taxa e a divisão on-chain, e a custódia nunca é da Caedral.

A API key é opcional e serve a um único propósito: vincular as ordens à sua dashboard para métricas e histórico. Envie no header X-API-Key e o pedido usa a carteira salva da sua conta (quando o body não traz wallet).

Criar pedido e assinatura: sem autenticaçãoX-API-Key: vínculo de dados (opcional)

Criar pedido

POST/api/crypto/v1/orders

http

POST /api/crypto/v1/orders
Content-Type: application/json

{
  "amountBRL": 149.90,
  "description": "Plano Pro",
  "token": "USDT",
  "chain": "base",
  "webhookUrl": "https://seu-servidor.com/caedral-webhook",
  "wallet": {
    "address": "0xSEU-ENDERECO-EVM",
    "affiliates": [
      { "address": "0xENDERECO-AFILIADO", "bps": 1000 }
    ]
  }
}

json

201 Created

{
  "ref": "0xd2768883...b57a0fb4",
  "status": "pending",
  "amountBRL": 149.90,
  "cryptoAmount": "26.209438",
  "feeAmount": "0.262094",
  "netAmount": "25.947344",
  "token": "USDT",
  "chain": "base",
  "paymentUrl": "https://caedral.com/pay/0xd2768883...",
  "paymentUri": "ethereum:0xfde4C96c...@8453/transfer?...",
  "expiresAt": "2026-11-03T20:10:00.000Z",
  "statusUrl": "https://caedral.com/api/crypto/v1/orders/0xd2768883...",
  "webhook": {
    "url": "https://seu-servidor.com/caedral-webhook",
    "secret": "whsec_...",
    "note": "Recebe payment.confirmed assinado (HMAC-SHA256). Guarde o secret."
  }
}

Campo	Tipo	Descrição
amountBRL	number	Valor em reais (1–50000). Cotação travada por 15 minutos.
wallet.address	string	Endereço EVM do lojista (recebe o líquido).
wallet.affiliates	array?	Repasses em basis points (1–10000, soma ≤ 10000) liquidados na mesma transação.
webhookUrl	string?	URL https que recebe payment.confirmed assinado para ESTE pedido. O secret vem na resposta.
token	string?	USDT (padrão) ou USDC.
chain	string?	Rede: base (padrão). Multi-rede no roadmap.
description	string?	Descrição do produto (máx. 200 caracteres).
cartId	string?	Identificador do seu carrinho para conciliação.

Com API key: vendas vinculadas à dashboard

Gere a chave na dashboard (Chaves de API) e envie no header X-API-Key. Quando o body não traz wallet, o pedido usa a carteira salva da sua conta — e todas as ordens criadas com a chave ficam vinculadas às suas métricas.

A chave não é autorização: o pagamento funciona igual sem ela. Mesmo assim, trate-a como dado sensível — ela identifica suas métricas. Revelar ou rotacionar exige a sua senha.

bash

curl -X POST /api/crypto/v1/orders \
  -H "X-API-Key: $CAEDRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amountBRL": 149.90, "description": "Plano Pro" }'

Consultar status do pedido

A ref é a capability de consulta: qualquer um com a ref vê o status (público, como o pagamento em si). Status possíveis: pending → paid | expired (a rede aceita até o fim do grace de 45 min após a cotação).

bash

GET /api/crypto/v1/orders/{ref}

{
  "ref": "0xd2768883...",
  "status": "paid",
  "cryptoAmount": "26.209438",
  "feeAmount": "0.262094",
  "netAmount": "25.947344",
  "paidAt": "2026-11-03T20:05:30.000Z",
  "txHash": "0xdef456..."
}

Cobrança recorrente sem custódia e sem débito automático

Assinaturas recorrentes

POST/api/crypto/v1/subscriptions

Sem custódia não existe débito automático na carteira do cliente. A assinatura da Caedral gera uma COBRANÇA por ciclo: criamos o pedido, enviamos o link ao seu serviço por webhook e o cliente paga com a carteira dele. Confirmado o pagamento, o próximo ciclo é agendado automaticamente; expirado, a assinatura entra em atraso e o ciclo é reemitido em 24h.

O gerenciamento usa capability: a criação retorna subscriptionId + manageToken (guarde os dois — o token dá acesso ao status, aos ciclos e ao cancelamento).

http

POST /api/crypto/v1/subscriptions
Content-Type: application/json

{
  "amountBRL": 29.90,
  "customerRef": "cliente-001",
  "customerEmail": "cliente@email.com",
  "description": "Plano mensal",
  "monthly": true,
  "webhookUrl": "https://seu-servidor.com/sub-webhook",
  "wallet": { "address": "0xSEU-ENDERECO-EVM" }
}

json

201 Created

{
  "subscription": {
    "subscriptionId": "6aea52f5...",
    "status": "active",
    "customerRef": "cliente-001",
    "amountBRL": 29.90,
    "intervalDays": 30,
    "cycle": 1,
    "currentCharge": {
      "ref": "0x871fb998...",
      "status": "pending",
      "cryptoAmount": "5.446958",
      "paymentUrl": "https://caedral.com/pay/0x871fb998...",
      "expiresAt": "..."
    }
  },
  "manageToken": "b3fbb3b8..."
}

Campo	Tipo	Descrição
amountBRL	number	Valor por ciclo em reais (1–50000).
customerRef	string	Identificador do cliente no seu sistema (letras, números, - e _).
intervalDays	number?	Intervalo do ciclo em dias (1–365). Ou use monthly: true (30 dias).
monthly	boolean?	Atalho para intervalDays = 30.
customerEmail	string?	Email do cliente (opcional, para seus registros).
webhookUrl	string?	Recebe subscription.charge.created, subscription.paid, subscription.expired e subscription.canceled.
wallet	object	Carteira do lojista — ou X-API-Key para usar a salva na dashboard.

Gerenciamento

bash

# Status da assinatura + ciclo em aberto
GET /api/crypto/v1/subscriptions/{id}?manageToken={token}

# Histórico de ciclos
GET /api/crypto/v1/subscriptions/{id}/orders?manageToken={token}

# Cancelar
DELETE /api/crypto/v1/subscriptions/{id}?manageToken={token}

Eventos de webhook da assinatura

subscription.charge.createdUm novo ciclo foi gerado — contém ref e paymentUrl para cobrar o cliente.
subscription.paidO cliente pagou o ciclo (confirmado on-chain).
subscription.expiredO ciclo expirou sem pagamento — assinatura em atraso; novo ciclo reemitido em 24h.
subscription.canceledAssinatura cancelada.

Modal de pagamento embutível

SDK

Cole o script e poucas linhas: a Caedral renderiza o checkout completo (QR, carteira, status on-chain) dentro do seu site, com cores configuráveis para combinar com a sua marca.

html

<script src="https://caedral.com/checkout.js"></script>

<script>
  CaedralCheckout.open({
    merchantAddress: '0xSEU-ENDERECO-EVM',   // ou apiKey para vincular à dashboard
    amountBRL: 149.90,
    description: 'Plano Pro',
    theme: { brand: '#7C3AED', background: '#FFFFFF', radius: 14 },
    onSuccess: function (order) {
      // order.ref · order.txHash — pagamento confirmado on-chain
      liberarAcesso(order.ref);
    },
    onError: function (err) { console.error(err); }
  });
</script>

Opção	Descrição
theme.brand	Cor de destaque do checkout (botões e status).
theme.text	Cor do texto.
theme.background	Cor de fundo do modal.
theme.radius	Arredondamento em px.

Página hospedada (opcional)

Todo pedido e todo ciclo de assinatura recebem uma paymentUrl para a página de pagamento hospedada da Caedral: QR ERC-681 (MetaMask, Trust, Rabby e qualquer carteira), conexão direta de carteira via navegador, confirmação on-chain em tempo real.

Prefere integrar sem código? Redirecione o cliente para a paymentUrl — o fluxo é o mesmo do SDK.

Webhooks

Dois caminhos independentes: (1) webhookUrl por pedido ou por assinatura, na própria requisição de criação; (2) URLs fixas registradas na dashboard (Webhooks) para todas as ordens vinculadas à sua API key.

Todas as entregas são POST assinados com HMAC-SHA256 no header X-Caedral-Signature — verifique antes de liberar a entrega.

http

POST <sua-url>
X-Caedral-Event: payment.confirmed
X-Caedral-Signature: sha256=<HMAC-SHA256(body, secret)>

{
  "event": "payment.confirmed",
  "data": {
    "ref": "0xd2768883...",
    "amount": "26.209438 USDT",
    "txHash": "0xdef456..."
  },
  "timestamp": 1730000000
}

Verificação em Node.js: crypto.createHmac('sha256', secret).update(rawBody).digest('hex') — compare com o header usando o corpo bruto da requisição.

Gas: exato por transação, via receipts on-chain

Telemetria

O custo de rede é lido do receipt de cada transação (gasUsed × effectiveGasPrice) — valor exato por operação, por rede. A dashboard do lojista exibe o custo real por período: o gas do operator (registro e settlement direto, pago pela Caedral) e o gas pago pelo comprador no pay(), lido do txHash da venda.

Códigos de erro

HTTP	Significado
400	Parâmetros inválidos ou ausentes (ex.: wallet.address inválido)
401	API key obrigatória para este endpoint (listar ordens, métricas)
404	Pedido ou assinatura não encontrados (ref/inválida ou token errado)
429	Rate limit excedido — veja o header Retry-After
500	Erro interno do servidor

Precisa de ajuda? Fale com o time ou siga @trycaedral.

Base MainnetUSDT · USDCSem custódia