Skip to main content
POST
/
api
/
v1
/
invoices
curl -X POST https://api.settlx.io/api/v1/invoices \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "99.99",
    "currency": "USD",
    "description": "Order #1234",
    "expiresInMinutes": 15,
    "webhookUrl": "https://yoursite.com/webhooks/settlx",
    "metadata": {
      "orderId": "order_abc123"
    }
  }'

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "merchantId": "f9e8d7c6-b5a4-3210-9876-543210fedcba",
    "amount": "99.99",
    "currency": "USD",
    "status": "pending",
    "description": "Order #1234",
    "expiresAt": "2024-01-15T10:30:00.000Z",
    "webhookUrl": "https://yoursite.com/webhooks/settlx",
    "paymentUrl": "https://api.settlx.io/checkout/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T10:00:00.000Z"
  }
}

​
Create Invoice

Creates a new payment invoice. The invoice represents a payment request for a specified fiat amount. After creation, the customer selects a token and chain on the checkout page, which triggers address generation on-demand.

​
Request

​
amount
string
required
Invoice amount as a decimal string. Must be greater than 0.Example: "99.99"
​
currency
string
required
The fiat currency of the invoice. Supported: USD, EUR, GBP, etc.Example: "USD"
​
description
string
Optional human-readable description of the invoice.Example: "Order #1234 — 2x T-shirts"
​
expiresInMinutes
number
Time in minutes until the invoice expires. If omitted, defaults to 15 minutes. Must be between 1 and 525600 (1 year).Example: 15
​
webhookUrl
string
URL to receive webhook event notifications for this invoice. Must be a valid HTTPS URL. Overrides the default webhook URL set in merchant settings.Example: "https://yoursite.com/webhooks/settlx"
​
metadata
object
Arbitrary key-value pairs to store with the invoice. Useful for correlating with your internal order IDs.Example: { "orderId": "order_abc123", "userId": "user_456" }

​
Response

​
data
object
curl -X POST https://api.settlx.io/api/v1/invoices \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "99.99",
    "currency": "USD",
    "description": "Order #1234",
    "expiresInMinutes": 15,
    "webhookUrl": "https://yoursite.com/webhooks/settlx",
    "metadata": {
      "orderId": "order_abc123"
    }
  }'

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "merchantId": "f9e8d7c6-b5a4-3210-9876-543210fedcba",
    "amount": "99.99",
    "currency": "USD",
    "status": "pending",
    "description": "Order #1234",
    "expiresAt": "2024-01-15T10:30:00.000Z",
    "webhookUrl": "https://yoursite.com/webhooks/settlx",
    "paymentUrl": "https://api.settlx.io/checkout/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T10:00:00.000Z"
  }
}