Skip to main content

​
Endpoint

POST /api/v1/invoices
Requires authentication. See Authentication.

​
Request

​
Body parameters

​
amount
string
required
The invoice amount as a decimal string. Up to 8 decimal places.Examples: "49.99", "1000", "0.00000001"
​
currency
string
required
The invoice currency. Typically a fiat currency code (USD, EUR, GBP) or a stablecoin (USDT, USDC).Your customer sees this amount and currency on the checkout page.
​
description
string
A human-readable description shown on the checkout page. For example: "Pro Plan - Monthly".
​
expiresInMinutes
number
How long the invoice stays open, in minutes. Minimum 1, maximum 525600 (1 year).If omitted, the invoice does not expire.
​
webhookUrl
string
The URL Settlx will POST events to for this invoice. Must be a publicly reachable URL. HTTPS is required in production environments.
​
metadata
object
Arbitrary key-value pairs you want to attach to this invoice. All values must be JSON-serializable.Metadata is returned as-is in every webhook event for this invoice under data.invoice.metadata. Use it to carry your internal IDs (order ID, customer ID, etc.) so you can correlate the payment to your system without a database lookup.
{
  "orderId": "order_123",
  "customerId": "cust_456"
}

​
Response

Returns 201 Created with the invoice object. 
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "merchantId": "9f8e7d6c-5b4a-3c2d-1e0f-ba9876543210",
    "amount": "49.99",
    "currency": "USD",
    "status": "pending",
    "description": "Pro Plan - Monthly",
    "expiresAt": null,
    "webhookUrl": "https://your-backend.com/webhooks/settlx",
    "paymentUrl": "https://api.settlx.io/checkout/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "createdAt": "2026-04-12T10:00:00.000Z",
    "updatedAt": "2026-04-12T10:00:00.000Z"
  }
}

​
Response fields

FieldTypeDescription
idstring (UUID)Unique invoice identifier
merchantIdstring (UUID)Your merchant account ID
amountstringInvoice amount
currencystringInvoice currency
statusstringAlways pending at creation
descriptionstring | nullDescription passed at creation
expiresAtstring | nullISO 8601 expiry timestamp, or null if no expiry
webhookUrlstring | nullWebhook URL for this invoice
paymentUrlstringHosted checkout URL — redirect your customer here
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 8601 last-updated timestamp
Redirect your customer to paymentUrl immediately after creation. On the checkout page they select their chain and token, and Settlx generates the deposit address.

​
Code examples

curl -X POST https://api.settlx.io/api/v1/invoices \
  -H "Authorization: Bearer pgk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "49.99",
    "currency": "USD",
    "description": "Pro Plan - Monthly",
    "webhookUrl": "https://your-backend.com/webhooks/settlx",
    "metadata": {
      "orderId": "order_123",
      "customerId": "cust_456"
    }
  }'

​
Errors

StatusMessageReason
400Amount must be greater than 0amount is zero, negative, or not a valid decimal
400Currency is requiredcurrency is missing or empty
400Expires in minutes must be greater than 0expiresInMinutes is zero or negative
401Missing or invalid Authorization headerAPI key not provided or malformed
401Invalid API keyKey not found or has been revoked
403Merchant account is not activeAccount is suspended or pending review