BILLmanager Documentation

Recurring (automatic) payments

A recurring payment allows a user to set up the recurring payment only once, and funds will be added automatically when needed. 

Funds are added to the BILLmanager account automatically when the client has insufficient funds to pay for services with automatic renewal or daily billing cycle. The amount of every recurring payment is generated based on estimated expenses for the next month.

Example: a client orders the Shared hosting service for 150 euro per month and activates the automatic renewal option. The client uses recurring payments. After he had paid for the service, he had 10 euro left on his account. 

So the estimated expenses for the next month is 140 euro. The system will make a recurring payment for 140 euro. On the third month, the system will pay the full price - 150 euro. 

If the automatic payment failed, the client will receive the error notification" "Cannot complete automatic payment". 

Configuration


Admin area

Some payment methods support recurring payments: 

To enable recurring payments, navigate to "Provider" → "Payment methods" → "Edit" → check the "Recurring payments" box:

This checkbox is also available on a new payment method creation form "Provider" → "Payment method" → "Add" → "Recurring payments".

With this option enabled, the system will add new configuration fields specific to each payment method. For more information, refer to a certain payment method page

Client area

Recurring payment management options can be found in "Finances" → "Auto payment". This menu section is hidden if the service provider has not configured the payment method supporting automatic invoicing. On the configuration form, a client can choose the desired payment method and enter the maximum payment amount. To create an auto-payment without the limit, leave the Maximum payment amount field blank. 

When the client has insufficient funds in his account for the automatic payment, BILLmanager will send to his email the notification that the monthly auto-payment limit has been reached". The notification is sent only after the first failed attempt to make the automatic payment. 

Eg., the total amount of auto-payments for the current month is 90 euro and the limit is 100 euro. Today is the day when the system will charge the account automatically for 20 euro. The upcoming autopayment amount will be 110 euro. This amount exceeds the specified limit, so BILLmanager will cancel the payment and email the notification to the client. 

Clicking "Confirm" will redirect the client into the payment system to allow for automatic payments to the provider's company.

How payment is created 


The following cron job creates a payment:

BILLmanager process autopayments
1 0 * * * /usr/local/mgr5/sbin/billmaintain --command recurring >/dev/null 2>&1

The payment will be created provided that the client has insufficient funds on his account balance for renewing services with the enabled auto-renewal option and daily charges. The payment process starts right after creation. 

If the system failed to make a payment 


Check logs 

If an error occurred during the payment process on the payment gateway side, the payment status in BILLmanager will be "New". The log file /usr/local/mgr5/var/logs/billmgr.log will contain the following information: 

core_module INFO Request [pm<payment_system>][root] 'func=payment.recurring.payerror&out=xml&payment=<payment_id>'
 Where

payment_system — the payment gateway name. 

payment_id — payment id in BILLmanager. 

To get information about an issue, open the log file of the corresponding payment system. 

 Log files of payment systems

Yandex.Kassa — /usr/local/mgr5/var/ycresult.log

Adyen — /usr/local/mgr5/var/adyenrecresult.log

WebMoney with invoice — /usr/local/mgr5/var/pmwebmoneyas.log

Stripe — /usr/local/mgr5/var/pmstripe.log

PayMaster — /usr/local/mgr5/var/pmpaymaster.log

SimplePay — /usr/local/mgr5/var/simplepayrecurringresult.log

Invalid_token

If the payment system sends the response invalid_token, BILLmanager will use an expired or invalid authorization token. In this case, the log file of the payment system contains the following string:

libmgr ERROR Error: Type: '<payment_system>_error' Object: 'expired' Value: 'invalid_token'

To resolve the issue, set up a new auto-payment in the customer's client area:

  1. Go to Finances Auto-payment
  2. Disable the old auto-payment.
  3. Configure a new one.