WHMCS integration

Before you begin

Complete:

1. Store setup
2. Understand flow

Use this path if your tenant website runs on WHMCS (Web Host Manager Complete Solution) and you want to automatically add credit to a client's account when a VodafoneCash payment is matched.

How it works

When a payment is matched on our platform, our server calls the WHMCS API directly:

• Endpoint: POST https://your-whmcs.com/includes/api.php
• Action: AddCredit
• Parameters:
  • identifier — your WHMCS API identifier
  • secret — your WHMCS API secret
  • clientid — the WHMCS client ID (sent as user_name by your payment form)
  • description — VodafoneCash payment - trans_id: {trans_id}
  • amount — the converted balance (after applying your store's currency rate)

WHMCS responds with { "result": "success", ... } on success.

No custom callback endpoint is needed on your site — our server calls the WHMCS API directly using your credentials.

Store settings

API URL

Set to your WHMCS base URL (no trailing slash):

https://your-whmcs.com

Our system automatically appends /includes/api.php to the URL.

WHMCS Identifier & Secret

How to get your WHMCS API credentials:

1. Log in to your WHMCS admin area.
2. Go to Configuration → Manage API Credentials (or System Settings → API Credentials).
3. Click Generate New API Credential.
4. Assign to an admin user and select the Add/Remove Credit API role (or broader access).
5. ⚠️ Copy the Identifier and Secret immediately — the secret is shown only once.
6. Paste them directly into the WHMCS Identifier and WHMCS Secret fields.

IP Whitelisting (Required)

Required step

Our server must be whitelisted in WHMCS before API calls will succeed. Without this, WHMCS will reject all AddCredit requests with an access error.

Add the following IP address to both places in your WHMCS admin area under Settings → Security:

157.173.113.36

1. Whitelisted IPs — allows the IP to bypass IP-based access restrictions.
2. API IP Access Restriction — explicitly permits this IP to call the WHMCS API.

Steps:

1. Log in to your WHMCS Admin Area.
2. Go to Settings → Security.
3. Under Whitelisted IPs, add 157.173.113.36.
4. Under API IP Access Restriction, also add 157.173.113.36.
5. Save changes.

user_name mapping

When determining who should receive the automated credit, the user_name parameter sent in your check request must exactly match the WHMCS Client ID (numeric) of the customer.

Example payment check call:

GET /api/payment_link_check?phone=01000000000&amount=100&user_name=42&store_id=5&lang=en

user_name=42 means WHMCS client ID 42 will receive the credit once matched.

Official WHMCS Gateway Module (Recommended)

To display the payment form on your client invoices and securely trigger the check without exposing your Store ID, we provide an official WHMCS Gateway Module.

The module is maintained on GitHub: vodafoncash-whmcs-module.

1. Open Releases (v1.0.0) and download the latest .zip file.
2. Extract the contents of the ZIP file directly into the root directory of your WHMCS installation. (This places files safely into modules/gateways/).
3. Log in to your WHMCS Admin Area.
4. Navigate to System Settings → Payment Gateways.
5. Click on the All Payment Gateways tab and click VodafoneCash to activate it.
6. Configure the module settings:
   • VodafoneCash System URL: Enter our platform URL (e.g., https://vodafoncash.com).
   • Store ID: Enter your store ID.
7. Tick the box to Show on Order Form.

What the module does

When a client views an unpaid invoice and selects VodafoneCash, the module automatically displays a form asking for their Wallet Phone Number.

When they hit confirm:

1. The module securely sends the data (phone, amount, client ID) to a custom backend callback (modules/gateways/callback/vodafoncash.php).
2. The backend securely uses your Store ID to call our GET /api/payment_link_check.
3. If successful, our platform matches the transaction and asynchronously calls your WHMCS AddCredit API to credit the client.
4. The client is shown a success message and redirected back to their invoice.

Anti-Spam

When Anti-Spam is enabled on your store, a payment may enter a waiting-for-approval state before credit is added to the client. Your payment form should handle the requires_verification: true response — see the check form guide for details.

Quick checklist

Before going live:

• [ ] WHMCS API credentials generated (identifier + secret)
• [ ] API URL set to your WHMCS base URL (e.g. https://your-whmcs.com)
• [ ] WHMCS Identifier and Secret fields filled
• [ ] IP 157.173.113.36 added to Whitelisted IPs (Settings → Security)
• [ ] IP 157.173.113.36 added to API IP Access Restriction (Settings → Security)
• [ ] Your payment form sends user_name = WHMCS client ID
• [ ] Currency rate configured in store settings