Invoices

An invoice asks a buyer for a USD amount, paid in USDT or USDC on one network. Each invoice gets its own deposit address, so a payment is matched to its invoice by the address it was sent to.

Create an invoice

POST /api/v1/crypto/invoices — permission crypto-invoices:create, header Idempotency-Key required (see Idempotency).

There are two ways to create one:

• Fixed network and token. Send network and token. The invoice is PENDING immediately and the response carries deposit_address, total and payment_uri.
• Buyer chooses. Omit both. The invoice takes the environment of your API key; with a legacy key, send mode to choose it: Sandbox (mode: "test" in the API) or Live ("live"). The invoice is AWAITING_SELECTION; the buyer picks a network and token on the hosted checkout, which assigns the address then.

The smallest valid requests:

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

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

A complete request, with a seller, a partner share and a 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" }
  }'

Request fields

How fee_payer, markup_percent and splits turn into amounts is explained, with a worked example, in Ledger and splits. Accounts named in merchant and splits must exist; an unknown reference is a 422 on that field.

The invoice object

201 Created returns the invoice. A replay of the same Idempotency-Key returns it with 200.

Statuses

The full lifecycle diagram is in the Overview.

Retrieve an invoice

GET /api/v1/crypto/invoices/{id} — permission crypto-invoices:read.

Returns the invoice object plus:

List invoices

GET /api/v1/crypto/invoices — permission crypto-invoices:read.

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

The response is { "items": [...], "next_cursor": "..." }, newest first.

Void an invoice

POST /api/v1/crypto/invoices/{id}/void — permission crypto-invoices:update. No body.

Voiding moves an AWAITING_SELECTION or PENDING invoice to CANCELLED and returns it. Any other status answers 409 CONFLICT: once a payment is detected, the invoice can no longer be voided. Voiding sends no webhook.

If the buyer pays a cancelled invoice anyway, the money is not credited to the seller; it is held for the buyer as a LATE_PAYMENT refund.

Quote

POST /api/v1/crypto/quote — permission crypto-invoices:read. Computes the same breakdown an invoice would get, without creating anything.

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

network and token are required; fee_payer, markup_percent, merchant and splits are optional and default as on an invoice. The response:

{
  "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" }]
}

The hosted checkout

Send the buyer to pay_url (https://aliquot.cc/pay/{id}). The page needs nothing else from you.

• Network selection. For an AWAITING_SELECTION invoice, the buyer first picks one of the network and token pairs available in the invoice's environment. Picking assigns the deposit address, computes total for that token, and restarts the payment window: the buyer gets the full expires_in_minutes from that moment. A pair cannot be changed once picked.
• Paying. The buyer sees the exact amount, the address and a QR code (the EIP-681 payment_uri), and can pay from a browser wallet with one button, which switches the wallet to the right network first.
• Live status. The page follows the invoice as it moves through DETECTED, with a confirmation count, to PAID, and then shows a receipt, with the payment link's fulfilment when there is one. If the buyer underpays, the page asks for the rest; if the invoice expires or a refund is held, the page says so.

The checkout is built on public endpoints you can also call to build your own payment page:

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}`);
});

Anyone with the invoice ID can open its checkout, so do not treat the ID as a secret, and never fulfil an order from what a browser reports. Fulfil from the invoice.paid webhook or from GET /api/v1/crypto/invoices/{id}.

Returning to your site

When the checkout sees the invoice reach PAID while the buyer has it open, it counts down five seconds and navigates to redirect_url; the buyer can choose to stay. A buyer who opens the page after the fact gets a link back instead, and so does a buyer whose receipt shows a payment link's fulfilment, so they do not miss it. Aliquot does not append anything to the URL, so put whatever you need to find the order in redirect_url itself, for example https://shop.example.com/orders/77310.

Arriving at redirect_url does not prove payment. Check the invoice status on your server.

Payment window

expires_in_minutes (default 30) is the payment window: how long the buyer has to send the money once a deposit address exists.

• Network and token sent at creation. The window starts at creation: expires_at is the creation time plus expires_in_minutes.
• The buyer picks the network. expires_at first bounds the choice: the buyer must pick a pair within expires_in_minutes of creation, or the invoice becomes EXPIRED. Picking moves expires_at to the moment of selection plus the same expires_in_minutes, so the buyer always gets the full window to pay, and the whole flow can take up to twice expires_in_minutes.

Invoices created from a payment link use the organization's default window (30 minutes) the same way. An invoice that is still PENDING or AWAITING_SELECTION at expires_at becomes EXPIRED; one that is UNDERPAID becomes EXPIRED_UNDERPAID. A DETECTED invoice never expires, because the buyer paid in time.