How to manage transactions for invoices in WHMCS


Written by Dennis Nind

Last published at: February 8th, 2019

Applying Payment to an Invoice

If you receive a payment that isn't automatically logged in WHMCS, you will need to manually apply it to the invoice. Alternatively if the payment is not for any particular invoice, you should follow the steps below for issuing credit to a client.

  1. Begin by locating & opening the invoice to apply the payment to using the Search or Billing > Unpaid Invoices list
  2. Next from the invoice management page, select the Add Payment tab
  3. Enter the details corresponding to the payment including the date, payment method, transaction ID & amount into the fields shown
  4. Then click the Add Payment button to complete the process
Under/Over Payments You can add a partial amount, all of the invoice's balance or even apply more than the amount due on the invoice. If you apply a payment to an invoice which is larger than the amount due then any excess will be automatically added as a credit to the user for use on future invoices.

If you receive a payment which applies to multiple invoices, to enter that go to Billing > View Transaction List > Add Transaction. There you get the same fields as when applying payment to an individual invoice but in addition you also get a field labelled Invoice ID(s) and in that, you can enter a comma seperated list of all the invoice numbers that this payment should be applied to. Payments will be applied in the order entered until the full amount has been used and any amount left over will be automatically added as a credit to the user for use on future invoices.

Adding a Manual Transaction

You will need to enter transactions manually if you receive payment from a client by an offline means such as cheque or wire transfer. Or for example to enter external transactions into WHMCS such as expenditures you make to pay for your servers and/or other services. It is important you do this correctly to ensure the figures in your WHMCS system are correct so here's how you do it:

  1. Begin by going to Billing > Transactions List
  2. Select the Add Transaction tab at the top of the page
  3. Then you can choose the client it relates to (if any), date of the payment, gateway used, enter a description, transaction id (if applicable) and the amount
  4. If this is a payment that the client should be allowed to apply to invoices later (ie. a prefunding or payment on account) then you should tick the Add as Credit checkbox which will automatically create the appropriate credit entry for the user
  5. Once happy with the settings, click the Add Transaction button to complete the process
Note It is necessary to either enter Invoice ID(s) or tick the Add as Credit checkbox. Failure to do either will result in the transaction not being applied against an invoice or credited to the client's account.

Account Prefunding/Add Funds

There are times when a client might want to deposit money with you in advance. For example if they are about to place a number of orders, or they are going on holiday. And WHMCS allows for this using the Account Prefunding/Credit feature. For details, please see Add Funds

Managing Credit

Credit allows customers to have a prepaid balance on their account which can be useful for allowing customers to pay in advance and dealing with overpayments. For more help and information, please refer to Credit/Prefunding

Searching Transactions & Handling Reversals

So you've had a cheque bounce, or you've received a chargeback/dispute for a transaction you already applied? Chances are the actions that payment should trigger, such as renewal of a product, domain registration or renewal, have already happened and can't be reversed. So what you need to do is deduct the amount from your income and issue the client a new invoice to re-pay. So let's take an example of a transaction paid by 2CheckOut with the transaction ID "6A5245278HM" and see how we would handle that.

  1. Begin by going to Billing > Transactions List
  2. This will show you a list of all the transactions recorded in your WHMCS system
  3. Next, click the Search/Filter tab at the top - the various filtering options available will appear
  4. We know this transaction was made using 2CheckOut so we select 2CheckOut in the Gateway Dropdown List
  5. We also know the transaction ID so we enter this in the Transaction ID field as shown below
  6. Once you have completed selecting filter options, click submit
  7. Any matching transactions will be displayed.
  8. From here we can see the transaction date, client who made it and the invoice they were paying
  9. Now you can click into the invoice that transaction was applied to, and use the Refund tab to apply a "Record Only" refund to deduct the amount paid from your income and show that invoice as no longer paid
  10. Following that, you need to decide what to do with the items on the invoice. For example if it's a product, you might want to go and suspend that product from the clients profile to prevent any further use. And if it's a domain you might want to contact the registrar and see if a cancellation is a possibility.
  11. After taking care of the products, you may then want to create a new manual invoice for repayment - for example if the dispute is a mistake or the client has contacted you - so you can do that simply by raising a custom invoice, and with that you can also apply any fees or surcharges you may have incurred for the disputed payment. You should not attempt to re-invoice the original items for repayment as that could lead to double incrementing of due dates, and double renewal actions on products & services.

The Gateway Logs

If transactions aren't being automatically handled by WHMCS then it is often useful to take a look at the transaction log. The transactions log can be viewed by going to Billing > Gateway Log. If a payment return has been made by a payment gateway integrated with WHMCS then details of the return will be listed here. Each return has three possible outcomes - Successful, Invalid or Error.

  • A successful payment return occurs when the payment is identified and recorded by WHMCS automatically and any required actions are performed.
  • An invalid return occurs when the data returned from the gateway is not expected by WHMCS - for example the Invoice ID is wrong or the payment value doesn't match
  • Finally, an error return occurs if the data sent from the payment gateway contains errors or cannot be verified

Invalid returns will occur from time to time when the data received is not fully valid and are usually only random one offs. If you start getting a lot of transactions coming back as invalid or as errors then you might want to contact us so we can check it out.