hostdoc — offline cPanel/WHM/WHMCS support brain

← all runbooks

---
title: Invoice has not been paid or a payment failed
panel: WHMCS
symptoms:
  - invoice shows as unpaid
  - card payment did not complete
  - customer says they were charged
  - service suspended for non-payment
  - payment did not go through
  - card was declined
  - i have paid but it still shows unpaid
  - refund the payment
  - invoice still outstanding
  - service switched off for non payment
---

# Invoice has not been paid or a payment failed

## 1. Read the invoice before touching the service

**Why:** the invoice is the record of what is owed and what has been paid
against it. Almost every question in this call is answered by the
invoice, and the service is where people instinctively look. Reading the
invoice first tells you which of the three situations you are in: never
paid, paid but not recorded, or paid and recorded.

**In WHMCS:** the client's invoice, then the transaction list against it.

**In the terminal:** the API call `getinvoice` returns the invoice and
its line items. `getinvoices` returns them for a client.

**Care:** this only reads.

- https://developers.whmcs.com/api-reference/getinvoice/
- https://developers.whmcs.com/api-reference/getinvoices/

## 2. Check whether the money arrived but did not clear

**Why:** a transaction that shows on the customer's statement but not on
the invoice is a gateway settlement problem, not a customer problem. The
customer is right to be annoyed and wrong to be blamed, and telling them
otherwise is what turns this into a chargeback.

**In WHMCS:** the transaction list against the invoice, then the gateway
dashboard for the same reference.

**In the terminal:** the API calls `addtransaction` and
`addinvoicepayment` are what record a payment that arrived but was not
captured by the normal flow.

**Care:** recording a payment that has not actually been received is
fraud against your own accounts. Only do it against a reference you can
see on the customer's statement.

- https://developers.whmcs.com/api-reference/addtransaction/
- https://developers.whmcs.com/api-reference/addinvoicepayment/

## 3. Check the gateway when several customers report it

**Why:** if three customers report the same failure in the same hour, it
is the gateway and not any of them. Chasing each customer's browser
individually wastes the day. The gateway's own dashboard tells you in
one look what is wrong.

**In WHMCS:** Apps and Integrations, then the payment gateway's
settings and activity.

**In the terminal:** the API call `getpaymentmethods` shows which
gateways are enabled. `capturepayment` is the call for taking a payment
that was authorised but not captured.

**Care:** changing a gateway's configuration affects every customer using
it. Do not change it to fix one customer's payment.

- https://developers.whmcs.com/api-reference/getpaymentmethods/
- https://developers.whmcs.com/api-reference/capturepayment/

## 4. Settle the invoice before lifting the suspension

**Why:** unsuspending before the invoice is settled puts the customer back
in exactly the same position a week later, and they will be less
willing the second time. Telling them the order of it, settling first,
is what stops it becoming a cycle.

**In WHMCS:** the invoice, then the service's suspended status.

**In the terminal:** the API calls `modulesuspend` and
`moduleunsuspend` act on the service.

**Care:** unsuspending puts a service back online that may have been
suspended for a reason the customer has still not fixed. Check the
ticket before you do it.

- https://developers.whmcs.com/api-reference/modulesuspend/
- https://developers.whmcs.com/api-reference/moduleunsuspend/