curl https://api.settlx.io/api/v1/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status
{
"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
}
}
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
{
"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
}
}
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
UUID of the invoice.
Response
Hide Invoice status object
Hide Invoice status object
UUID of the invoice
Invoice status. One of:
pending, partial, confirmed, settled, expired.Original invoice amount
Original invoice fiat currency (e.g.
USD)Invoice description
Merchant display name (for branding the checkout page)
Current on-chain confirmation count for the latest detected payment
Confirmations required for the payment chain
Combined status string for UI rendering. One of:
pending, detected, confirmed, partial, wrong_token, settled, expired.Latest payment record’s status —
detected or confirmed. null if no payment yet.Net amount delivered in settlement, if completed
Latest on-chain transaction hash — payment hash if detected, settlement hash if settled.
ISO 8601 expiry timestamp
ISO 8601 creation timestamp
Post-payment return URL extracted from invoice metadata (
returnUrl, successUrl, etc.). null if not set.Cumulative amount received (across multiple payments) in payment currency
Currency of received payments
Amount still owed (8-decimal string)
Progress 0–100 (integer percent)
Whether at least one non-mismatch payment has been detected
Amount of the most recent detected payment
Currency of the most recent detected payment
Issue type if any:
underpaid, overpaid, or wrong_token. null if none.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
{
"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
}
}
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