Webhooks User Guide

Introduction

This document is provided as a technical resource to CCBill merchants. It discusses the features and implementation of the CCBill Webhooks system. This document is intended to be read by programmers, technicians, and others with advanced coding skills.

Users of this guide should have programming skills sufficient enough to enable your own system(s) to retrieve the data sent to the URLs that you have set up for Webhooks data push. This guide seeks to provide you with the functionality to pass consumer data into the CCBill payment form as well as the variables sent and potential parameters of those variables for all transactional events on an account.

Encoded Format

In July, 2017, the ability to choose between two different formats of the Webhook data was added. The original formatting is referred to as “URL Encoded” and uses the content type application/x-www-form-encoded. The newer formatting is referred to as “JSON” and formats the data to follow the JSON (JavaScript Object Notation) open-standard file format and uses the content type application/json.

Versioning

In October, 2013, we added support in Webhooks for different versions. This ensures that any changes to the Webhooks system we will not break your existing configuration.

If a Webhook has more than one version it will display tabbed content. Click the tab for the version you are using to view the details of that call.

In April, 2017, we added support for TLS 1.2 encryption protocol.

In May and June, 2017, we included additional parameters to multiple events.

In July, 2017, we included support for selecting specific configuration version numbers per each Webhook URL event type. This allows users to select previous versions or to upgrade to the newest version through a drop down menu that displays all available version numbers. Also included with this update was the ability to select the JSON formatted webhook data. The supported formats are listed within each version listed in the sections bellow.

The ChangeLog at the end of this document will summarize the changes made for each version.

Passing Variables to the Payment Form

Variables can be passed to the payment form in order to pre-fill consumer information. This can be implemented for the purpose of multi-part forms, custom tracking, and other implementations. Variables are passed to the payment form from the page preceding it through the use of an HTML form, or by passing in the variables through the URL string. Code examples are given below.

Custom tracking variables can also be sent to the form. These values will be posted back to the Webhooks URL when the transaction is complete. To define these variables, simply specify a variable name and a value in the same manner as the other variables being passed.

Optional custom tracking variables can be added manually by creating additional HTML form fields or passing the additional variables into the URL string, depending on the chosen submission method.

The following example shows basic HTML button code, with two custom variables added. The button created will, when clicked, take the consumer to the CCBill payment form while passing in the two custom variables:

<form action='https://bill.ccbill.com/jpost/signup.cgi' method=POST>
<input type=hidden name=clientAccnum value='900000'>
<input type=hidden name=clientSubacc value='0001'>
<input type=hidden name=formName value='211cc'>
<input type=hidden name=language value='English'>
<input type=hidden name=allowedTypes value='0000003361:840,0000004657:840,0000060748:840,0000060750:840,0000060752:840'> <input type=hidden name=subscriptionTypeId value='0000004657:840'>
<input type=hidden name=customVarName1 value=customVarValue1>
<input type=hidden name=customVarName2 value=customVarValue2>
<input type=submit name=submit value='Join Now'>
</form>

Please note that customVarName1 and customVarName2 are only example names and can be anything you choose. The values can also be anything you choose.

You may use a text link instead of a button if desired. The following example shows how to do this using data identical to the previous form example:

https://bill.ccbill.com/jpost/signup.cgi?clientAccnum=900000&clientSubacc=0001&formName=211cc&language=English&allowedTypes=0000003761:840,0000004607:840,0000060248:840,0000063750:840,0000060752:840&subscriptionTypeId=0000004657:840&customVarName1=customVarValue1&customVarName2=customVarValue2

Both methods serve the same purpose and either can be used.

Information can also be passed to the CCBill payment form using dynamic variables in a custom script. A custom HTML form can call the script, which then sends the variables to the CCBill payment form.

The form you create will pass data entered by the consumer to the next form, which will then pass the variables to the CCBill payment form. Upon completion of the transaction, data will be sent to the Webhooks URL.
The following code example uses Perl/CGI code to output a hidden HTML form field using a dynamic variable:

print "<input type=hidden name=customer_fname value='$cust_first_name'>";

Other languages will have different statements and syntax for data output, such as print or echo statements in PHP. Link code can be output in a similar fashion to the HTML form code above, replacing any number of static variable values with dynamic variables.

Please refer any questions you have concerning this type of code to a qualified programmer.

Receiving Data

When a transaction is approved or denied, data will be sent to the Webhooks URL, if that event has been selected within the configuration. The data sent will include everything passed into the payment form along with the data entered into the payment form by the consumer, excluding payment information. This data can be parsed and handled in whichever way the script is coded.

Data can be captured in multiple ways depending on the language in which the Webhooks script is written. For example:

Using PHP

The following line captures the consumer’s first name and assigns it to a variable called $fname. The variable $fname can be named anything you choose.

$fname = $_POST["customer_fname"]

Using Perl/CGI

The following line captures the consumer’s first name and assigns it to a variable called $fname. The variable $fname can be named anything you choose.

$fname = param("customer_fname")__

Other languages will have appropriate functions to capture POST data. Note that variable names must be entered exactly as they appear in this document.

Once the script captures these variable values, the script can handle the data in any manner specified in the script, such as inputting the information into a database.

Variables

CCBill has a set of specified system variables that can be used to pull data from CCBill’s system. Two variable sets are used, one for each of the following situations:

• Payment Form. These variables are used to pre-fill the payment form. Naming the variables correctly, as listed below, will ensure the data properly stored in CCBill’s system as the variables are intended.
• Return. These variables are sent to the Webhook URL, depending on the outcome of the transaction.

In both cases, custom variables will be sent exactly as they were entered.

System variable names must be entered exactly as they appear in this list.

Payment Form

The following chart lists each variable that can be pre-filled in the payment form:

Variable Name	Description
customer_fname	Consumer first name
customer_lname	Consumer last name
address1	Consumer address
email	Consumer email address
city	Consumer city
state	Consumer state
zipcode	Consumer Zip Code
country	Consumer country
phone_number	Consumer phone number
username	Consumer username
password	Consumer password
lifeTimeSubscription

The following variables can also be passed into the payment form, but are not shown on the form:

Variable Name	Description	Example Value
referer	CCBill affiliate ID number. This value is passed as ‘reseller’ when using Traffic Manager to cascade to Epoch forms.	1626321
formName	Three or more character codes identifying the form.	13cc
confirm_password	Confirm the password on the signup form.	0 or 1 (yes or no)
subscriptionTypeId	Subscription Type ID.	0108191202000001259
allowedTypes	The subscription options that will appear on the form; this value is generated automatically in the Admin.	0000003761:840,0000004607:840

Enabling Webhooks in the Admin Portal

1. Sign in to the Admin Portal.
2. Click the Account Info Mega Menu, then select Sub Account Admin from the Manage Sub Accounts section of the menu.
3. Click the Webhooks link on the left side of the screen.
4. Enter the URL that you wish posts to be directed to in the Webhook URL field.
5. Select the post types you wish to subscribe to (click All to select all types, or pick and choose any combination of post types by selecting the check box next to it).
6. Selecting the Satellite Locations that Webhooks should post to you from. Choosing a location that is geographically close to the host of the URL you selected in step 2 ensures that posts get to your URL quickly and provides the quickest response time from our system, though selecting all 3 locations will provide the highest level of redundancy. The satellite locations are currently Phoenix, AZ, Ashburn, VA, and Amsterdam, the Netherlands.
7. Click Update to save the configuration.

After at least one Webhook has been saved you will be presented with the option to edit, remove, or add more. You may add up to 4 Webhooks, and each may use different URLs if you wish.

Changing Webhooks Versions

Whenever you create a new configuration it will create a configuration that matches the most current version of Webhooks. If you have a configuration that was already created under an older version of Webhooks you will be given the option to upgrade the configuration.

Updating an existing Webhook to change the URL will NOT upgrade an existing configuration to a new version.

Adding a new event to an existing Webhooks configuration created in an older version of Webhooks will result in the newly added event having the current version of that event while all of the events that were in the configuration will continue to use the previous version of the event.

Webhooks IP Ranges

You will receive Webhooks from the following CCBill IP ranges:

• 64.38.212.1 - 64.38.212.254
• 64.38.215.1 - 64.38.215.254
• 64.38.240.1 - 64.38.240.254
• 64.38.241.1 - 64.38.241.254

You can use this information to setup firewall rules or confirm the validity of a Webhook from within your application.

URL Parameters

Webhooks sends 4 URL parameters with posts that are intended to let you know what type of Webhook is contained in the post. The following parameters are sent:

clientAccnum	The Merchant's account number.
clientSubacc	The Merchant subaccount number.
eventType	The Webhook event being sent, such as NewSaleSuccess or Expiration
eventGroupType	The event group that the event type falls in. At this time, only Subscription is a valid option.

The URL Parameters make up the first line in the following Webhooks Post Example.

Webhooks Post Example

URL Encoded Format

POST /webhooks.php?clientAccnum=999999&clientSubacc=9999&eventType=Expiration&eventGroupType=Subscription HTTP/1.1
X-Allowed-Satellites: PHX,ASH,AMS
Content-Type: application/x-www-form-urlencoded
Content-Length: 102
Host: merchanturl.com
User-Agent: Java/1.6.0_03
Via: 1.1 wmq1.ccbill.com:3129 (squid/2.7.STABLE5), 1.0 internal
Cache-Control: max-age=0
Connection: keep-alive

clientAccnum=999999&clientSubacc=9999&subscriptionId=0913024401000012340&timestamp=2013-01-25 03:22:44

JSON Format

POST /webhooks.php?clientAccnum=999999&clientSubacc=9999&eventType=Expiration&eventGroupType=Subscription HTTP/1.1
X-Allowed-Satellites: PHX,ASH,AMS
Content-Type: application/json
Content-Length: 102
Host: merchanturl.com
User-Agent: Java/1.6.0_03
Via: 1.1 wmq1.ccbill.com:3129 (squid/2.7.STABLE5), 1.0 internal
Cache-Control: max-age=0
Connection: keep-alive
{"clientAccnum":"999999","clientSubacc":"9999","subscriptionId":"0913024401000012340","timestamp":"2013-01-25 03:22:44"}

Webhooks Notifications

The following sections detail the notifications that Webhooks can send to your URL and lists the variables that are included in the notification push. The information included in each notification type is included in the last line of the above Webhooks post example.

In the above example, the Webhook being sent is for the Expiration Webhook. For each different Webhook sent, the information sent will be different (based on the eventType parameter in the first line), but the formatting will be the same.

UserReactivation

Supported Formats: URL Encoded, JSON

Variable Name	Description	Data Type (Max Length)	Example Value
subscriptionId	Subscription ID Number.	bigint(20) unsigned	1000000000
transactionId	Transaction identification number.	string	0912191101000000159
price	Product price (as shown on the form).	string	5.95 for 30 days (non‐recurring)
username	Consumer username.	varchar(16)	username1
password	Consumer password.	varchar(30)	mYPaSSw0rD
clientAccnum	CCBill Merchant main account number.	mediumint(6) unsigned	900100
clientSubacc	CCBill Merchant Sub Account Number.	smallint(4) unsigned zerofill	0000
email	Consumer Email address.	varchar(40)	user@randomurl.com
nextRenewalDate	Next billing date for recurring subscriptions.	string	2021-08-20

NewSaleSuccess

Some fields, such as avsResponse and cvv2Response, will not be sent if the associated features have not been configured by Merchant Support.

This event has more than one version. Click the tab for the version you want to view.

NewSaleFailure

Some fields, such as avsResponse and cvv2Response, will not be sent if the associated features have not been configured by Merchant Support.

UpgradeSuccess

Same as NewSaleSuccess but with these additional parameters added. NewSaleSuccess has multiple versions; take care to use the appropriate version of that Webhook when coding for this Webhook.

UpgradeFailure

The same as NewSaleFailure but with these additional parameters added.

Supported Formats: URL Encoded, JSON

Variable Name	Description	Data Type (Max Length)	Example Value
originalSubscriptionId	The Subscription ID associated with the original subscription, before an upgrade, upsale, or cross sale occurred.	string	0912187401000000099
originalClientAccnum	The Merchant Account Number associated with the original subscription, before an upgrade, upsale, or cross sale occurred.	int	900003
originalClientSubacc	The Merchant Sub Account Number associated with the original subscription, before an upgrade, upsale, or cross sale occurred.	short	0005
source	The source of an upgrade, upsale, cross sale, or cancellation.	string	FORM, API, or PHONE

UpSaleSuccess

Same as NewSaleSuccess but with these additional parameters added. NewSaleSuccess has multiple versions; take care to use the appropriate version of that Webhook when coding for this Webhook.

UpSaleFailure

The same as NewSaleFailure but with these additional parameters added. NewSaleFailure has multiple versions; take care to use the appropriate version of that Webhook when coding for this Webhook.

CrossSaleSuccess

The same as NewSaleSuccess but with these additional parameters added. NewSaleSuccess has multiple versions; take care to use the appropriate version of that Webhook when coding for this Webhook.

CrossSaleFailure

The same as NewSaleFailure but with these additional parameters added. NewSaleFailure has multiple versions; take care to use the appropriate version of that Webhook when coding for this Webhook.

Cancellation

Supported Formats: URL Encoded, JSON

Variable Name	Description	Data Type (Max Length)	Example Value
subscriptionId	Subscription ID Number (Approval Post URL only).	bigint(20) unsigned	1000000000
clientAccnum	CCBill Merchant main account number.	mediumint(6) unsigned	900100
clientSubacc	CCBill Merchant Sub Account Number.	smallint(4) unsigned zerofill	0000
timestamp	Time the event occurred.	date	2021‐08‐05 15:18:17
reason	The Reason given for a cancellation, chargeback, refund, or void, if any.	string	Customer Refunded, Proof of cancel, Webmaster, Billed cancel.
source	The source of an upgrade, upsale, cross sale, or cancellation.	string	FORM, API, or PHONE

Expiration

Supported Formats: URL Encoded, JSON

Variable Name	Description	Data Type (Max Length)	Example Value
subscriptionId	Subscription ID Number (Approval Post URL only).	bigint(20) unsigned	1000000000
clientAccnum	CCBill Merchant main account number.	mediumint(6) unsigned	900100
clientSubacc	CCBill Merchant Sub Account Number.	smallint(4) unsigned zerofill	0000
timestamp	Time the event occurred.	date	2021‐08‐05 15:18:17

BillingDateChange

Supported Formats: URL Encoded, JSON

Variable Name	Description	Data Type (Max Length)	Example Value
subscriptionId	Subscription ID Number (Approval Post URL only).	bigint(20) unsigned	1000000000
clientAccnum	CCBill Merchant main account number.	mediumint(6) unsigned	900100
clientSubacc	CCBill Merchant Sub Account Number.	smallint(4) unsigned zerofill	0000
timestamp	Time the event occurred.	date	2021‐08‐05 15:18:17
nextRenewalDate	Next billing date for recurring subscriptions.	string	2021-09-19

CustomerDataUpdate

This Webhook is only triggered when a customer alters their billing information via https://support.ccbill.com/. It will not be triggered when a customer’s login information is altered within the CCBill admin.

This event has more than one version. Click the tab for the version you want to view.

RenewalSuccess (Rebill)

This event has more than one version. Click the tab for the version you want to view.

Renewal Failure (Declined Rebill)

This event has more than one version. Click the tab for the version you want to view.

Chargeback

This event has more than one version. Click the tab for the version you want to view.

Return

This event has more than one version. Click the tab for the version you want to view.

Refund

This event has more than one version. Click the tab for the version you want to view.

Void

This event has more than one version. Click the tab for the version you want to view.

Appendix A: Currency Codes

Currency Numeric Code	Currency Letter Code	Currency Name
036	AUD	Australian Dollar
124	CAD	Canadian Dollar
392	JPY	Japanese Yen
826	GBP	United Kingdom Pound
840	USD	United States Dollar
978	EUR	Euro Member Countries

Appendix B: Decline Codes

Decline Code	Decline Text
1	Website is not available for signup
2	Unable to determine website signup requirements
3	Your card type is not accepted, please try another type of credit card
4	Banking System Error
5	The credit card you entered is not valid
6	Please check to ensure you entered your expiration dateUsed to show individual corresponding yearly, monthly or daily dates for report data. The date function's format is year-month-day; for example, 2002-01-01. correctly
7	Please check to ensure you entered your bank account number correctly
8	Please check to ensure you entered your bank's routing number correctly
9	Banking System Error, please try again
10	Website has invalid pricing
11	Transaction Declined
12	You currently have a subscription and are unable to signup
13	You have already had a free trial
14	You must enter your CVV2 number on the back of your card
15	Your account is currently being processed, please check the website you are joining to see if you have access. If not, please contact support@ecsuite.com
16	Subscription ID Provided is invalid
17	Subscription ID does not exist in system
18	Previous Transaction Attempt in request was declined
19	You are not authorized to signup with the provided credentials
20	No Decline
21	You have already had a trial, please select a normal recurring membership option
22	Error contacting bank, please try again later
23	Invalid Credit Card Provided
24	Transaction Denied by Bank
25	Bank Error
26	Card Processing Setup Incorrect for Merchant
27	System Error, Please Try Again
28	We are unable to process your transaction at this time. Please try again at a later time
29	Card Expired
30	We are unable to bill the telephone number provided for this transaction. Please return to the website and choose an alternate payment method.
31	Insufficient Funds
32	You must provide CVV2 to complete transaction
33	Unable to determine transaction type
34	Error contacting bank, please try again later
35	Card Declined at Pre-Auth SC
36	Unable To Contact Bank
37	We currently do not process for your bank's bin
38	Transaction Refused by Issuing Bank
39	You Have Submitted Too Many Times Today
40	The Card you are using is not accepted by this Merchant
41	Merchant Inactive
42	Incorrect Address Provided
43	We are unable to process your telephone billing transaction because your provider only allows for one charge, per telephone number, per day, and our records show that you have an existing daily charge to this telephone number. Please return to the website and choose an alternative payment method.
44	We're sorry, at this time prepaid cards are not allowed. Please try a different card type.
45	Transaction requires additional approval: please refer to your confirmation e-mail for further instructions.

ChangeLog

Release 1:

Initial Release.

Release 2:

October 30, 2013

• Adds support for versioning:
  • New configurations are always created using current (newest) version.
  • Adding an event to an existing configuration adds the event under the current version no matter the version of existing events.
  • Merchants using prior versions will be presented with option to upgrade to new version in existing configurations.
• Creates a new version of the following events:
  • NewSaleSuccess: Adds paymentAccount field.
  • RenewalSuccess: Adds renewalDate field.
  • RenewalFailure: Adds renewalDate field.
• Creates the following new events:
  • Return: Notifies user when a Check Return is received by CCBill.
• Bug Fixes:
  • Fixes a bug that resulted in incorrect POST of the failureCode, failureReason, and transactionId fields in Cross Sales, Cross Sale API, and Upgrades with specialOffer.
  • Fixes a bug that resulted in incorrect POST of failureCode, failureReason, and transactionId fields for Upsales.
  • Fixes a bug that caused the subscriptionTypeId to be incorrectly sent.

Release 3:

April 24, 2014

• Adds a new variable called flexId to some Webhooks to accomodate and identify sales made using FlexForms (currently in OPEN BETA status). Upgrading your Webhooks to the version that includes this variable will not cause any complications for users that are not a part of the Beta as the field DOES NOT SEND if the purchase was created using current CCBill forms.
  • The addition of this variable affected the following Webhooks:
    • NewSaleSuccess: Adds Version 3
    • NewSaleFailure: Adds Version 2
    • UpSaleSuccess: Because this Webhook is based on NewSaleSuccess notes were added to remind users to reference the correct version of that Webhook when coding for this Webhook.
    • UpSaleFailure: Because this Webhook is based on NewSaleFailure notes were added to remind users to reference the correct version of that Webhook when coding for this Webhook.
    • CrossSaleSuccess: Because this Webhook is based on NewSaleSuccess notes were added to remind users to reference the correct version of that Webhook when coding for this Webhook.
    • CrossSaleFailure: Because this Webhook is based on NewSaleFailure notes were added to remind users to reference the correct version of that Webhook when coding for this Webhook.

Release 4:

April 13, 2017

• Security is improved by adding the support for TLS 1.2 encryption protocol. Highest security standards will provide a more secure environment and promote the safety of customer data.
• Two new variables are added:
  • expDate: merchants are now aware of when a consumer’s card will expire. The notification can then be sent proactively to inform the consumers to update the card information. This will enhance the consumers’ overall experience. The addition of the expDate variable affected the following Webhooks:
    • NewSaleSuccess - this event contains the parameter in version 4.
    • CustomerDataUpdate- this event contains the parameter in version 2.
    • Chargeback - this event contains the parameter in version 2.
    • Refund - this event contains the parameter in version 2.
    • RenewalSuccess - this event contains the parameter in version 3.
    • Void - this event contains the parameter in version 2.
  • last4: merchants can now maintain more complete consumer data by receiving partial payment method information. The parameter will include the last four (4) digits of the credit card number for credit card transactions or the last four digits of the bank account number for check transactions. The addition of the last4 variable affected the following Webhooks:
    • NewSaleSuccess - this event contains the parameter in version 4.
    • CustomerDataUpdate- this event contains the parameter in version 2.
    • Chargeback - this event contains the parameter in version 2.
    • Refund - this event contains the parameter in version 2.
    • RenewalSuccess - this event contains the parameter in version 3.
    • Void - this event contains the parameter in version 2.

Release 5:

May 11, 2017

New parameter bin is added and Merchants can now receive the credit card BIN allowing them better track consumer trends.

• The addition of the bin parameter affected the following Webhooks:
  • NewSaleSuccess - this event contains the parameter in version 5.
  • UpgradeSuccess - this event contains the parameter in version 2.
  • UpSaleSuccess- this event contains the parameter in version 3.
  • CrossSaleSuccess- this event contains the parameter in version 3.
  • CustomerDataUpdate - this event contains the parameter in version 3.
  • Chargeback - this event contains the parameter in version 3.

• The paymentType parameter was added to the following Webhooks:
  • Chargeback - this event contains the parameter in version 3.
  • Return - this event contains the parameter in version 3.
  • Refund - this event contains the parameter in version 3.
  • RenewalSuccess - this event contains the parameter in version 4.
  • RenewalFailure - this event contains the parameter in version 3.
  • Void - this event contains the parameter in version 3.

• The cardType parameter was added to the following Webhooks:
  • Chargeback - this event contains the parameter in version 3.
  • Refund - this event contains the parameter in version 3.
  • RenewalSuccess - this event contains the parameter in version 4.
  • RenewalFailure - this event contains the parameter in version 3.
  • Void - this event contains the parameter in version 3.

Release 6:

June 1, 2017

The following parameters have been added and/or affected these Webhooks and versions:

• The paymentAccount parameter:
  • CustomerDataUpdate - this event contains the parameter in version 4.
  • Chargeback - this event contains the parameter in version 4.
  • Refund - this event contains the parameter in version 4.
  • Return - this event contains the parameter in version 4.
  • RenewalSuccess - this event contains the parameter in version 5.
  • Void - this event contains the parameter in version 4.

• The accountingCurrency parameter:
  • Chargeback - this event contains the updates in all versions.
  • Refund - this event contains the updates in all versions.
  • RenewalSuccess - this event contains the updates in all versions.
  • Void - this event contains the updates in all versions.

• The currency parameter:
  • Chargeback - this event contains the updates in all versions.
  • Refund - this event contains the updates in all versions.
  • Void - this event contains the updates in all versions.

• The billedCurrency parameter:
  • RenewalSuccess - this event contains the updates in all versions.

Release 7:

July 19, 2017

• The ability to receive Webhook data in JSON (JavaScript Object Notation) has been added. The original formatting will be referred to as "URL Encoded"

Release 8:

February 11, 2020

• New threeDSecure parameter has been added and allows Merchants to track 3DS authentication results.
  • The addition of the threeDSecure parameter affected the following Webhooks:
    • NewSaleSuccess - this event contains the parameter in version 6.
    • NewSaleFailure - this event contains the parameter in version 3.