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
An invoice can receive more than one transfer. Each transfer has its owntransaction.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. The three transaction amount fields are JSON numbers. Timestamps are Unix seconds. A timestamp that has not been recorded is JSONnull.
Invoice fields
Invoice callbacks add exactly these top-level fields. Static callbacks do not include them.Invoice identifier from Create Invoice.
Finalized, on-time gross amount counted toward fulfillment, in
payment_currency. This is not transaction.received_amount.null.
Example payloads
- Static: pending
- Static: confirmed
- Invoice: pending
- Invoice: confirmed and fulfilled
Responding to callbacks
Return any HTTP2xx 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.