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"
}
}'
const response = await fetch('https://api.settlx.io/api/v1/payments', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.SETTLX_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount: '49.99',
currency: 'USD',
chain: 'polygon',
token: 'USDT',
description: 'Order #1234',
expiresInMinutes: 30,
webhookUrl: `${process.env.BASE_URL}/webhooks/settlx`,
metadata: { orderId: 'order_abc123' },
}),
});
const { data } = await response.json();
// Show to your customer
console.log(data.address); // Deposit address
console.log(data.cryptoAmount); // Exact amount to send
console.log(data.qrCode); // Base64 QR code — render as <img>
import httpx
client = httpx.Client(headers={"Authorization": "Bearer pk_live_your_api_key"})
response = client.post("https://api.settlx.io/api/v1/payments", json={
"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 = response.json()["data"]
print(data["address"]) # Deposit address
print(data["cryptoAmount"]) # Exact amount to send
{
"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"
}
}
{
"error": "Bad Request",
"message": "Chain polygon is not supported or not enabled"
}
{
"error": "Unauthorized",
"message": "Invalid API key"
}
{
"error": "Forbidden",
"message": "Merchant account is not active"
}
Invoices
Create Payment
Create an invoice and generate a deposit address in a single call
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"
}
}'
const response = await fetch('https://api.settlx.io/api/v1/payments', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.SETTLX_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount: '49.99',
currency: 'USD',
chain: 'polygon',
token: 'USDT',
description: 'Order #1234',
expiresInMinutes: 30,
webhookUrl: `${process.env.BASE_URL}/webhooks/settlx`,
metadata: { orderId: 'order_abc123' },
}),
});
const { data } = await response.json();
// Show to your customer
console.log(data.address); // Deposit address
console.log(data.cryptoAmount); // Exact amount to send
console.log(data.qrCode); // Base64 QR code — render as <img>
import httpx
client = httpx.Client(headers={"Authorization": "Bearer pk_live_your_api_key"})
response = client.post("https://api.settlx.io/api/v1/payments", json={
"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 = response.json()["data"]
print(data["address"]) # Deposit address
print(data["cryptoAmount"]) # Exact amount to send
{
"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"
}
}
{
"error": "Bad Request",
"message": "Chain polygon is not supported or not enabled"
}
{
"error": "Unauthorized",
"message": "Invalid API key"
}
{
"error": "Forbidden",
"message": "Merchant account is not active"
}
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
string
required
Invoice amount as a decimal string. Must be greater than 0.Example:
"49.99"string
required
Fiat currency of the invoice. Supported:
USD, EUR, GBP, etc.Example: "USD"string
required
The chain the customer will pay on. See GET /api/v1/tokens for supported values.Examples:
"polygon", "ethereum", "bsc", "tron", "bitcoin"string
The token the customer will send. If omitted, the chain’s native currency is used.Examples:
"USDT", "USDC", "ETH"string
Optional human-readable description stored with the invoice.Example:
"Order #1234 — 2x T-shirts"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:
15string
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"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
object
Hide Payment object
Hide Payment object
string
Invoice UUID. Use this to correlate webhook events and to poll
GET /api/v1/invoices/:id/status.string
Deposit address to display to the customer. Do not reuse this address across invoices.
string
Base64-encoded PNG QR code of the deposit address. Render with
<img src={data.qrCode} />.string
Exact amount the customer must send, with 8 decimal places (e.g.
"50.02000000").string
Token symbol the customer must send (e.g.
"USDT").string
Chain identifier (e.g.
"polygon").string
Original invoice amount in fiat (e.g.
"49.99000000").string
Original invoice currency (e.g.
"USD").string
Exchange rate used for the fiat → crypto conversion at time of address generation.
string
Invoice status — always
"pending" at creation.string
ISO 8601 expiry timestamp. Always set — defaults to the platform rate window if not specified.
string
ISO 8601 creation timestamp.
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"
}
}'
const response = await fetch('https://api.settlx.io/api/v1/payments', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.SETTLX_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount: '49.99',
currency: 'USD',
chain: 'polygon',
token: 'USDT',
description: 'Order #1234',
expiresInMinutes: 30,
webhookUrl: `${process.env.BASE_URL}/webhooks/settlx`,
metadata: { orderId: 'order_abc123' },
}),
});
const { data } = await response.json();
// Show to your customer
console.log(data.address); // Deposit address
console.log(data.cryptoAmount); // Exact amount to send
console.log(data.qrCode); // Base64 QR code — render as <img>
import httpx
client = httpx.Client(headers={"Authorization": "Bearer pk_live_your_api_key"})
response = client.post("https://api.settlx.io/api/v1/payments", json={
"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 = response.json()["data"]
print(data["address"]) # Deposit address
print(data["cryptoAmount"]) # Exact amount to send
{
"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"
}
}
{
"error": "Bad Request",
"message": "Chain polygon is not supported or not enabled"
}
{
"error": "Unauthorized",
"message": "Invalid API key"
}
{
"error": "Forbidden",
"message": "Merchant account is not active"
}
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.