Skip to main content
Creates a hosted invoice. Creating an invoice does not provision a receiving address. The payer selects a currently eligible currency and network option on the returned payment_url.

Headers

string
required
Your active Vanryx API key. See API keys and authentication.
string
Use application/json. The examples send JSON request bodies.
string
Optional. 1 to 255 visible ASCII characters. See Idempotency.

Body parameters

string
required
Invoice price. Must be numeric and greater than zero. Send it as a JSON string to preserve decimal precision, for example "49.95".
string
default:"USD"
Fiat currency of the invoice price. If omitted or empty, defaults to USD. Maximum 16 characters. Must match an active configured fiat currency.
integer
default:"60"
Invoice lifetime in minutes. From 1 to 43200.
boolean
default:"false"
Whether the payer bears the service-fee gross-up under the Vanryx invoice rules.
number | string
default:"0"
Accepted range: 0 to 100.
string
URL that receives webhook callbacks for this invoice. Maximum 2,048 characters. Must use HTTP or HTTPS and resolve only to public IP addresses.
string
Maximum 2,048 characters. Must be a valid URL.
string
Valid email address. Maximum 255 characters.
string
Your order reference. Maximum 128 characters.
string
Maximum 500 characters.
string
Maximum 1,000 characters.

Unsupported fields and capabilities

Do not send allowed_assets, to_currency, or network. Invoice creation does not accept them and returns a validation error. You cannot select the crypto asset when you create an invoice: the payer chooses from the options on the hosted page.
The request schema accepts the boolean fields sandbox, mixed_payment, and auto_withdrawal, but these invoice capabilities are unavailable. If any of them is true, the request is rejected. Leave them out of your requests.

Idempotency

The Idempotency-Key header is optional.
  • If you reuse a key with equivalent normalized request data, Vanryx returns the original invoice response.
  • If you reuse a key with different request data, Vanryx returns HTTP 409 with code IDEMPOTENCY_KEY_REUSED.

Response

object
string
Result message.

Payment options

Send the payer to payment_url. The payer selects a currency and network on that page. Not every currency is available for every invoice. Eligible options depend on current configuration, Merchant account readiness, rate availability, and minimums. Existing invoice quotes are retained.

Errors

See Errors and integration notes.