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 line

  $fname = $_POST["customer_fname"]

  will capture the consumer’s first name and assign it to a variable called $fname. The variable $fname can be named anything you choose.
• Using Perl/CGI, the line

  $fname = param("customer_fname")__

  will capture the consumer’s first name and assign it to a variable called $fname. The variable $fname can be named anything you choose.

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:

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

---

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:



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 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

---

NewSaleSuccess

Note: 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

Note: 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.

---

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

<Any Pass-through Key/Values – Prepended with X->

---

Expiration

---

BillingDateChange

---

CustomerDataUpdate

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

---

Appendix B: Decline Codes

---

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.
• Chargeback - this event contains the parameter in version 2.
• Return - 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"

---