Payment links

Um payment link é uma página pública com um título, um preço em USD e os pares de rede e token que você aceita. Compartilhe a URL dele em qualquer lugar. Cada vez que um comprador inicia um pagamento, o Aliquot cria uma nova fatura em AWAITING_SELECTION e envia o comprador para o hosted checkout dessa fatura, onde ele escolhe um dos pares aceitos.

Use um payment link quando o preço é fixo e você não precisa criar uma fatura por pedido a partir do seu servidor. Use faturas quando precisar de splits, do seu próprio ID de pedido ou de um valor por comprador.

Criar um link

POST /api/v1/crypto/payment-links — permissão crypto-links:create. Sem Idempotency-Key.

curl -X POST https://api.aliquot.cc/api/v1/crypto/payment-links \
  -H "Authorization: Bearer $ALIQUOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Halden Grotesk — Desktop license",
    "description": "Five desktop seats, OTF and TTF.",
    "amount": "49.00",
    "accepted_pairs": [
      { "network": "POLYGON_AMOY", "token": "USDC" },
      { "network": "BASE_SEPOLIA", "token": "USDC" }
    ],
    "merchant": "halden_type",
    "redirect_url": "https://shop.example.com/thanks"
  }'

Um link do Sandbox usa as redes de teste; um link cujos pares são todos de redes Live recebe pagamentos reais.

Entrega

A entrega (fulfilment) é o que o comprador recebe no comprovante do checkout quando a fatura está PAID ou OVERPAID:

• Nunca antes do pagamento. Em qualquer outro status, o fulfillment da visão pública é null; o payload não chega ao navegador.
• Fixa por fatura. A entrega é copiada para a fatura quando o comprador inicia o checkout. Editar o link muda o que os checkouts seguintes entregam, nunca o comprovante de uma fatura que já existe.
• Comprovante público. Qualquer pessoa com o ID da fatura pode abrir o comprovante, como o resto do checkout. Para algo que precisa ficar vinculado a um único comprador, use uma URL assinada que expire ou entregue a partir do seu webhook.
• Sem retorno automático. Um comprovante com entrega não faz a contagem regressiva para redirect_url; o comprador recebe um botão para voltar.

A visão pública (GET /api/v1/public/pay/{id} e o seu stream) a traz assim:

"fulfillment": { "type": "FILE_DOWNLOAD", "payload": "https://files.example.com/halden-grotesk.zip" }

Todos os webhooks invoice.* trazem payment_link_id, então seu handler de invoice.paid sabe de qual link o pagamento veio sem outra requisição.

O objeto link

201 Created devolve:

{
  "id": "plink_01JB7RZ4C2W8M6Q1N3H5T7V9XA",
  "slug": "k7m2q9x4hd",
  "url": "https://aliquot.cc/l/k7m2q9x4hd",
  "livemode": false,
  "title": "Halden Grotesk — Desktop license",
  "description": "Five desktop seats, OTF and TTF.",
  "amount": "49.00",
  "currency": "USD",
  "merchant": { "reference": "halden_type", "name": "Halden Type" },
  "accepted_pairs": [
    { "network": "POLYGON_AMOY", "token": "USDC" },
    { "network": "BASE_SEPOLIA", "token": "USDC" }
  ],
  "fee_payer": null,
  "markup_percent": null,
  "fulfillment_type": "NONE",
  "fulfillment_payload": null,
  "redirect_url": "https://shop.example.com/thanks",
  "active": true,
  "sales_count": 0,
  "created_at": "2026-10-27T14:00:00.000Z",
  "updated_at": "2026-10-27T14:00:00.000Z"
}

O Aliquot gera o slug; compartilhe a url. sales_count conta as faturas deste link que chegaram a PAID ou OVERPAID.

Listar, consultar e atualizar

Não há exclusão. Para tirar um link do ar, defina "active": false: a página dele responde 404 e ele não cria novas faturas. As faturas que ele já criou não são afetadas. As alterações valem para os checkouts iniciados depois delas.

O que um checkout cria

Quando um comprador inicia um pagamento em https://aliquot.cc/l/{slug}, a nova fatura recebe:

• o title, a description, o amount, o merchant e a redirect_url do link;
• o fee_payer e o markup_percent do link, ou os padrões da organização quando eles são null;
• nenhum splits, nenhum merchant_order_id, nenhum buyer_email e nenhum metadata;
• payment_link_id com o id do link, e uma cópia da entrega do link;
• o ambiente do link, e a janela de pagamento padrão da organização (30 minutos), que recomeça inteira quando o comprador escolhe um par.

Essas faturas se comportam como qualquer outra: aparecem em GET /api/v1/crypto/invoices e enviam os mesmos webhooks.

Endpoints públicos

A página do link usa dois endpoints sem autenticação, que você pode chamar para colocar um botão de pagamento na sua própria página:

allowed_pairs lista os pares aceitos que podem receber pagamentos neste momento.