Technical Guide for Creating and Charging Payment Tokens

This technical guide outlines the steps for creating and charging payment tokens using CCBill's Transaction RESTful API service.

It is intended for programmers, technicians, and others with advanced coding skills.

Requirements

  • The user has a CCBill Account.
  • The user has been given API credentials.
  • The user has had their origin request IP whitelisted.
  • The user possesses intermediate to advanced programming skills.
  • User has experience with HTTP/1.1.
  • User has experience with RESTful Web Services.
  • User has experience with JSON formats.
  • The RESTful Transaction API supports TLS 1.2 only.

Terminology

  • Merchant Account: Each CCBill merchant receives an account number for tracking purposes. The standard format is 9xxxxx-xxxx, where 9xxxxx is the main account. The main account is a six (6) digit number. For example: "999999".
  • Merchant Sub-account: CCBill Merchants may open one or more sub-accounts. The sub-account is a four (4) digit number. The standard format is: xxxx. For example: "1234". The sub-account is part of the main account.
  • Payment Token: A Payment Token identifies a billable entity within the system.
  • Subscription ID: Transaction subscription identification number
  • Merchant Application ID: This is the username that was set up for authentication of this API.
  • Merchant Secret: This is the password that was set up for authentication of this API.
  • Strong Customer Authentication (SCA): European laws (PSD2) require the use of SCA, such as the 3DS protocol, for online payment processing. SCA is initiated when an EU-based cardholder makes a payment online. Merchants can use CCBill's Advanced Widget and its functions to facilitate strong customer authentication.

The Payment Flow

When using the CCBill RESTful API, there are 4 requests for CCBill to capture a consumer’s card information and charge their credit card. Below is the sequence of requests that need to take place to charge a consumer’s credit card.

  1. Generate Frontend Bearer Token
  2. Create Payment Token ID
  3. Generate Backend Bearer Token
  4. Charge Payment Token ID

Generate Frontend Bearer Token

The CCBill RESTful Transaction API uses bearer token-based authentication and authorization. Before accessing the API, you must register your application with CCBill to receive a merchant application ID and secret key.

Use these credentials to generate a token by providing them to the authorization server.

Once you have generated an access token (not to be confused with a payment token), provide it in the Authorization header of each API request. You will have access until the access token expires or is revoked.

EndPoint URL

https://api.ccbill.com/ccbill-auth/oauth/token

Header

Content-Type: application/x-www-form-urlencoded

Authorization: Basic Merchant_ApplicationID:Merchant_Secret

Example Request

curl -X POST \

https://api.ccbill.com/ccbill-auth/oauth/token \

--header 'Content-Type: application/x-www-form-urlencoded' \

--header 'Authorization: Basic 34618470599e11eabb010050569d23bb:JQX7mwuiaVRmBn0b9K9wfPska' \

--data-urlencode 'grant_type=client_credentials'

The acquired token is a random data string that does not hold sensitive information or value. It is an authentication and authorization tool that grants your applications access to CCBill's RESTful API resources.

Example of Bearer Token in Request Header

  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsibWNuLXRyYW5zYWN0aW9uLXNlcnZpY2UiLCJtY24tYWRtaW4tc2VydmljZSJdLCJzY29wZSI6WyJjcmVhdGVfdG9rZW4iLCJyZWFkX3Rva2VuIiwiY2hhcmdlX3Rva2VuIiwiY3JlYXRlX3Byb2dyYW0iLCJyZWFkX3Byb2dyYW0iLCJjcmVhdGVfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIiwicmVhZF9wcm9ncmFtX3BhcnRpY2lwYXRpb24iLCJtb2RpZnlfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIl0sImV4cCI6MTUzNzM4MDczNiwiYXV0aG9yaXRpZXMiOlsiTUNOX0FQSV9UT0tFTl9DSEFSR0VSIiwiTUNOX0FQSV9UT0tFTl9DUkVBVE9SIiwiTUNOX0FQSV9BRE1JTiJdLCJqdGkiOiI4YzI2Njg1MC00NjMzLTQzZDMtYjZjOC1lNzIyY2ExNjQ1YTUiLCJjbGllbnRfaWQiOiI1MjE3NjhhYTc1OGQxMWU4YWE2YjAwNTA1NjlkMTU4NSJ9.HRYXZFATkIcI2_LJ1W_xo67IfBnbN9atyYNzyHqseLxYUxzgwBsAV5rNqCixKemOrDIeQLBN4jrwRsBIHDpEvshwBC8XmTodDJzpGmMaU9s1r20RV68X0_d1yTgSDke_Of7VCrVmJRbSuDl7AgsfTqQ1J7nWyu9vcIaER93ms-vadser_Ot9Z68_HAmCJL3DCLpdIFq3PYtBMKKKqXbvhfhSZQZD3b6-aewAnBo0VzpvK6tREqw1rv9_73oAvYcW2aHAj79ILr8viWMM40LyDKMMYOYkneg3hJUQsUVeh9WzztYUJKzERYNXje9fYIGN-eofoLvX7OZJ3eXmIfkrfQ' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Create Payment Token ID (CCBill Advanced Widget)

The CCBill Advanced Widget enables merchants to automate payment token requests. Merchants can design their own interface to call the widget and generate payment tokens.

The JavaScript widget is hosted in a location accessible to merchants allowing them to reference and import the widget into their websites.

The following instructions describe how to set up and use the Advanced Widget library.

Step 1. Add Preload Link and HTML Elements

Add a preload link and script HTML elements to the client HTML page that will connect to the CCBill Advanced Widget.

<link rel="preload" href="https://js.ccbill.com/v1.2.2/ccbill-advanced-widget.js" as="script"/>
<script type="text/javascript" src="https://js.ccbill.com/v1.2.2/ccbill-advanced-widget.js"></script>

The API version in this URI example is v1.2.2. Pay special attention to the version in the URI path as the version number may be subject to change.

Step 2. Define Field IDs

The Advanced Widget library knows how to extract the relevant form values by relying on default ID attributes or utilizing the data-ccbill attribute. The data-ccbill attribute is recommended as it is less intrusive and provides more flexibility. The correct format is:

Format

data-ccbill='corresponding field'

The table shows the values that should be set for the data-ccbill attribute or, alternatively, in the default ID attribute fields.

data-ccbillDefault IDs
cardNumber_ccbillId_cardNumber
expMonth_ccbillId_expMonth
expYear_ccbillId_expYear
firstName_ccbillId_firstName
lastName_ccbillId_lastName
address1 (optional)_ccbillId_address1 (optional)
address2 (optional)_ccbillId_address2 (optional)
city (optional)_ccbillId_city (optional)
country_ccbillId_country
state (optional) _ccbillId_state (optional)
postalCode_ccbillId_postalCode
phoneNumber (optional)_ccbillId_phoneNumber (optional)
email_ccbillId_email
currencyCode (A three-digit currency code for the currency used in the transaction. Required for SCA.)_ccbillId_currencyCode (A three-digit currency code for the currency used in the transaction. Required for SCA.)
ipAddress (optional, recommended hidden field auto-populated by JavaScript)_ccbillId_ipAddress (optional, recommended hidden field auto-populated by JavaScript)
browserHttpAccept (optional, recommended hidden field auto-populated by JavaScript)_ccbillId_browserHttpAccept (optional, recommended hidden field auto-populated by JavaScript)
browserHttpAcceptEncoding (optional, recommended hidden field auto-populated by javascript)_ccbillId_browserHttpAcceptEncoding (optional, recommended hidden field auto-populated by javascript)
browserHttpAcceptLanguage (optional, recommended hidden field auto-populated by javascript)_ccbillId_browserHttpAcceptLanguage (optional, recommended hidden field auto-populated by javascript)

Step 3. Create JavaScript Method

Create a JavaScript method that will call the CCBill Advanced Widget createPaymentToken() function. The provided example can be modified as required.

This is the main function that Merchants need to incorporate into their JavaScript calls in order to create Payment Tokens.

To generate a token, multiple parameters need to be passed using the function:

PARAMETERTYPEDESCRIPTION
authToken
string
(required)
Required input that uses an Oauth token to perform the creation of the Payment Token. This must be a valid Oauth Token for the client account provided.
clientAccnuminteger
(required)
Merchant account number.
clientSubaccinteger
(required)
Merchant subaccount number.
clearPaymentInfoboolean
(optional)
Optional input that will clear the Payment Information fields when the createPaymentToken function is called. This will default to not clearing the Payment Information fields.

Note: Even though this parameter is optional, this field should be set to 'null' if not used.
clearCustomerInfoboolean
(optional)
Optional input that will clear the Customer Information fields when the createPaymentToken function is called. This will default to not clearing the Customer Information fields.

Note: Even though this parameter is optional, this field should be set to 'null' if not used.
timeToLiveinteger
(optional)
Time for the token to exist.
numberOfUseinteger
(optional)
Total number of times the Payment Token can be used for purchases.

Note: Even though this parameter is optional, this field should be set to 'null' if not used.

createPaymentToken() Example

const widget = new ccbill.CCBillAdvancedWidget(applicationId);
try {
       const result = widget.createPaymentToken(oauthToken, clientAccnum, clientSubacc, clearPaymentInfo, clearCustomerInfo, timeToLive, numberOfUse);
       result.then(
           (data) => {
               console.log("SUCCESS");
               return data.json();
           },
           (error) => {
               console.log("ERROR");
               return error.json();
           }).then(json => {                
               console.log("RESULT :[" + JSON.stringify(json) + "]");
           }).catch((error) => {
           console.error("ERROR2 [" + error + "]");
       });
       console.log(`FINISHED`);
   } catch (error) {
       const errors = [];
       error.forEach(function(item) {
         const msg = item.message.split(".");
         errors.push(msg[1]);
       });
       console.error(`ERROR ` + JSON.stringify(errors));
       alert("ERROR: Unable to generate Payment Token: " + JSON.stringify(errors));
   }

Using Only Required Parameters

const result = widget.createPaymentToken(oauthToken, clientAccnum, clientSubacc);

Using Field Clearing Flags

const result = widget.createPaymentToken(oauthToken, clientAccnum, clientSubacc, clearPaymentInfo, clearCustomerInfo);

Using numberOfUse and timeToLive but no Flags

const result = widget.createPaymentToken(oauthToken, clientAccnum, clientSubacc, null, null, timeToLive, numberOfUse);

Using All Parameters

const result = widget.createPaymentToken(oauthToken, clientAccnum, clientSubacc, clearPaymentInfo, clearCustomer, timeToLive, numberOfUse);

Step 4. Payment Token Generated

The result will contain the newly created payment token, which can be stringified into JSON.

It may also contain validation violations that occurred on the data being passed from the form or indicate any errors that might have happened while generating the Payment Token.

Field Data Validation

The createPaymentToken function will validate field values. If any of the values do not pass validation, no token will be created. If that is the case, the system will generate a violations array indicating which fields are invalid.

PARAMETERTYPEREQUIREMENT
clientAccnuminteger
(required)
Merchant account number.
clientSubaccinteger
(required)
Merchant subaccount number.
timeToLiveinteger
(optional)
Time for the token to exist. Has a range of 0-2147483647 and must be a number. If the max value is desired, then leave this out (or pass null).
numberOfUseinteger
(optional)
The total number of times the Payment Token can be used for purchases. Has a range of 0-2147483647 and must be a number. If the max value is desired, then leave this out (or pass null).
cardNumstring
(required)
Must be a valid credit card number.
expMonthstring
(required)
Card expiration month in mm format.
expYearstring
(required)
Card expiration year in yyyy format.
customerFnamestring
(required)
Customer's first name.
customerLnamestring
(required)
Customer's last name.
address1string
(required)
Customer's address.
citystring
(required)
Customer's city.
countrystring
(required)
Customer's country.
statestring
(required)
Customer's state. Required ("XX" if not available).
zipcodestring
(required)
Customer's zip code. Is a valid postal code for the country provided.
phoneNumberstring
(optional)
Customer's phone number. If provided, it must be a valid telephone number.
emailstring
(required)
Customer's email address.
ipAddressstring
(required)
Customer's IP address.

The violations array is an object of the following object:

{
  target: Object,
  message: string,
  propertyName: string
}

At this time, the Client Page will need to either resolve any errors, display the right message on which fields were invalid, or use the new payment token provided.

Strong Customer Authentication

The CCBill Advanced Widget also enables merchants to integrate with CCBill's 3DS vendor and incorporate strong customer authentication in their transactions.

Alternatively, merchants can send SCA (3DS) results obtained from a 3DS vendor of their choice. To initiate charges using a payment token the SCA parameters need to be submitted along with other required parameters.

isScaRequired Function

The isScaRequired function determines whether strong customer authentication is needed. The system checks the provided credit card number, merchant account number, subaccount number, and currency code.

A valid input results in a Promise, that will eventually resolve to a response with SCA parameters or will turn into a rejection, due to an error.

Example

const result = widget.isScaRequired(authToken, clientAccnum, clientSubacc);
PARAMETERTYPEDESCRIPTION
authTokenstring
(required)
Must be a valid Oauth Token for the provided Merchant Account.
clientAccnuminteger
(required)
Merchant account number.
clientSubaccinteger
(required)
Merchant subaccount number.

The merchant payment form needs to contain a text input field or select element for the currencyCode value. The value represents a three-digit currency code (ISO 4217 standard) for the currency used in the transaction.

The Advanced Widget will automatically collect the currencyCode value if it follows standard naming conventions. Merchants can:

  • Use the default ID attribute.
  • Specify the currency code ID using the library.
  • Utilize the data-ccbill attribute to specify the currency code field.

data-ccbill attribute example (input)

<input data-ccbill=”currencyCode” type=”text” />

data-ccbill attribute example (select)

<select data-ccbill=”currencyCode” />

<option>…</option>
<option>…</option>
…

</select>

Default _ccbillId_currencyCode attribute example (input)

<input id=“_ccbillId_currencyCode” type=”text” />

Default _ccbillId_currencyCode attribute example (select)

<select id=“_ccbillId_currencyCode” />

<option>…</option>
<option>…</option>
…

</select>

Field Data Validation

PARAMETERTYPEDESCRIPTION
clientAccnuminteger
(required)
Has a range of 900000-999999 and must be a number.
clientSubaccinteger
(required)
Has a range of 0-9999 and must be a number.
currencyCodeinteger
(required)
Has to match regular expression ^\\d{3}$
Credit Card Number (form input)integer
(required)
Must be a valid credit card number.

The violations object is an array of the following object:

{
  target: Object,
  message: string,
  propertyName: string
}
isScaRequiredForPaymentToken Function

The isScaRequiredForPaymentToken function determines whether strong customer authentication is required based on the provided payment token ID and currency code.

A valid input results in a Promise, that will eventually resolve to a response with SCA parameters or will turn into a rejection, due to an error.

PARAMETERTYPEDESCRIPTION
authTokenstring
(required)
Must be a valid Oauth Token for the provided Merchant Account.
paymentTokenIdstring
(required)
The payment token ID.

Example

const result = widget.isScaRequiredForPaymentToken(authToken, paymentTokenId);

The merchant payment form needs to contain a text input field or select element for the currencyCode value. The value represents a three-digit currency code (ISO 4217 standard) for the currency used in the transaction.

The Advanced Widget will automatically collect the currencyCode value if it follows standard naming conventions. Merchants can:

  • Use the default ID attribute.
  • Specify the currency code ID using the library.
  • Utilize the data-ccbill attribute to specify the currency code field.

data-ccbill attribute example (input)

<input data-ccbill=”currencyCode” type=”text” />

data-ccbill attribute example (select)

<select data-ccbill=”currencyCode” />

<option>…</option>
<option>…</option>
…

</select>

Default _ccbillId_currencyCode attribute example (input)

<input id=“_ccbillId_currencyCode” type=”text” />

Default _ccbillId_currencyCode attribute example (select)

<select id=“_ccbillId_currencyCode” />

<option>…</option>
<option>…</option>
…

</select>

Field Data Validation

PARAMETERTYPEDESCRIPTION
paymentTokenIdstring
(required)
Must match regular expression ^[a-zA-Z0-9]+$
currencyCodeinteger
(required)
Has to match regular expression ^\\d{3}$

The violations object is an array of the following object:

{
  target: Object,
  message: string,
  propertyName: string
}
authenticateCustomer Function

The authenticateCustomer function enables merchants to obtain the customer authentication result before initiating a 3DS transaction and calling CCBill's Merchant Connect (RESTful) API endpoint. If the call fails, it is going to return an error.

Several parameters need to be passed to facilitate a strong customer authentication.

PARAMETERTYPEDESCRIPTION
authTokenstring
(required)
Must be a valid Oauth Token for the provided Merchant Account.
formstring
(optional)
A form reference should either be a valid selector or an HTML Form Element that exists on the merchant's web page.
iframeIdstring
(optional)
The 3DS authentication process presents an iframe on the web page to perform its functionality. The Advanced Widget script generates an iframe and injects it into the merchant's web page if the parameter is undefined. If the provided value is null or an empty string, it is regenerated to fit the minimum technical requirements.
paymentTokenIdstring
(optional)
Use this optional field instead of the card number, card expiry month, and card expiry year. The card information must be present in the associated HTML form if the token ID is not provided.

Example using only required parameters

const result = widget.authenticateCustomer(authToken);

Example using form

const result = widget.authenticateCustomer(authToken, form);

Example using iframeId and form

const result = widget.authenticateCustomer(authToken, form, iframeId);

Example using all parameters

const result = widget.authenticateCustomer(authToken, form, iframeId, paymentTokenId);

Field Data Validation

PARAMETERTYPEDESCRIPTION
paymentTokenIdstring
(required)
Must match regular expression ^[a-zA-Z0-9]+$
formstring
(optional)
A form reference should either be a valid selector or an HTML Form Element that exists on the merchant's web page.
iframeIdstring
(optional)
The 3DS authentication process presents an iframe on the web page to perform its functionality. The Advanced Widget script generates an iframe and injects it into the merchant's web page if the parameter is undefined. If the provided value is null or an empty string, it is regenerated to fit the minimum technical requirements.

Visit the 3DS Authentication Error Codes page for a comprehensive list of error codes.

Charge Payment Token ID

After you have generated a new bearer token using the second set of credentials and have generated a payment token ID, you’ll then use those two new tokens to charge the consumer’s credit card.

Charge Payment Token (Without 3DS Authentication)

HTTP Request URL
Header
Accept: application/vnd.mcn.transaction-service.api.v.1+json
Request Parameters
PARAMETERTYPEDESCRIPTION
clientAccnuminteger
(required)
Merchant account number.
clientSubaccinteger
(required)
Merchant subaccount number.
initialPricefloat
(required)
Initial transaction price.
initialPeriodinteger
(required)
The length (in days) of the initial billing period.
recurringPricefloat
(optional)
The amount the consumer will be charged for each recurring bill.
recurringPeriodinteger
(optional)
The length of time between rebills.
rebillsinteger
(optional)
The total number of times the subscription will rebill.
currencyCodeinteger
(optional)
Three-digit currency code (ISO 4217 standard) for the currency used in the transaction.
lifeTimeSubscriptionboolean
(optional)
The presence of this variable with a value of 1 indicates that the transaction is a lifetime subscription.
createNewPaymentTokenboolean
(optional)
Return new payment token for subsequent transactions or not.
passThroughInfoArray[any]
(optional)
Paired information being passed through to the transaction service.

cURL

curl -X POST \
  https://api.ccbill.com/payment-tokens/merchant-only \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsibWNuLXRyYW5zYWN0aW9uLXNlcnZpY2UiLCJtY24tYWRtaW4tc2VydmljZSJdLCJzY29wZSI6WyJjcmVhdGVfdG9rZW4iLCJyZWFkX3Rva2VuIiwiY2hhcmdlX3Rva2VuIiwiY3JlYXRlX3Byb2dyYW0iLCJyZWFkX3Byb2dyYW0iLCJjcmVhdGVfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIiwicmVhZF9wcm9ncmFtX3BhcnRpY2lwYXRpb24iLCJtb2RpZnlfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIl0sImV4cCI6MTUzNzM4MDczNiwiYXV0aG9yaXRpZXMiOlsiTUNOX0FQSV9UT0tFTl9DSEFSR0VSIiwiTUNOX0FQSV9UT0tFTl9DUkVBVE9SIiwiTUNOX0FQSV9BRE1JTiJdLCJqdGkiOiI4YzI2Njg1MC00NjMzLTQzZDMtYjZjOC1lNzIyY2ExNjQ1YTUiLCJjbGllbnRfaWQiOiI1MjE3NjhhYTc1OGQxMWU4YWE2YjAwNTA1NjlkMTU4NSJ9.HRYXZFATkIcI2_LJ1W_xo67IfBnbN9atyYNzyHqseLxYUxzgwBsAV5rNqCixKemOrDIeQLBN4jrwRsBIHDpEvshwBC8XmTodDJzpGmMaU9s1r20RV68X0_d1yTgSDke_Of7VCrVmJRbSuDl7AgsfTqQ1J7nWyu9vcIaER93ms-vadser_Ot9Z68_HAmCJL3DCLpdIFq3PYtBMKKKqXbvhfhSZQZD3b6-aewAnBo0VzpvK6tREqw1rv9_73oAvYcW2aHAj79ILr8viWMM40LyDKMMYOYkneg3hJUQsUVeh9WzztYUJKzERYNXje9fYIGN-eofoLvX7OZJ3eXmIfkrfQ' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{ "clientAccnum": 900000, "clientSubacc": 0, "customerInfo": { "customerFname": "Tyler", "customerLname": "Thomas", "address1": "Woodland Drive", "address2": "Apt 21", "city": "Tempe", "state": "AZ", "zipcode": "85281", "country": "US", "phoneNumber": "5555555555", "email": "tthomas@xyz.com", "ipAddress": "10.70.60.14'\''", "browserHttpUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:60.0) Gecko/20100101 Firefox/60.0", "browserHttpAccept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8", "browserHttpAcceptLanguage": "en-US,en;q=0.5", "browserHttpAcceptEncoding": "gzip, deflate, br" }, "paymentInfo": { "creditCardPaymentInfo": { "cardNum": "4473707989493598", "nameOnCard": "Tyler Thomas", "expMonth": "04", "expYear": "2026" } }, "subscriptionId":900000000000000001, "timeToLive": 30, "validNumberOfUse": 3 }'

JavaScript

var data = JSON.stringify({
  "clientAccnum": 900000,
  "clientSubacc": 0,
  "customerInfo": {
    "customerFname": "Tyler",
    "customerLname": "Thomas",
    "address1": "Woodland Drive",
    "address2": "Apt 21",
    "city": "Tempe",
    "state": "AZ",
    "zipcode": "85281",
    "country": "US",
    "phoneNumber": "5555555555",
    "email": "tthomas@xyz.com",
    "ipAddress": "10.70.60.14'",
    "browserHttpUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:60.0) Gecko/20100101 Firefox/60.0",
    "browserHttpAccept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
    "browserHttpAcceptLanguage": "en-US,en;q=0.5",
    "browserHttpAcceptEncoding": "gzip, deflate, br"
  },
  "paymentInfo": {
    "creditCardPaymentInfo": {
      "cardNum": "4473707989493598",
      "nameOnCard": "Tyler Thomas",
      "expMonth": "04",
      "expYear": "2026"
    }
  },
  "subscriptionId": 900000000000000000,
  "timeToLive": 30,
  "validNumberOfUse": 3
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.ccbill.com/payment-tokens/merchant-only");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsibWNuLXRyYW5zYWN0aW9uLXNlcnZpY2UiLCJtY24tYWRtaW4tc2VydmljZSJdLCJzY29wZSI6WyJjcmVhdGVfdG9rZW4iLCJyZWFkX3Rva2VuIiwiY2hhcmdlX3Rva2VuIiwiY3JlYXRlX3Byb2dyYW0iLCJyZWFkX3Byb2dyYW0iLCJjcmVhdGVfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIiwicmVhZF9wcm9ncmFtX3BhcnRpY2lwYXRpb24iLCJtb2RpZnlfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIl0sImV4cCI6MTUzNzM4MDczNiwiYXV0aG9yaXRpZXMiOlsiTUNOX0FQSV9UT0tFTl9DSEFSR0VSIiwiTUNOX0FQSV9UT0tFTl9DUkVBVE9SIiwiTUNOX0FQSV9BRE1JTiJdLCJqdGkiOiI4YzI2Njg1MC00NjMzLTQzZDMtYjZjOC1lNzIyY2ExNjQ1YTUiLCJjbGllbnRfaWQiOiI1MjE3NjhhYTc1OGQxMWU4YWE2YjAwNTA1NjlkMTU4NSJ9.HRYXZFATkIcI2_LJ1W_xo67IfBnbN9atyYNzyHqseLxYUxzgwBsAV5rNqCixKemOrDIeQLBN4jrwRsBIHDpEvshwBC8XmTodDJzpGmMaU9s1r20RV68X0_d1yTgSDke_Of7VCrVmJRbSuDl7AgsfTqQ1J7nWyu9vcIaER93ms-vadser_Ot9Z68_HAmCJL3DCLpdIFq3PYtBMKKKqXbvhfhSZQZD3b6-aewAnBo0VzpvK6tREqw1rv9_73oAvYcW2aHAj79ILr8viWMM40LyDKMMYOYkneg3hJUQsUVeh9WzztYUJKzERYNXje9fYIGN-eofoLvX7OZJ3eXmIfkrfQ");
xhr.setRequestHeader("Cache-Control", "no-cache");

xhr.send(data);

PHP

<?php
$request = new HttpRequest();
$request->setUrl('https://api.ccbill.com/payment-tokens/merchant-only');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'Cache-Control' => 'no-cache',
  'Authorization' => 'Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsibWNuLXRyYW5zYWN0aW9uLXNlcnZpY2UiLCJtY24tYWRtaW4tc2VydmljZSJdLCJzY29wZSI6WyJjcmVhdGVfdG9rZW4iLCJyZWFkX3Rva2VuIiwiY2hhcmdlX3Rva2VuIiwiY3JlYXRlX3Byb2dyYW0iLCJyZWFkX3Byb2dyYW0iLCJjcmVhdGVfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIiwicmVhZF9wcm9ncmFtX3BhcnRpY2lwYXRpb24iLCJtb2RpZnlfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIl0sImV4cCI6MTUzNzM4MDczNiwiYXV0aG9yaXRpZXMiOlsiTUNOX0FQSV9UT0tFTl9DSEFSR0VSIiwiTUNOX0FQSV9UT0tFTl9DUkVBVE9SIiwiTUNOX0FQSV9BRE1JTiJdLCJqdGkiOiI4YzI2Njg1MC00NjMzLTQzZDMtYjZjOC1lNzIyY2ExNjQ1YTUiLCJjbGllbnRfaWQiOiI1MjE3NjhhYTc1OGQxMWU4YWE2YjAwNTA1NjlkMTU4NSJ9.HRYXZFATkIcI2_LJ1W_xo67IfBnbN9atyYNzyHqseLxYUxzgwBsAV5rNqCixKemOrDIeQLBN4jrwRsBIHDpEvshwBC8XmTodDJzpGmMaU9s1r20RV68X0_d1yTgSDke_Of7VCrVmJRbSuDl7AgsfTqQ1J7nWyu9vcIaER93ms-vadser_Ot9Z68_HAmCJL3DCLpdIFq3PYtBMKKKqXbvhfhSZQZD3b6-aewAnBo0VzpvK6tREqw1rv9_73oAvYcW2aHAj79ILr8viWMM40LyDKMMYOYkneg3hJUQsUVeh9WzztYUJKzERYNXje9fYIGN-eofoLvX7OZJ3eXmIfkrfQ',
  'Content-Type' => 'application/json'
));

$request->setBody('{ "clientAccnum": 900000, "clientSubacc": 0, "customerInfo": { "customerFname": "Tyler", "customerLname": "Thomas", "address1": "Woodland Drive", "address2": "Apt 21", "city": "Tempe", "state": "AZ", "zipcode": "85281", "country": "US", "phoneNumber": "5555555555", "email": "tthomas@xyz.com", "ipAddress": "10.70.60.14'", "browserHttpUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:60.0) Gecko/20100101 Firefox/60.0", "browserHttpAccept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8", "browserHttpAcceptLanguage": "en-US,en;q=0.5", "browserHttpAcceptEncoding": "gzip, deflate, br" }, "paymentInfo": { "creditCardPaymentInfo": { "cardNum": "4473707989493598", "nameOnCard": "Tyler Thomas", "expMonth": "04", "expYear": "2026" } }, "subscriptionId":900000000000000001, "timeToLive": 30, "validNumberOfUse": 3 }');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
?>
Decline Response Parameters
ParameterTypeDescription
declineCodestringError condition value of the transaction.
declineTextbooleanDescription of decline.
declineIdstringRandomly generated GUID.
approvedbooleanApproval status of the transaction.
paymentUniqueIdstringUnique key connected to payment account.
sessionIdstringUnique session ID value for transaction.
subscriptionIdintegerSubscription ID to which the transaction belongs.
newPaymentTokenIdstringNew payment token for subsequent transactions.

Example Response

{"declineCode":null,"declineText":null,"denialId":null,"approved":true,"paymentUniqueId":"dG4P1t8dL58pA3rNxE+Phw","sessionId":null,"subscriptionId":121095101000018190,"newPaymentTokenId":null}

Charge Payment Token (With 3DS Authentication)

Endpoint URL
Headers
Accept: application/vnd.mcn.transaction-service.api.v.1+json
Request Parameters
PARAMETERTYPEDESCRIPTION
createNewPaymentTokenboolean
(optional)
Return new payment token for subsequent transactions or not.
clientAccnuminteger
(required)
Merchant account number.
clientSubaccinteger
(required)
Merchant subaccount number.
initialPricefloat
(required)
Initial transaction price.
initialPeriodinteger
(required)
The length (in days) of the initial billing period.
recurringPricefloat
(optional)
The amount the consumer will be charged for each recurring bill.
recurringPeriodinteger
(optional)
The length of time between rebills.
rebillsinteger
(optional)
The total number of times the subscription will rebill.
currencyCodeinteger
(optional)
Three-digit currency code (ISO 4217 standard) for the currency used in the transaction.
lifeTimeSubscriptionboolean
(optional)
The presence of this variable with a value of 1 indicates that the transaction is a lifetime subscription.
createNewPaymentTokenboolean
(optional)
Return new payment token for subsequent transactions or not.
passThroughInfoArray[any]
(optional)
Paired information being passed through to the transaction service.
threedsCardTokeninteger
(required)
The payment card number (PAN).
threedsEcistring
(required)
An Electronic Commerce Indicator (ECI).
Values: '0', '1', '2', '5', '6', or '7'.
threedsStatusstring
(required)
The status of the 3DS verification ('Y', 'N', 'A', etc.)
threedsVersionstring
(required)
The version of the 3DS protocol to be followed for this specific card and transaction.
Available versions are 1.0.2 and 2.1.0
threedsXidstring
(optional/required)
The transaction identifier (XID) is a unique tracking number set by the merchant for 3DS. It is a required parameter for threedsVersion 1.0.2
threedsCavvstring
(optional/required)
A digital signature that proves that the transaction has been 3DS verified. The signature is obtained through a 3DS verification flow and is a required parameter for threedsVersion 1.0.2
threedsCavvAlgorithmstring
(optional/required)
CAVV Algorithm for threeds request. The threedsCavvAlgorithm parameter is required for threedsVersion 1.0.2
threedsDsTransIdstring
(optional/required)
Directory Server Transaction ID. The threedsDsTransId parameter is required for threedsVersion 2.1.0
threedsAcsTransIdstring
(optional/required)
Access Control Server Transaction ID. The threedsAcsTransId parameter is required for threedsVersion 2.1.0
threedsSdkTransIdstring
(optional)
The 3DS vendor's transaction ID.
threedsAuthenticationTypestring
(optional)
A digital signature that proves that the transaction has been 3DS verified. The signature is obtained through a 3DS verification flow (v2.1.0).
threedsAuthenticationValuestring
(optional)
A digital signature that proves that the transaction has been 3DS verified. The signature is obtained through a 3DS verification flow (v2.1.0).
threedsClientTransactionIdstring
(required)
The parameter is automatically generated by the Advanced Widget. Its purpose is to identify the origin of the 3DS authentication transaction.
threedsSuccessboolean
(optional)
Verification of 3DS authentication success or failure.
threedsAmountinteger
(optional)
The amount to be charged (same as initialPrice).
threedsCurrencyinteger
(optional)
The 3-digit currency code for the currency to be used in this transaction.
Example value: 840
threedsErrorstring
(optional/required)
Error received from the 3DS vendor during the strong customer authentication process. The parameter is required if no threedsVersion is provided.
threedsErrorDetailstring
(optional)
Error details related to the threedsError.
threedsErrorCodestring
(optional)
Error code.
threedsResponsestring
(optional)
The complete response in case of an error.

cURL

curl -X POST \
  https://api.ccbill.com/transactions/payment-tokens/threeds/01047ed6f3b440c7a2ccc6abc1ad0a84 \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsibWNuLXRyYW5zYWN0aW9uLXNlcnZpY2UiLCJtY24tYWRtaW4tc2VydmljZSJdLCJzY29wZSI6WyJjcmVhdGVfdG9rZW4iLCJyZWFkX3Rva2VuIiwiY2hhcmdlX3Rva2VuIiwiY3JlYXRlX3Byb2dyYW0iLCJyZWFkX3Byb2dyYW0iLCJjcmVhdGVfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIiwicmVhZF9wcm9ncmFtX3BhcnRpY2lwYXRpb24iLCJtb2RpZnlfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIl0sImV4cCI6MTUzNzM4MDczNiwiYXV0aG9yaXRpZXMiOlsiTUNOX0FQSV9UT0tFTl9DSEFSR0VSIiwiTUNOX0FQSV9UT0tFTl9DUkVBVE9SIiwiTUNOX0FQSV9BRE1JTiJdLCJqdGkiOiI4YzI2Njg1MC00NjMzLTQzZDMtYjZjOC1lNzIyY2ExNjQ1YTUiLCJjbGllbnRfaWQiOiI1MjE3NjhhYTc1OGQxMWU4YWE2YjAwNTA1NjlkMTU4NSJ9.HRYXZFATkIcI2_LJ1W_xo67IfBnbN9atyYNzyHqseLxYUxzgwBsAV5rNqCixKemOrDIeQLBN4jrwRsBIHDpEvshwBC8XmTodDJzpGmMaU9s1r20RV68X0_d1yTgSDke_Of7VCrVmJRbSuDl7AgsfTqQ1J7nWyu9vcIaER93ms-vadser_Ot9Z68_HAmCJL3DCLpdIFq3PYtBMKKKqXbvhfhSZQZD3b6-aewAnBo0VzpvK6tREqw1rv9_73oAvYcW2aHAj79ILr8viWMM40LyDKMMYOYkneg3hJUQsUVeh9WzztYUJKzERYNXje9fYIGN-eofoLvX7OZJ3eXmIfkrfQ' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{"clientAccnum":"901505","clientSubacc":"0","initialPrice":"10.00","initialPeriod":"30","threedsEci":"05","threedsError":"","threedsStatus":"Y","threedsSuccess":"true","threedsVersion":"1.0.2","threedsXid":"aWQteHc4ajJnNGIxZW8gICAgICA=","threedsCavv":"cGFzc3dvcmQxMjM0NTZwYXNzd28=","threedsCavvAlgorithm":"SHA-256","threedsAmount":"10","threedsClientTransactionId":"id-wl9r6duc5zj","threedsCurrency":"USD","threedsSdkTransId":"","threedsAcsTransId":"","threedsDsTransId":"","threedsAuthenticationType":"","threedsCardToken":"4111111111111111","threedsErrorDetail":"","threedsErrorCode":"","threedsResponse":""}'

JavaScript

var data = JSON.stringify({
    "clientAccnum": "901505",
    "clientSubacc": "0",
    "initialPrice": "10.00",
    "initialPeriod": "30",
    "threedsEci": "05",
    "threedsError": "",
    "threedsStatus": "Y",
    "threedsSuccess": "true",
    "threedsVersion": "1.0.2",
    "threedsXid": "aWQteHc4ajJnNGIxZW8gICAgICA=",
    "threedsCavv": "cGFzc3dvcmQxMjM0NTZwYXNzd28=",
    "threedsCavvAlgorithm": "SHA-256",
    "threedsAmount": "10",
    "threedsClientTransactionId": "id-wl9r6duc5zj",
    "threedsCurrency": "USD",
    "threedsSdkTransId": "",
    "threedsAcsTransId": "",
    "threedsDsTransId": "",
    "threedsAuthenticationType": "",
    "threedsCardToken": "4111111111111111",
    "threedsErrorDetail": "",
    "threedsErrorCode": "",
    "threedsResponse": ""
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.ccbill.com/transactions/payment-tokens/threeds/01047ed6f3b440c7a2ccc6abc1ad0a84");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsibWNuLXRyYW5zYWN0aW9uLXNlcnZpY2UiLCJtY24tYWRtaW4tc2VydmljZSJdLCJzY29wZSI6WyJjcmVhdGVfdG9rZW4iLCJyZWFkX3Rva2VuIiwiY2hhcmdlX3Rva2VuIiwiY3JlYXRlX3Byb2dyYW0iLCJyZWFkX3Byb2dyYW0iLCJjcmVhdGVfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIiwicmVhZF9wcm9ncmFtX3BhcnRpY2lwYXRpb24iLCJtb2RpZnlfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIl0sImV4cCI6MTUzNzM4MDczNiwiYXV0aG9yaXRpZXMiOlsiTUNOX0FQSV9UT0tFTl9DSEFSR0VSIiwiTUNOX0FQSV9UT0tFTl9DUkVBVE9SIiwiTUNOX0FQSV9BRE1JTiJdLCJqdGkiOiI4YzI2Njg1MC00NjMzLTQzZDMtYjZjOC1lNzIyY2ExNjQ1YTUiLCJjbGllbnRfaWQiOiI1MjE3NjhhYTc1OGQxMWU4YWE2YjAwNTA1NjlkMTU4NSJ9.HRYXZFATkIcI2_LJ1W_xo67IfBnbN9atyYNzyHqseLxYUxzgwBsAV5rNqCixKemOrDIeQLBN4jrwRsBIHDpEvshwBC8XmTodDJzpGmMaU9s1r20RV68X0_d1yTgSDke_Of7VCrVmJRbSuDl7AgsfTqQ1J7nWyu9vcIaER93ms-vadser_Ot9Z68_HAmCJL3DCLpdIFq3PYtBMKKKqXbvhfhSZQZD3b6-aewAnBo0VzpvK6tREqw1rv9_73oAvYcW2aHAj79ILr8viWMM40LyDKMMYOYkneg3hJUQsUVeh9WzztYUJKzERYNXje9fYIGN-eofoLvX7OZJ3eXmIfkrfQ");
xhr.setRequestHeader("Cache-Control", "no-cache");

xhr.send(data);

PHP

<?php
$request = new HttpRequest();
$request->setUrl('https://api.ccbill.com/transactions/payment-tokens/threeds/01047ed6f3b440c7a2ccc6abc1ad0a84');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'Cache-Control' => 'no-cache',
  'Authorization' => 'Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsibWNuLXRyYW5zYWN0aW9uLXNlcnZpY2UiLCJtY24tYWRtaW4tc2VydmljZSJdLCJzY29wZSI6WyJjcmVhdGVfdG9rZW4iLCJyZWFkX3Rva2VuIiwiY2hhcmdlX3Rva2VuIiwiY3JlYXRlX3Byb2dyYW0iLCJyZWFkX3Byb2dyYW0iLCJjcmVhdGVfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIiwicmVhZF9wcm9ncmFtX3BhcnRpY2lwYXRpb24iLCJtb2RpZnlfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIl0sImV4cCI6MTUzNzM4MDczNiwiYXV0aG9yaXRpZXMiOlsiTUNOX0FQSV9UT0tFTl9DSEFSR0VSIiwiTUNOX0FQSV9UT0tFTl9DUkVBVE9SIiwiTUNOX0FQSV9BRE1JTiJdLCJqdGkiOiI4YzI2Njg1MC00NjMzLTQzZDMtYjZjOC1lNzIyY2ExNjQ1YTUiLCJjbGllbnRfaWQiOiI1MjE3NjhhYTc1OGQxMWU4YWE2YjAwNTA1NjlkMTU4NSJ9.HRYXZFATkIcI2_LJ1W_xo67IfBnbN9atyYNzyHqseLxYUxzgwBsAV5rNqCixKemOrDIeQLBN4jrwRsBIHDpEvshwBC8XmTodDJzpGmMaU9s1r20RV68X0_d1yTgSDke_Of7VCrVmJRbSuDl7AgsfTqQ1J7nWyu9vcIaER93ms-vadser_Ot9Z68_HAmCJL3DCLpdIFq3PYtBMKKKqXbvhfhSZQZD3b6-aewAnBo0VzpvK6tREqw1rv9_73oAvYcW2aHAj79ILr8viWMM40LyDKMMYOYkneg3hJUQsUVeh9WzztYUJKzERYNXje9fYIGN-eofoLvX7OZJ3eXmIfkrfQ',
  'Content-Type' => 'application/json'
));

$request->setBody('{"clientAccnum":"901505","clientSubacc":"0","initialPrice":"10.00","initialPeriod":"30","threedsEci":"05","threedsError":"","threedsStatus":"Y","threedsSuccess":"true","threedsVersion":"1.0.2","threedsXid":"aWQteHc4ajJnNGIxZW8gICAgICA=","threedsCavv":"cGFzc3dvcmQxMjM0NTZwYXNzd28=","threedsCavvAlgorithm":"SHA-256","threedsAmount":"10","threedsClientTransactionId":"id-wl9r6duc5zj","threedsCurrency":"USD","threedsSdkTransId":"","threedsAcsTransId":"","threedsDsTransId":"","threedsAuthenticationType":"","threedsCardToken":"4111111111111111","threedsErrorDetail":"","threedsErrorCode":"","threedsResponse":""}');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
?>
Decline Response Parameters
ParameterTypeDescription
errorCodeintegerError condition value of the transaction.
approvedbooleanApproval status of the transaction.
paymentUniqueIdstringUnique key connected to payment account.
sessionIdstringUnique session ID value for transaction.
subscriptionIdintegerSubscription ID to which the transaction belongs.
newPaymentTokenIdstringNew payment token for subsequent transactions.

Example Response

{
  "errorCode": "integer",
  "approved": "boolean",
  "paymentUniqueId": "string",
  "sessionId": "string",
  "subscriptionId": "integer",
  "newPaymentTokenId": "string"
}

Once the payment token has been charged, a webhooks HTTP POST notification will be triggered so that you may capture the transaction information. This webhooks event will be a “UpSaleSuccess”.

Read Payment Token ID

Use this API call to obtain data on a previously made charge. You will need to identify the charge by the payment token ID and include the ID as an URI element.

Example Request

GET 'https://api.ccbill.com/payment-tokens/{{PAYMENT_TOKEN_ID}}' \

--header 'Authorization: Bearer {{BACKEND_ACCESS_TOKEN}}' \

--header 'Accept: application/vnd.mcn.transaction-service.api.v.2+json'
HTTP Request URL
Header
Accept: application/vnd.mcn.transaction-service.api.v.2+json
Response Parameters
PARAMETERTYPEDESCRIPTION
paymentTokenIdstring
(required)
Complex representation of Payment Token ID.
programParticipationIdinteger
(required)
The Program connected to the Payment Token.
originalPaymentTokenIdstring
(optional)
Reference to a previous Token ID.
clientAccnuminteger
(required)
Merchant account number.
clientSubaccinteger
(required)
Merchant subaccount number.
createdDatetimedatetime-only
(required)
Date and time of creation of the Payment Token.
timeToLiveinteger
(required)
Time for the token to exist (hours).
validNumberOfUseinteger
(required)
Total number of times the Payment Token can be used for purchases.
paymentInfoIdstring
(optional)
Information associated with the payment.
subscriptionIdinteger
(required)
Identification of the subscription associated with the transaction.
cvv2Responsestring
(required)
The result of CVV2 verification.
avsResponsestring
(required)
The result of AVS verification.

Example Response

{"paymentTokenId":"01390f2aae864749a6437e007936529b","programParticipationId":null,"originalPaymentTokenId":null,"clientAccnum":999999,"clientSubacc":0,"createdDatetime":"2021-04-02T23:09:02","timeToLive":30,"validNumberOfUse":3,"paymentInfoId":null,"errors":null,"subscriptionId":"121092501000146223","cvv2Response":M,"avsResponse":M}

Visit the following page for a complete list of CCBill RESTful API Error Codes.