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

{
  "data": {
    "paymentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "address": "0xAbCdEf1234567890AbCdEf1234567890AbCdEf12",
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "cryptoAmount": "50.02000000",
    "cryptoCurrency": "USDT",
    "chain": "polygon",
    "fiatAmount": "49.99000000",
    "fiatCurrency": "USD",
    "exchangeRate": "1.00060",
    "status": "pending",
    "expiresAt": "2026-04-12T10:30:00.000Z",
    "createdAt": "2026-04-12T10:00:00.000Z"
  }
}
Creates an invoice and generates a deposit address in one request. The customer can start paying immediately — no second call needed. Use this instead of Create Invoice when you already know which chain and token the customer will pay with (e.g. your checkout UI lets them choose before you call the API).

​
Request

​
amount
string
required
Invoice amount as a decimal string. Must be greater than 0.Example: "49.99"
​
currency
string
required
Fiat currency of the invoice. Supported: USD, EUR, GBP, etc.Example: "USD"
​
chain
string
required
The chain the customer will pay on. See GET /api/v1/tokens for supported values.Examples: "polygon", "ethereum", "bsc", "tron", "bitcoin"
​
token
string
The token the customer will send. If omitted, the chain’s native currency is used.Examples: "USDT", "USDC", "ETH"
​
description
string
Optional human-readable description stored with the invoice.Example: "Order #1234 — 2x T-shirts"
​
expiresInMinutes
number
Minutes until the invoice expires. If omitted, defaults to the platform rate window (15 minutes). Cannot exceed the platform rate window — values above the cap are silently reduced to the maximum.Example: 15
​
webhookUrl
string
URL to receive webhook events for this payment. 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 stored with the invoice. Returned in every webhook event — use it to correlate with your internal order ID.Example: { "orderId": "order_abc123", "userId": "user_456" }

​
Response

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

{
  "data": {
    "paymentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "address": "0xAbCdEf1234567890AbCdEf1234567890AbCdEf12",
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "cryptoAmount": "50.02000000",
    "cryptoCurrency": "USDT",
    "chain": "polygon",
    "fiatAmount": "49.99000000",
    "fiatCurrency": "USD",
    "exchangeRate": "1.00060",
    "status": "pending",
    "expiresAt": "2026-04-12T10:30:00.000Z",
    "createdAt": "2026-04-12T10:00:00.000Z"
  }
}
The customer must send cryptoAmount of cryptoCurrency to address. A 1% tolerance is applied — amounts within 1% of the quoted value are accepted as full payment. Amounts below the tolerance threshold trigger partial payment handling.
Fulfill the order on invoice.settled — not invoice.confirmed. Confirmed means the chain accepted it; settled means funds have actually landed in your wallet.