Skip to main content
Documentation for invoices: Overview, Fees, Create invoice, Cancel invoice, Callbacks.For new integrations, consider using payment requests instead.

Body

application/json
​
id
integer
required

Invoice ID.

​
foreign_id
string
required

The foreign_id you provided when creating the invoice.

​
type
enum<string>
required
Available options:
invoice
​
currency_received
object
required

The currency and amount received for the invoice so far, in the invoice currency, or in the convert_to currency for invoices with automatic conversion. The amount is 0 while nothing has been paid and for cancelled invoices. For partially paid invoices, including failed ones, it holds the part of the amount received.

​
transactions
(blockchain · object | internal · object | exchange · object)[]
required

Transactions related to the invoice. The transaction_type field shows what each entry is:

  • blockchain: an incoming transaction on the blockchain
  • internal: an incoming transaction for an off-chain payment, which is never sent to the blockchain
  • exchange: the conversion of the payment, present only for invoices with automatic conversion

An invoice can be paid with several transactions (installments), in which case all of them are listed. Once the full amount is received, the invoice is marked as confirmed.

​
fees
object[]
required

Fees charged for the invoice payment.

​
error
string
required

The reason the invoice failed. Empty string otherwise. Possible values:

  • Timer expired. User not paid.: the invoice expired before any payment was received
  • Timer expired. User paid less than requested.: the customer paid less than the required invoice amount before the invoice expired
  • Timer expired. Transactions were in status processing too long.: a payment was detected but remained in processing for too long without being finalized
  • Cancelled by customer.: the invoice was cancelled via /v2/invoices/{foreign_id}/cancel
​
status
enum<string>
required

Invoice status:

  • pending: the invoice has been created and is waiting for payment, or has been partially paid and is waiting for the remaining amount. Until the customer selects a payment currency, the callback has no crypto_address and currency_sent
  • confirmed: the invoice has been paid in full, with one or several transactions, and can be treated as completed on your side
  • processing: a payment transaction has been detected in the mempool but has not yet been finalized. Treat the invoice as pending until you receive the confirmed callback
  • failed: the invoice was not paid and will not be completed. Use the error field to determine the reason
Available options:
pending,
confirmed,
processing,
failed
​
fixed_at
integer | null
required

Unix time in seconds when the rate was fixed, that is, when the customer selected a payment currency. null until then, and for invoices cancelled via the API.

​
expires_at
integer | null
required

Unix time in seconds when the invoice expires. null for invoices cancelled via the API.

​
end_user_reference
string

The end_user_reference you provided when creating the invoice.

​
crypto_address
object

Details of the address the customer pays to. Absent until the customer selects a payment currency, and from invoices cancelled via the API.

​
currency_sent
object

The invoice amount in the payment currency. Absent until the customer selects a payment currency, and from invoices cancelled via the API.

Last modified on September 30, 2026