Skip to main content
Vanryx sends JSON POST callbacks to the callback_url you supplied when you created the invoice or static address.

Events

The type field is Invoice or Static. Static Address callbacks also support transaction.failed. This event does not apply to invoices. There are no separate invoice.* lifecycle callbacks. Invoice progress is reported on the transaction events above, through the invoice fields described below.

Transaction confirmation vs invoice payment

transaction.confirmed means one transaction was confirmed. It does not mean the invoice is paid.Use fulfilled to decide whether an invoice is complete. A confirmed but underpaid transfer still sends event: transaction.confirmed and may report invoice_status: Underpaid with fulfilled: false.
An invoice can receive more than one transfer. Each transfer has its own transaction.pending and transaction.confirmed events, and a later transfer can carry the updated fulfilled outcome.

Common fields

These fields appear in both Static and Invoice callbacks.
string
transaction.pending or transaction.confirmed.
string
Static or Invoice.
string
Pending or Confirmed.
string | null
Saved value from the static address or invoice. null when not supplied.
string | null
Saved value from the static address or invoice. null when not supplied.
string | null
Saved value from the static address or invoice. null when not supplied.
object
The three transaction amount fields are JSON numbers. Timestamps are Unix seconds. A timestamp that has not been recorded is JSON null.

Invoice fields

Invoice callbacks add exactly these top-level fields. Static callbacks do not include them.
string
Invoice identifier from Create Invoice.
string
Invoice status, for example Processing, Paid, or Underpaid.
boolean
Persisted fulfillment outcome of the invoice. It is not implied by transaction confirmation.
string
Invoice price, as persisted on the invoice.
string
Fiat currency of the invoice price.
boolean
Value set when the invoice was created.
string
Value set when the invoice was created.
string
Currency of the payment option used for this transaction.
string
Network of the payment option used for this transaction.
string
Amount due, in payment_currency.
string
Finalized, on-time gross amount counted toward fulfillment, in payment_currency. This is not transaction.received_amount.
string
Remaining amount, in payment_currency.
string
Excess amount, in payment_currency.
integer | null
Unix time in seconds when the invoice was fulfilled, or null.
Invoice decimal fields are strings. For a legacy unquoted payment option, quote-dependent fields may be null.

Example payloads

Responding to callbacks

Return any HTTP 2xx status to acknowledge a callback. Vanryx records non-2xx responses and transport failures as failed deliveries. No callback retry schedule is documented.

Handle callbacks idempotently

Vanryx does not guarantee exactly one HTTP request per event. The same callback can be sent more than once.
1

Deduplicate

Store each callback by transaction identity plus event: transaction.tx_id and event. Ignore a combination you have already processed.
2

Credit transactions idempotently

Record each transaction once, even if its callback arrives again.
3

Link invoice events by track_id

Match invoice callbacks to your invoice record with track_id. Expect that one invoice can have more than one transfer.
4

Fulfill only on fulfilled: true

Do not fulfill an order based only on transaction.confirmed. Fulfill the order once, and only when the invoice callback reports fulfilled: true.

Security

Callbacks do not include a signature or authentication header. Treat a callback as a notification, not as proof of payment on its own. Check that each callback refers to an invoice or static address you created before you act on it.