Invoices

Create and manage crypto payment invoices. Each invoice generates a unique deposit address.

POST/v1/invoices

Create a new payment invoice. Returns a checkout URL for the customer.

Request body

Field	Type	Required	Description
tokenId	integer	Yes	Token ID (get from /v1/public/tokens)
amountFiat	number	Yes	Amount in fiat currency
fiatCurrency	string	No	3-letter currency code, default USD
description	string	No	Invoice description, max 512 chars
merchantReference	string	No	Your internal reference ID
redirectUrl	string	No	URL to redirect after payment
cancelUrl	string	No	URL to redirect on cancellation
metadata	object	No	Arbitrary key/value pairs
ttlSeconds	integer	No	Invoice expiry in seconds

{
  "ok": true,
  "data": {
    "id": "clxyz123...",
    "publicId": "pub_abc123",
    "status": "pending",
    "checkoutUrl": "https://oxinpayments.com/checkout/pub_abc123",
    "amountFiat": "50.00",
    "fiatCurrency": "USD",
    "amountCrypto": "47.321000",
    "tokenSymbol": "USDT",
    "chainCode": "BSC",
    "depositAddress": "0xabc...",
    "expiresAt": "2026-06-21T13:00:00Z",
    "createdAt": "2026-06-21T12:00:00Z"
  }
}

GET/v1/invoices/:id

Retrieve a single invoice by ID.

GET/v1/invoices

List invoices with optional filters.

Query parameters

Param	Description
page	Page number (default 1)
limit	Results per page (max 100)
status	Filter: pending, completed, expired, cancelled
dateFrom	ISO date filter start
dateTo	ISO date filter end

Invoice statuses

Status	Description
pending	Awaiting payment
detecting	Transaction detected, awaiting confirmations
confirming	Confirmations in progress
completed	Payment confirmed and swept
expired	Customer did not pay within TTL
underpaid	Payment received but below required amount
cancelled	Manually cancelled