Create Payment

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"
}

POST

api

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: 15

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"

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

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.

Invoices

Subscriptions

Settlements

Webhooks

Reference

Webhook Events — Invoices

Webhook Events — Subscriptions

Guides

Create Payment

Request

Response

​Request

​Response

Request

Response