CCBill Payment Gateway for WooCommerce Subscriptions

Contents

1. Requirements
2. Install the plugin
3. Configure the gateway in WooCommerce
4. Configure CCBill (approval URL + webhook)
5. Run a test transaction
6. Troubleshooting
7. Support

1. Requirements

• WordPress 6.0+ and a working WooCommerce store.
• WooCommerce (latest stable).
• WooCommerce Subscriptions — get it here. Required even if you only sell one-time products, because the gateway integrates with the Subscriptions hooks.
• A CCBill merchant account with a Dynamic Pricing Form enabled (see callout above).
• HTTPS on your store URL — CCBill webhooks won't post to an insecure endpoint.

2. Install the plugin

1. Log in to your WordPress admin.
2. Go to Plugins → Add New → Upload Plugin.
3. Choose the plugindistrict-ccbill-payment-gateway-woocommerce-subscriptions.zip file from your Plugin District download.
4. Click Install Now, then Activate.

You can re-download the latest ZIP at any time from My Account → Downloads.

3. Configure the gateway in WooCommerce

1. Go to WooCommerce → Settings → Payments.
2. Find CCBill in the list and toggle it on.
3. Click Manage and fill in the fields from your CCBill subaccount:
   • Account Number — your 6-digit CCBill client account.
   • Subaccount Number — the subaccount you want charges routed to.
   • Form Name — the dynamic pricing form ID assigned to you by CCBill.
   • Salt / Encryption Key — copy from CCBill's Account Info → Sub Account Admin → Sub Account → MD5 Salt. This is what hashes the form payload; if it doesn't match, payments will be rejected.
   • Currency Code — must match your WooCommerce store currency.
4. Click Save Changes.

4. Configure CCBill

4a. Approval URL

This is where CCBill returns the customer after a successful charge.

1. Log in to your CCBill admin.
2. Go to Account Info → Sub Account Admin → Basic.
3. Set the Approval URL to your subscriptions page so customers land on their new subscription:
   https://YOURSITE.com/my-account/subscriptions/
4. Click Update at the bottom of the page.

4b. Advanced post URLs

Now click Advanced on the left. Both the Approval Post URL and Denial Post URL should be left empty. Order status is delivered through webhooks (next step), not legacy post-backs — leaving these set will cause duplicate notifications.

4c. Webhook

1. Go to Account Info → Sub Account Admin → Subaccount → Webhooks.
2. Click Add.
3. Set Webhook URL to:
   https://YOURSITE.com/?wc-api=WC_Gateway_CCBill&webhook=1
   (Replace YOURSITE.com with your domain. The ?wc-api= handler is registered by WooCommerce — no permalink changes needed.)
4. Select all events. Filtering at this layer will mean missing renewals, refunds, or chargebacks.
5. Click Update at the bottom.

5. Run a test transaction

1. Ask CCBill support to whitelist your IP for their test system, or use the test cards they provide for your account.
2. Add a subscription product to the cart and check out.
3. You should be redirected to the CCBill hosted payment form, complete the payment, and land on /my-account/subscriptions/.
4. Within a minute, the order in WooCommerce should flip from Pending to Processing (or Active for the subscription) — that flip is the webhook arriving.

6. Troubleshooting

Orders stay in "Pending" after a successful payment

Almost always a webhook delivery issue. Check, in order:

1. Webhook URL is exact, including ?wc-api=WC_Gateway_CCBill&webhook=1 and HTTPS.
2. Your firewall / CDN is not blocking CCBill. If you use Cloudflare, Wordfence, Sucuri, or similar, whitelist these CCBill ranges:
   • 64.38.240.0 – 64.38.240.255
   • 64.38.241.0 – 64.38.241.255
   • 64.38.212.0 – 64.38.212.255
   • 64.38.215.0 – 64.38.215.255
3. WooCommerce logs. Check WooCommerce → Status → Logs for entries under ccbill — failed signature verification means the Salt / Encryption Key in your gateway settings doesn't match the one in CCBill.

Customer is bounced back to checkout instead of subscriptions page

Your CCBill Approval URL is unset or wrong. Re-check step 4a.

"Invalid form" error from CCBill

The Form Name in your WooCommerce settings doesn't match a Dynamic Pricing Form on your CCBill subaccount. Confirm the exact form ID with CCBill support.

7. Support

Found a bug, got stuck, or want a feature? Contact us with your WooCommerce version, WooCommerce Subscriptions version, and the plugin version (Plugins → Installed Plugins). For CCBill-account questions (form approval, payouts, chargebacks), reach CCBill directly at [email protected] or 1-800-510-2859.

↑ Back to top