curl https://api.settlx.io/api/v1/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status
async function pollInvoiceStatus(invoiceId) {
const response = await fetch(`https://api.settlx.io/api/v1/invoices/${invoiceId}/status`);
const { data } = await response.json();
if (data.status === 'settled') {
redirectToSuccess(data.returnUrl);
return;
}
if (data.status === 'expired') {
showExpiredUI();
return;
}
// Still pending — show progress and poll again
updateProgressBar(data.paymentProgress);
if (data.hasDetectedPayment) {
showAwaitingConfirmationsUI(data.confirmations, data.requiredConfirmations);
}
setTimeout(() => pollInvoiceStatus(invoiceId), 5000);
}
{
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "pending",
"amount": "49.99",
"currency": "USD",
"description": "Order #1234",
"merchantName": "Acme Inc",
"confirmations": 0,
"requiredConfirmations": 0,
"paymentStatus": "pending",
"paymentStatusDetail": null,
"settledAmount": null,
"txHash": null,
"expiresAt": "2024-01-15T10:30:00.000Z",
"createdAt": "2024-01-15T10:00:00.000Z",
"returnUrl": null,
"totalReceivedAmount": "0",
"totalReceivedCurrency": "USD",
"remainingAmount": "49.99000000",
"paymentProgress": 0,
"hasDetectedPayment": false,
"detectedPaymentAmount": null,
"detectedPaymentCurrency": null,
"paymentIssueType": null,
"mismatchPayment": null
}
}
{
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "pending",
"amount": "49.99",
"currency": "USD",
"description": "Order #1234",
"merchantName": "Acme Inc",
"confirmations": 4,
"requiredConfirmations": 12,
"paymentStatus": "detected",
"paymentStatusDetail": "detected",
"settledAmount": null,
"txHash": "0x9f4c3a8b7e6d5f4c3a8b7e6d5f4c3a8b7e6d5f4c3a8b7e6d5f4c3a8b7e6d5f4c",
"expiresAt": "2024-01-15T10:30:00.000Z",
"createdAt": "2024-01-15T10:00:00.000Z",
"returnUrl": null,
"totalReceivedAmount": "0",
"totalReceivedCurrency": "USDT",
"remainingAmount": "49.99000000",
"paymentProgress": 0,
"hasDetectedPayment": true,
"detectedPaymentAmount": "49.99",
"detectedPaymentCurrency": "USDT",
"paymentIssueType": null,
"mismatchPayment": null
}
}
{
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "settled",
"amount": "49.99",
"currency": "USD",
"description": "Order #1234",
"merchantName": "Acme Inc",
"confirmations": 12,
"requiredConfirmations": 12,
"paymentStatus": "settled",
"paymentStatusDetail": "confirmed",
"settledAmount": "48.74",
"txHash": "0x9f4c3a8b7e6d5f4c3a8b7e6d5f4c3a8b7e6d5f4c3a8b7e6d5f4c3a8b7e6d5f4c",
"expiresAt": "2024-01-15T10:30:00.000Z",
"createdAt": "2024-01-15T10:00:00.000Z",
"returnUrl": "https://yoursite.com/order/1234/success",
"totalReceivedAmount": "49.99",
"totalReceivedCurrency": "USDT",
"remainingAmount": "0.00000000",
"paymentProgress": 100,
"hasDetectedPayment": true,
"detectedPaymentAmount": "49.99",
"detectedPaymentCurrency": "USDT",
"paymentIssueType": null,
"mismatchPayment": null
}
}
{
"error": "Not Found",
"message": "Invoice not found"
}
Invoices
Get Invoice Status
Public polling endpoint for invoice payment status
GET
/
api
/
v1
/
invoices
/
{id}
/
status
curl https://api.settlx.io/api/v1/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status
async function pollInvoiceStatus(invoiceId) {
const response = await fetch(`https://api.settlx.io/api/v1/invoices/${invoiceId}/status`);
const { data } = await response.json();
if (data.status === 'settled') {
redirectToSuccess(data.returnUrl);
return;
}
if (data.status === 'expired') {
showExpiredUI();
return;
}
// Still pending — show progress and poll again
updateProgressBar(data.paymentProgress);
if (data.hasDetectedPayment) {
showAwaitingConfirmationsUI(data.confirmations, data.requiredConfirmations);
}
setTimeout(() => pollInvoiceStatus(invoiceId), 5000);
}
{
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "pending",
"amount": "49.99",
"currency": "USD",
"description": "Order #1234",
"merchantName": "Acme Inc",
"confirmations": 0,
"requiredConfirmations": 0,
"paymentStatus": "pending",
"paymentStatusDetail": null,
"settledAmount": null,
"txHash": null,
"expiresAt": "2024-01-15T10:30:00.000Z",
"createdAt": "2024-01-15T10:00:00.000Z",
"returnUrl": null,
"totalReceivedAmount": "0",
"totalReceivedCurrency": "USD",
"remainingAmount": "49.99000000",
"paymentProgress": 0,
"hasDetectedPayment": false,
"detectedPaymentAmount": null,
"detectedPaymentCurrency": null,
"paymentIssueType": null,
"mismatchPayment": null
}
}
{
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "pending",
"amount": "49.99",
"currency": "USD",
"description": "Order #1234",
"merchantName": "Acme Inc",
"confirmations": 4,
"requiredConfirmations": 12,
"paymentStatus": "detected",
"paymentStatusDetail": "detected",
"settledAmount": null,
"txHash": "0x9f4c3a8b7e6d5f4c3a8b7e6d5f4c3a8b7e6d5f4c3a8b7e6d5f4c3a8b7e6d5f4c",
"expiresAt": "2024-01-15T10:30:00.000Z",
"createdAt": "2024-01-15T10:00:00.000Z",
"returnUrl": null,
"totalReceivedAmount": "0",
"totalReceivedCurrency": "USDT",
"remainingAmount": "49.99000000",
"paymentProgress": 0,
"hasDetectedPayment": true,
"detectedPaymentAmount": "49.99",
"detectedPaymentCurrency": "USDT",
"paymentIssueType": null,
"mismatchPayment": null
}
}
{
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "settled",
"amount": "49.99",
"currency": "USD",
"description": "Order #1234",
"merchantName": "Acme Inc",
"confirmations": 12,
"requiredConfirmations": 12,
"paymentStatus": "settled",
"paymentStatusDetail": "confirmed",
"settledAmount": "48.74",
"txHash": "0x9f4c3a8b7e6d5f4c3a8b7e6d5f4c3a8b7e6d5f4c3a8b7e6d5f4c3a8b7e6d5f4c",
"expiresAt": "2024-01-15T10:30:00.000Z",
"createdAt": "2024-01-15T10:00:00.000Z",
"returnUrl": "https://yoursite.com/order/1234/success",
"totalReceivedAmount": "49.99",
"totalReceivedCurrency": "USDT",
"remainingAmount": "0.00000000",
"paymentProgress": 100,
"hasDetectedPayment": true,
"detectedPaymentAmount": "49.99",
"detectedPaymentCurrency": "USDT",
"paymentIssueType": null,
"mismatchPayment": null
}
}
{
"error": "Not Found",
"message": "Invoice not found"
}
Get Invoice Status
Public endpoint for polling invoice payment status. Designed for use on the customer-facing checkout page as a fallback when the WebSocket connection is unavailable. This endpoint does not require authentication.Prefer the WebSocket at
/ws/invoices/:id for real-time updates. Use this endpoint only as a polling fallback. Recommended polling interval: 5–10 seconds.Path Parameters
string
required
UUID of the invoice.
Response
object
Hide Invoice status object
Hide Invoice status object
string
UUID of the invoice
string
Invoice status. One of:
pending, partial, confirmed, settled, expired.string
Original invoice amount
string
Original invoice fiat currency (e.g.
USD)string | null
Invoice description
string
Merchant display name (for branding the checkout page)
number
Current on-chain confirmation count for the latest detected payment
number
Confirmations required for the payment chain
string
Combined status string for UI rendering. One of:
pending, detected, confirmed, partial, wrong_token, settled, expired.string | null
Latest payment record’s status —
detected or confirmed. null if no payment yet.string | null
Net amount delivered in settlement, if completed
string | null
Latest on-chain transaction hash — payment hash if detected, settlement hash if settled.
string | null
ISO 8601 expiry timestamp
string
ISO 8601 creation timestamp
string | null
Post-payment return URL extracted from invoice metadata (
returnUrl, successUrl, etc.). null if not set.string
Cumulative amount received (across multiple payments) in payment currency
string
Currency of received payments
string
Amount still owed (8-decimal string)
number
Progress 0–100 (integer percent)
boolean
Whether at least one non-mismatch payment has been detected
string | null
Amount of the most recent detected payment
string | null
Currency of the most recent detected payment
string | null
Issue type if any:
underpaid, overpaid, or wrong_token. null if none.object | null
Set when a customer paid the wrong token. Contains
amount, currency, actualCurrency, txHash. null if no mismatch.curl https://api.settlx.io/api/v1/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status
async function pollInvoiceStatus(invoiceId) {
const response = await fetch(`https://api.settlx.io/api/v1/invoices/${invoiceId}/status`);
const { data } = await response.json();
if (data.status === 'settled') {
redirectToSuccess(data.returnUrl);
return;
}
if (data.status === 'expired') {
showExpiredUI();
return;
}
// Still pending — show progress and poll again
updateProgressBar(data.paymentProgress);
if (data.hasDetectedPayment) {
showAwaitingConfirmationsUI(data.confirmations, data.requiredConfirmations);
}
setTimeout(() => pollInvoiceStatus(invoiceId), 5000);
}
{
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "pending",
"amount": "49.99",
"currency": "USD",
"description": "Order #1234",
"merchantName": "Acme Inc",
"confirmations": 0,
"requiredConfirmations": 0,
"paymentStatus": "pending",
"paymentStatusDetail": null,
"settledAmount": null,
"txHash": null,
"expiresAt": "2024-01-15T10:30:00.000Z",
"createdAt": "2024-01-15T10:00:00.000Z",
"returnUrl": null,
"totalReceivedAmount": "0",
"totalReceivedCurrency": "USD",
"remainingAmount": "49.99000000",
"paymentProgress": 0,
"hasDetectedPayment": false,
"detectedPaymentAmount": null,
"detectedPaymentCurrency": null,
"paymentIssueType": null,
"mismatchPayment": null
}
}
{
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "pending",
"amount": "49.99",
"currency": "USD",
"description": "Order #1234",
"merchantName": "Acme Inc",
"confirmations": 4,
"requiredConfirmations": 12,
"paymentStatus": "detected",
"paymentStatusDetail": "detected",
"settledAmount": null,
"txHash": "0x9f4c3a8b7e6d5f4c3a8b7e6d5f4c3a8b7e6d5f4c3a8b7e6d5f4c3a8b7e6d5f4c",
"expiresAt": "2024-01-15T10:30:00.000Z",
"createdAt": "2024-01-15T10:00:00.000Z",
"returnUrl": null,
"totalReceivedAmount": "0",
"totalReceivedCurrency": "USDT",
"remainingAmount": "49.99000000",
"paymentProgress": 0,
"hasDetectedPayment": true,
"detectedPaymentAmount": "49.99",
"detectedPaymentCurrency": "USDT",
"paymentIssueType": null,
"mismatchPayment": null
}
}
{
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "settled",
"amount": "49.99",
"currency": "USD",
"description": "Order #1234",
"merchantName": "Acme Inc",
"confirmations": 12,
"requiredConfirmations": 12,
"paymentStatus": "settled",
"paymentStatusDetail": "confirmed",
"settledAmount": "48.74",
"txHash": "0x9f4c3a8b7e6d5f4c3a8b7e6d5f4c3a8b7e6d5f4c3a8b7e6d5f4c3a8b7e6d5f4c",
"expiresAt": "2024-01-15T10:30:00.000Z",
"createdAt": "2024-01-15T10:00:00.000Z",
"returnUrl": "https://yoursite.com/order/1234/success",
"totalReceivedAmount": "49.99",
"totalReceivedCurrency": "USDT",
"remainingAmount": "0.00000000",
"paymentProgress": 100,
"hasDetectedPayment": true,
"detectedPaymentAmount": "49.99",
"detectedPaymentCurrency": "USDT",
"paymentIssueType": null,
"mismatchPayment": null
}
}
{
"error": "Not Found",
"message": "Invoice not found"
}
This endpoint is public — anyone with the invoice ID can poll it. Do not include the invoice ID in URLs that customers can bookmark and share with third parties if you consider the metadata sensitive.
⌘I