Comece por aqui

Iniciação rápida

Faça sua primeira venda em três passos: crie a ordem, exiba o pagamento e acompanhe a liquidação.

Esta página percorre o caminho mais curto entre a integração e a primeira venda líquida na sua carteira. Você precisa de uma carteira compatível e de um sistema capaz de fazer chamadas HTTPS. Os valores abaixo são ilustrativos; substitua o endereço pela sua carteira.

Pré-requisitos

  • Uma carteira que recebe em stablecoins (o endereço do lojista);
  • Um backend capaz de fazer chamadas HTTPS;
  • Nenhuma conta na Caedral — a API é pública e sem autenticação.

Passo 1 — Crie a ordem

Atenção

A carteira do lojista é sempre explícita na criação da ordem — é para ela que o split on-chain liquida.

curl -X POST https://api.caedral.com/api/crypto/v1/orders \
  -H "Content-Type: application/json" \
  -d '{
    "amountBRL": 149.90,
    "cartId": "PED-1042",
    "wallet": { "address": "0x1111111111111111111111111111111111111111" },
    "token": "USDT",
    "chain": "base"
  }'

A resposta 201 traz a ordem formatada, com o valor em cripto já calculado a partir da cotação travada:

{
  "ref": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "amountBRL": 149.9,
  "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "chainParams": {
    "chainIdHex": "0x2105",
    "chainName": "Base",
    "rpcUrls": ["https://..."],
    "nativeSymbol": "ETH",
    "blockExplorerUrls": ["https://basescan.org"]
  },
  "feeBps": 100,
  "paymentUrl": "https://pay.caedral.com/pay/0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "qrCodeUrl": "https://api.caedral.com/api/crypto/v1/orders/0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/qr",
  "statusUrl": "https://api.caedral.com/api/crypto/v1/orders/0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "expiresAt": "2026-11-08T19:05:00.000Z"
}

Passo 2 — Exiba o pagamento

Você tem duas formas, use a que couber no seu checkout:

  • Página hospedada — redirecione o comprador para paymentUrl. Ela já contém o valor, o contador de expiração e o QR;
  • QR universal — renderize qrCodeUrl (imagem) dentro do seu próprio layout. O QR segue o padrão ERC-681 e depende da compatibilidade da carteira.

Passo 3 — Acompanhe a liquidação

  • Webhook — passe webhookUrl na criação da ordem e receba o evento payment.confirmed assinado com HMAC-SHA256;
  • Status — consulte statusUrl (GET /orders/{ref}) quando quiser;

Ao confirmar o pagamento, o contrato executa o split e a sua parte cai direto na carteira informada. Fim — não existe etapa de "saque" ou "liquidação posterior".

Dica

Sem token e sem chain, a API cria um payment intent com selectionRequired: true e o comprador escolhe rede e ativo no checkout — útil para carrinhos genéricos. Veja Criar ordem.