Faturas

Uma fatura pede a um comprador um valor em USD, pago em USDT ou USDC em uma rede. Cada fatura recebe o seu próprio endereço de depósito, então um pagamento é associado à sua fatura pelo endereço para o qual foi enviado.

Criar uma fatura

POST /api/v1/crypto/invoices — permissão crypto-invoices:create, header Idempotency-Key obrigatório (veja Idempotência).

Há duas formas de criar uma:

• Rede e token fixos. Envie network e token. A fatura fica PENDING imediatamente e a resposta traz deposit_address, total e payment_uri.
• O comprador escolhe. Omita os dois. A fatura assume o ambiente da sua API key; com uma key legada, envie mode para escolhê-lo: Sandbox (mode: "test" na API) ou Live ("live"). A fatura fica AWAITING_SELECTION; o comprador escolhe uma rede e um token no hosted checkout, que atribui o endereço nesse momento.

As menores requisições válidas:

{ "amount": "49.00", "title": "Pro plan, 1 month", "network": "POLYGON_AMOY", "token": "USDC" }

{ "amount": "49.00", "title": "Pro plan, 1 month", "mode": "test" }

Uma requisição completa, com um vendedor, a participação de um parceiro e um markup:

curl -X POST https://api.aliquot.cc/api/v1/crypto/invoices \
  -H "Authorization: Bearer $ALIQUOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-77310" \
  -d '{
    "amount": "100.00",
    "network": "POLYGON_AMOY",
    "token": "USDC",
    "fee_payer": "CUSTOMER",
    "markup_percent": 2,
    "merchant": "halden_type",
    "splits": [{ "account": "kerning_weekly", "percent": 10 }],
    "title": "Halden Grotesk — Desktop license",
    "merchant_order_id": "order-77310",
    "buyer_email": "[email protected]",
    "redirect_url": "https://shop.example.com/orders/77310",
    "metadata": { "cart_id": "c_5521" }
  }'

Campos da requisição

Como fee_payer, markup_percent e splits se transformam em valores é explicado, com um exemplo calculado, em Ledger e splits. As contas indicadas em merchant e splits precisam existir; uma referência desconhecida resulta em 422 nesse campo.

O objeto fatura

201 Created devolve a fatura. Um replay da mesma Idempotency-Key a devolve com 200.

Status

O diagrama completo do ciclo de vida está na Visão geral.

Consultar uma fatura

GET /api/v1/crypto/invoices/{id} — permissão crypto-invoices:read.

Devolve o objeto fatura, mais:

Listar faturas

GET /api/v1/crypto/invoices — permissão crypto-invoices:read.

curl "https://api.aliquot.cc/api/v1/crypto/invoices?mode=test&q=order-77310" \
  -H "Authorization: Bearer $ALIQUOT_API_KEY"

A resposta é { "items": [...], "next_cursor": "..." }, das mais recentes para as mais antigas.

Anular uma fatura

POST /api/v1/crypto/invoices/{id}/void — permissão crypto-invoices:update. Sem corpo.

Anular move uma fatura AWAITING_SELECTION ou PENDING para CANCELLED e a devolve. Qualquer outro status responde 409 CONFLICT: depois que um pagamento é detectado, a fatura não pode mais ser anulada. A anulação não envia webhook.

Se o comprador pagar uma fatura cancelada mesmo assim, o dinheiro não é creditado ao vendedor; ele fica retido para o comprador como um reembolso LATE_PAYMENT.

Cotação

POST /api/v1/crypto/quote — permissão crypto-invoices:read. Calcula o mesmo detalhamento que uma fatura teria, sem criar nada.

{
  "amount": "100.00",
  "network": "POLYGON_AMOY",
  "token": "USDC",
  "fee_payer": "CUSTOMER",
  "markup_percent": 2,
  "merchant": "halden_type",
  "splits": [{ "account": "kerning_weekly", "percent": 10 }]
}

network e token são obrigatórios; fee_payer, markup_percent, merchant e splits são opcionais e têm os mesmos padrões de uma fatura. A resposta:

{
  "network": "POLYGON_AMOY",
  "token": "USDC",
  "decimals": 6,
  "fee_payer": "CUSTOMER",
  "base": "100.00",
  "platform_fee": "0.50",
  "markup": "2.00",
  "merchant_net": "90.00",
  "total": "102.50",
  "splits": [{ "account": "kerning_weekly", "percent": 10, "amount": "10.00" }]
}

O hosted checkout

Envie o comprador para pay_url (https://aliquot.cc/pay/{id}). A página não precisa de mais nada da sua parte.

• Escolha da rede. Em uma fatura AWAITING_SELECTION, o comprador primeiro escolhe um dos pares de rede e token disponíveis no ambiente da fatura. A escolha atribui o endereço de depósito, calcula total para esse token e reinicia a janela de pagamento: o comprador tem o expires_in_minutes inteiro a partir desse momento. Um par não pode ser trocado depois de escolhido.
• Pagamento. O comprador vê o valor exato, o endereço e um QR code (a payment_uri EIP-681), e pode pagar com uma wallet do navegador em um único botão, que antes troca a wallet para a rede certa.
• Status ao vivo. A página acompanha a fatura enquanto ela passa por DETECTED, com uma contagem de confirmações, até PAID, e então mostra um comprovante, com a entrega do payment link quando houver. Se o comprador pagar a menos, a página pede o restante; se a fatura expirar ou um reembolso ficar retido, a página informa isso.

O checkout é construído sobre endpoints públicos que você também pode chamar para montar a sua própria página de pagamento:

const source = new EventSource('https://api.aliquot.cc/api/v1/public/pay/inv_01JB7Q8M3X4K9TPZ2R6WVN5HDC/stream');
source.addEventListener('invoice', (e) => {
  const view = JSON.parse(e.data);
  console.log(view.status, `${view.confirmations}/${view.required_confirmations}`);
});

Qualquer pessoa com o ID da fatura pode abrir o checkout dela, então não trate o ID como um segredo, e nunca entregue um pedido com base no que um navegador informa. Entregue a partir do webhook invoice.paid ou de GET /api/v1/crypto/invoices/{id}.

Retorno ao seu site

Quando o checkout vê a fatura chegar a PAID enquanto o comprador está com ele aberto, ele faz uma contagem regressiva de cinco segundos e navega para redirect_url; o comprador pode optar por ficar. Um comprador que abre a página depois recebe um link de volta, e o mesmo acontece quando o comprovante mostra a entrega de um payment link, para que o comprador não a perca. O Aliquot não acrescenta nada à URL, então coloque em redirect_url tudo o que você precisa para encontrar o pedido, por exemplo https://shop.example.com/orders/77310.

Chegar a redirect_url não prova o pagamento. Verifique o status da fatura no seu servidor.

Janela de pagamento

expires_in_minutes (padrão 30) é a janela de pagamento: quanto tempo o comprador tem para enviar o dinheiro depois que existe um endereço de depósito.

• Rede e token enviados na criação. A janela começa na criação: expires_at é o momento da criação mais expires_in_minutes.
• O comprador escolhe a rede. Primeiro, expires_at limita a escolha: o comprador precisa escolher um par dentro de expires_in_minutes a partir da criação, ou a fatura passa a EXPIRED. Ao escolher, expires_at passa a ser o momento da escolha mais o mesmo expires_in_minutes, então o comprador sempre tem a janela inteira para pagar, e o fluxo todo pode levar até o dobro de expires_in_minutes.

Faturas criadas a partir de um payment link usam da mesma forma a janela padrão da organização (30 minutos). Uma fatura que ainda está PENDING ou AWAITING_SELECTION em expires_at passa a EXPIRED; uma que está UNDERPAID passa a EXPIRED_UNDERPAID. Uma fatura DETECTED nunca expira, porque o comprador pagou a tempo.