Skip to content
CryptonlyCryptonlyCryptonly

Invoice processing lifecycle

See Invoice statuses for the full status table and integration notes.

Create, listen, then settle

Section titled “Create, listen, then settle”
  1. Create a payment request through the API
  2. Redirect the customer to the payment link
  3. Listen for invoice.statusChanged webhook events
  4. Update your internal order or payment status only after the invoice reaches a settled payment status (paid, partially_paid, or overpaid)

Invoice lifecycle

Section titled “Invoice lifecycle”

  1. Merchant creates an invoice request

    An invoice can be created either:

    • through the admin panel
    • via the API (POST /invoice)

    The create response includes paymentPageUrl for the hosted checkout. Default invoice expiry is 24 hours unless you pass expiresInMinutes on create.

  2. Customer opens the link and selects a cryptocurrency

    The customer visits the hosted payment page and chooses which supported cryptocurrency to pay with.

    Each network option shows its network fee in the invoice’s fiat currency.

    Cryptonly assigns a unique deposit address, used for this payment attempt only, and locks the crypto amount: the invoice amount plus the network fee. The invoice status stays created — no additional invoice.statusChanged webhook is sent. If the customer changes currency, the invoice remains created throughout.

    The deposit payment link is valid for 30 minutes by default. A payment that arrives at this address within 4 hours after it expires — or after the customer switched to another currency — is still processed normally. See Late payments.

    The customer then sends that amount to the deposit address.

  3. Cryptonly waits for the required on-chain confirmation(s)

    Once the transfer is detected on-chain, Cryptonly waits for the required number of blockchain confirmations before proceeding. See Onchain confirmations for the number required per chain.

  4. Cryptonly performs an AML check

    After the required confirmations, Cryptonly screens the transaction. It can pass and continue, be flagged for review, or be held.

  5. If the AML check passes, the invoice is settled and the balance is credited

    Cryptonly settles the invoice with a payment-received status (paid, partially_paid, or overpaid) and credits the merchant’s internal balance (the received amount minus the network fee and commission).

  6. Cryptonly sends webhooks on status changes

    Cryptonly sends an invoice.statusChanged webhook on each invoice status transition.

Section titled “Related pages”
StatusesStatus table and late payments
Onchain confirmationsHow many confirmations each network requires
Fees and commissionsNetwork fee added on the payment page
WebhooksVerify invoice.statusChanged