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"
}
}'
const response = await fetch('https://api.settlx.io/api/v1/invoices', {
method: 'POST',
headers: {
'Authorization': 'Bearer pk_live_your_api_key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
amount: '99.99',
currency: 'USD',
description: 'Order #1234',
expiresInMinutes: 30,
webhookUrl: 'https://yoursite.com/webhooks/settlx',
metadata: { orderId: 'order_abc123' }
})
});
const { data } = await response.json();
console.log(data.paymentUrl); // Redirect customer here
import httpx
client = httpx.Client(headers={"Authorization": "Bearer pk_live_your_api_key"})
response = client.post("https://api.settlx.io/api/v1/invoices", json={
"amount": "99.99",
"currency": "USD",
"description": "Order #1234",
"expiresInMinutes": 15,
"webhookUrl": "https://yoursite.com/webhooks/settlx",
"metadata": {"orderId": "order_abc123"}
})
invoice = response.json()["data"]
print(invoice["paymentUrl"]) # Redirect customer here
{
"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"
}
}
{
"error": "Bad Request",
"message": "Amount must be greater than 0"
}
{
"error": "Unauthorized",
"message": "Invalid API key"
}
{
"error": "Forbidden",
"message": "Merchant account is not active"
}
Invoices
Create Invoice
Create a new payment invoice
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"
}
}'
const response = await fetch('https://api.settlx.io/api/v1/invoices', {
method: 'POST',
headers: {
'Authorization': 'Bearer pk_live_your_api_key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
amount: '99.99',
currency: 'USD',
description: 'Order #1234',
expiresInMinutes: 30,
webhookUrl: 'https://yoursite.com/webhooks/settlx',
metadata: { orderId: 'order_abc123' }
})
});
const { data } = await response.json();
console.log(data.paymentUrl); // Redirect customer here
import httpx
client = httpx.Client(headers={"Authorization": "Bearer pk_live_your_api_key"})
response = client.post("https://api.settlx.io/api/v1/invoices", json={
"amount": "99.99",
"currency": "USD",
"description": "Order #1234",
"expiresInMinutes": 15,
"webhookUrl": "https://yoursite.com/webhooks/settlx",
"metadata": {"orderId": "order_abc123"}
})
invoice = response.json()["data"]
print(invoice["paymentUrl"]) # Redirect customer here
{
"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"
}
}
{
"error": "Bad Request",
"message": "Amount must be greater than 0"
}
{
"error": "Unauthorized",
"message": "Invalid API key"
}
{
"error": "Forbidden",
"message": "Merchant account is not active"
}
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
string
required
Invoice amount as a decimal string. Must be greater than 0.Example:
"99.99"string
required
The fiat currency of the invoice. Supported:
USD, EUR, GBP, etc.Example: "USD"string
Optional human-readable description of the invoice.Example:
"Order #1234 — 2x T-shirts"number
Time in minutes until the invoice expires. If omitted, defaults to 15 minutes. Must be between
1 and 525600 (1 year).Example: 15string
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"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
object
Show Invoice object
Show Invoice object
string
UUID of the invoice
string
UUID of your merchant account
string
Invoice amount
string
Invoice currency
string
Invoice status — always
pending on creationstring | null
Invoice description
string
ISO 8601 expiry timestamp. Always set — defaults to the platform rate window if not specified.
string | null
Webhook URL for this invoice
string
Hosted checkout URL. Only needed if you are using our hosted checkout — redirect your customer here. If you are building your own checkout UI, ignore this field.
string
ISO 8601 creation timestamp
string
ISO 8601 last-updated timestamp
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"
}
}'
const response = await fetch('https://api.settlx.io/api/v1/invoices', {
method: 'POST',
headers: {
'Authorization': 'Bearer pk_live_your_api_key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
amount: '99.99',
currency: 'USD',
description: 'Order #1234',
expiresInMinutes: 30,
webhookUrl: 'https://yoursite.com/webhooks/settlx',
metadata: { orderId: 'order_abc123' }
})
});
const { data } = await response.json();
console.log(data.paymentUrl); // Redirect customer here
import httpx
client = httpx.Client(headers={"Authorization": "Bearer pk_live_your_api_key"})
response = client.post("https://api.settlx.io/api/v1/invoices", json={
"amount": "99.99",
"currency": "USD",
"description": "Order #1234",
"expiresInMinutes": 15,
"webhookUrl": "https://yoursite.com/webhooks/settlx",
"metadata": {"orderId": "order_abc123"}
})
invoice = response.json()["data"]
print(invoice["paymentUrl"]) # Redirect customer here
{
"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"
}
}
{
"error": "Bad Request",
"message": "Amount must be greater than 0"
}
{
"error": "Unauthorized",
"message": "Invalid API key"
}
{
"error": "Forbidden",
"message": "Merchant account is not active"
}
⌘I