> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vanryx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Invoice

> Create a hosted Vanryx invoice and get the payer-facing payment URL.

```text theme={null}
POST https://api.vanryx.com/api/v1/payment/invoice
```

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

**Merchant-API-Key** `string` *required*

Your active Vanryx API key. See [API keys and authentication](https://docs.vanryx.com/authentication.md).

**Content-Type** `string`

Use `application/json`. The examples send JSON request bodies.

**Idempotency-Key** `string`

Optional. 1 to 255 visible ASCII characters. See [Idempotency](#idempotency).

## Body parameters

**amount** `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"`.

**currency** `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.

**lifetime** `integer` (default: 60)

Invoice lifetime in minutes. From `1` to `43200`.

**fee\_paid\_by\_payer** `boolean` (default: false)

Whether the payer bears the service-fee gross-up under the Vanryx invoice rules.

**under\_paid\_coverage** `number | string` (default: 0)

Accepted range: `0` to `100`.

**callback\_url** `string`

URL that receives [webhook callbacks](https://docs.vanryx.com/webhooks.md) for this invoice. Maximum 2,048 characters. Must use HTTP or HTTPS and resolve only to public IP addresses.

**return\_url** `string`

Maximum 2,048 characters. Must be a valid URL.

**email** `string`

Valid email address. Maximum 255 characters.

**order\_id** `string`

Your order reference. Maximum 128 characters.

**thanks\_message** `string`

Maximum 500 characters.

**description** `string`

Maximum 1,000 characters.

### Unsupported fields and capabilities

> [!WARNING]
>
> 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

**data** `object`

**properties**

**track\_id** `string`

Invoice identifier. Webhook callbacks for this invoice include the same `track_id`.

**payment\_url** `string`

Payer-facing hosted payment page.

**status** `string`

Invoice status at creation, for example `Pending`.

**expired\_at** `integer`

Invoice expiry time.

**date** `integer`

Invoice creation time.

**message** `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

| HTTP status | When |
| - | - |
| `401` | `Missing merchant API Key` or `Invalid or inactive API Key`. |
| `409` | `IDEMPOTENCY_KEY_REUSED`: the `Idempotency-Key` was reused with different request data. |
| `422` | Field validation failed, including unsupported fields or an unavailable capability set to `true`. |
| `429` | The route limit of 10 requests per minute was exceeded. |
| `503` | `INVOICE_LINK_UNAVAILABLE`, `INVOICE_ID_UNAVAILABLE`, or `INVOICE_CREATION_UNAVAILABLE`. |

See [Errors and integration notes](https://docs.vanryx.com/errors.md).

```bash cURL theme={null}
curl --request POST \
  --url https://api.vanryx.com/api/v1/payment/invoice \
  --header 'Merchant-API-Key: <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": "49.95",
    "currency": "USD",
    "lifetime": 60,
    "order_id": "ORDER-2026-1042",
    "email": "buyer@example.com",
    "description": "Example order"
  }'
```

```bash cURL with Idempotency-Key theme={null}
curl --request POST \
  --url https://api.vanryx.com/api/v1/payment/invoice \
  --header 'Merchant-API-Key: <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-2026-1042-attempt-1' \
  --data '{
    "amount": "49.95",
    "currency": "USD",
    "lifetime": 60,
    "order_id": "ORDER-2026-1042",
    "email": "buyer@example.com",
    "description": "Example order"
  }'
```

```json 200 theme={null}
{
  "data": {
    "track_id": "Ab3dEf7Gh1Jk2LmN9Q",
    "payment_url": "https://app.vanryx.com/invoice/Ab3dEf7Gh1Jk2LmN9Q",
    "status": "Pending",
    "expired_at": 1795000000,
    "date": 1794996400
  },
  "message": "Operation completed successfully!"
}
```

```json 401 theme={null}
{
  "message": "Invalid or inactive API Key"
}
```

```json 422 (illustrative) theme={null}
{
  "message": "The given data was invalid.",
  "errors": {
    "amount": ["The amount field is required."]
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.