Billing & invoices

Overview

Billing questions are among the most frequent a support team receives, and among the most sensitive. Silux Chat handles them in three stages: the customer is verified with a one-time code, the bot reads that customer’s invoices (and balance, where your system holds one), and it answers only from what came back. It never estimates an amount, never invents a due date and never tells a customer a payment “has gone through” unless your system says so.

• Read-only. The bot reads invoices and balances. It cannot take payments, issue refunds, change a payment method or alter an invoice — none of the billing connectors request write access.
• Verified customers only. Invoice and balance calls are blocked in code until identity verification has succeeded in that conversation. There is no prompt or setting that bypasses it.
• One standard shape. Whether the data comes from Xero, Stripe, your own database or the live demo, the bot receives the same core fields per invoice: invoice, date, amount, status.

What customers ask, and what the bot does

Two ways to connect billing

How a connector call flows

1. 1
   The customer passes verification. The platform stores a session for 30 minutes holding the customer record your vendor returned (vendor ID, name, email, phone, postcode).
2. 2
   The bot calls POST https://www.siluxchat.com/api/connect/{connection_id}/invoices with that session token. The request carries a per-connection access key that the platform generates and holds — you never call this endpoint yourself.
3. 3
   The platform calls the vendor’s documented invoices endpoint for that customer ID with your stored, encrypted credentials, and maps each row into the standard shape. Amounts reported in minor units (pence or cents) are converted to pounds, and dates are normalised to YYYY-MM-DD.
4. 4
   A safety net removes any row that names a different customer’s email address, whatever the vendor search returned. The bot then answers from the remaining rows.

{
  "success": true,
  "invoices": [
    { "invoice": "INV-0042", "date": "2026-09-01", "amount": "120.00", "status": "PAID" },
    { "invoice": "INV-0051", "date": "2026-09-15", "amount": "80.00", "status": "AUTHORISED" }
  ]
}

The invoice shape

Every source is mapped to the same fields. The first two are required for a row to count; the others are shown when present. Many connectors add extra fields their vendor provides — currency, due or due_date, andoutstanding (the amount still owed on a part-paid invoice) are the most common. Each connector’s page lists exactly which fields it maps.

Invoices from your own system (Account Connect)

Your /invoices endpoint receives the session token your /verify-otp endpoint issued, looks up which customer it belongs to, and returns their invoices. Everything below runs against our public demo, which holds fictional customers only.

# export SESSION=<the session_token returned by POST /verify-otp>
: "${SESSION:?export SESSION first}"
curl -s -X POST "https://www.siluxchat.com/api/account-connect-demo/v1/invoices" \
  -H "X-API-Key: demo-account-connect-key" \
  -H "Content-Type: application/json" \
  -d "{\"session_token\":\"$SESSION\"}"

{
  "success": true,
  "invoices": [
    { "invoice": "INV-7781", "date": "2026-09-01", "amount": "£19.95", "status": "paid" },
    { "invoice": "INV-7702", "date": "2026-08-01", "amount": "£19.95", "status": "paid" }
  ]
}

{
  "success": true,
  "invoices": [
    { "invoice": "INV-7790", "date": "2026-09-01", "amount": "£29.95", "status": "unpaid" }
  ]
}

The whole flow, copy and paste

This script verifies Jane Demo and reads her invoices and balance. It runs as written in any shell with curl and Python 3.

BASE=https://www.siluxchat.com/api/account-connect-demo/v1
KEY=demo-account-connect-key

# 1. Identify Jane Demo (the demo never sends a text; the code is always 123456)
OTP=$(curl -s -X POST $BASE/verify-identity -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
  -d '{"full_name":"Jane Demo","postcode":"SW1A 1AA"}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["otp_token"])')

# 2. Exchange the code for a session token
SESSION=$(curl -s -X POST $BASE/verify-otp -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
  -d "{\"otp_token\":\"$OTP\",\"otp_code\":\"123456\"}" | python3 -c 'import sys,json;print(json.load(sys.stdin)["session_token"])')

# 3. Read her invoices and her account balance
curl -s -X POST $BASE/invoices        -H "X-API-Key: $KEY" -H 'Content-Type: application/json' -d "{\"session_token\":\"$SESSION\"}"; echo
curl -s -X POST $BASE/account-summary -H "X-API-Key: $KEY" -H 'Content-Type: application/json' -d "{\"session_token\":\"$SESSION\"}"; echo

Recommendations for your implementation

• Return the most recent invoices first and cap the list — the last 12 is plenty. The bot reads roughly the first 2,000 characters of a response, so a short list is read in full.
• A customer with no invoices is a normal answer: return {"success": true, "invoices": []}, never an error.
• Format amounts as the customer would see them (£29.95), including credit notes as negative amounts or with a status of credit.
• Only return invoices belonging to the customer bound to the session token. Never accept a customer ID from the request body.

Balances and amounts due

A balance is a single figure, so it travels in the account summary rather than as a list. With your own system, add it to your/account-summary response under a clear name such as balance_due. With a connector that has the balancecapability (Stripe, Xero, QuickBooks, Sage and others), the platform reads the vendor’s balance and merges it into the account summary automatically.

# export SESSION=<the session_token returned by POST /verify-otp>
: "${SESSION:?export SESSION first}"
curl -s -X POST "https://www.siluxchat.com/api/account-connect-demo/v1/account-summary" \
  -H "X-API-Key: demo-account-connect-key" \
  -H "Content-Type: application/json" \
  -d "{\"session_token\":\"$SESSION\"}"

{
  "success": true,
  "account": {
    "account_number": "C1002",
    "status": "active",
    "plan": "Unlimited Calls Bundle — 24 months",
    "monthly_price": "£29.95",
    "contract_end": "2028-01-15",
    "balance_due": "£29.95",
    "name": "Jane Demo"
  }
}

Through a connector, the merged summary carries the customer fields the vendor returned plus the vendor’s balance row, for example {"id": "cus_…", "name": "Jane Smith", "email": "jane@example.com", "balance": "12.50"}. See Account lookups for the full summary behaviour.

Billing connectors

Every connector below can read invoices, a balance, or both. Each page explains where to find the key in the vendor’s admin, the read-only permissions to grant and exactly which fields the bot sees. They are tested against each vendor’s documented API responses and again with a real call to your own account when you connect.

Errors and edge cases

A connection whose vendor starts refusing its key is marked as failing, and the daily health check emails the account owner once. Details and fixes are in Troubleshooting.

What never to return

The billing connectors only map the invoice fields listed on each connector’s page (number, date, amount, status and, for some vendors, currency, due date or amount outstanding) plus the balance, so card and bank details held by a vendor are never read in the first place. More in Security & data protection.

Get help

Unsure whether your billing system is covered, or want a second pair of eyes on your /invoices endpoint before you go live? Email support@siluxcall.co.uk with the name of the system you use and a sample (anonymised) response — our integration team will help you connect it.