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

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 client ID that the merchant has received upon signing up to use the CCBill RESTful API.
• Merchant Secret: This is the password that was setup for the authentication with the CCBill RESTful 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

Below are the 3 essential steps for charging the consumer using a payment token:

1. Generate the CCBill OAuth Bearer Token

2. Create the Payment Token

3. Charge the Payment Token

The following sequence diagram describes the flow for creating and charging payment tokens without 3DS verification. Click the image to view it in full size.

---

While all of the above steps can be completed by making requests from your backend to our API endpoints, you can also use the CCBill Advanced Widget (JS library) to:

• create the payment tokens
• check whether the 3DS verification is required or not, and
• perform strong customer authentication (SCA) from within the browser

The following sequence diagram describes the flow for creating and charging payment tokens with 3DS verification. Click the image to view it in full size.

---

Creation of the CCBill OAuth token and charging payment tokens are not supported by the CCBill Advanced Widget and must be performed by making API calls from your back-end services.

1. Generate CCBill OAuth Bearer Token

The CCBill RESTful Transaction API uses OAuth 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.

In the first curl example, the -u option automatically encodes the provided credentials into a format compatible with HTTP Basic Authentication.

Alternatively, merchants can manually encode their merchant application ID and secret key using Base64 encoding. The encoded credentials must be included in the request as authorization header parameters, as shown in the second example request.

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?grant_type=client_credentials

Header

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

Authorization: Basic MerchantApplicationID:SecretKey

curl -X POST 'https://api.ccbill.com/ccbill-auth/oauth/token' \
-i -u 'Basic Merchant_Application_ID:Secret_Key' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials'

curl -X POST \
https://api.ccbill.com/ccbill-auth/oauth/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic [base64_encoded_Merchant_ApplicationID:Merchant_Secret]' \
--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' \

2. Create Payment Token (CCBill Advanced Widget)

The CCBill Advanced Widget makes the creation of payment tokens easier by encapsulating the API calls that need to be made into a JavaScript function that can be used from within your web page.

The library is hosted on CCBill's content distribution network (CDN), which makes import into the merchants' websites quick and easy from any location in the world.

The following instructions describe how to set up and use the CCBill 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.3.0/ccbill-advanced-widget.js" as="script"/>
<script type="text/javascript" src="https://js.ccbill.com/v1.3.0/ccbill-advanced-widget.js"></script>

Step 2. Define Field IDs

The Advanced Widget is able to extract the relevant form fields by relying on default ID attributes or by utilizing the data-ccbill custom HTML element attribute. The data-ccbill attribute is recommended as it is less intrusive and provides more flexibility.

When using the custom attribute the correct format is:

Format

<input type="text" data-ccbill="[corresponding field name]" />

When using the default IDs the correct format is:

<input type="text" id="_ccbillId_[corresponding field name]" />

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

data-ccbill	Default IDs
nameOnCard	_ccbillId_nameOnCard
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 (required, recommended hidden field auto-populated by JavaScript)	_ccbillId_ipAddress (required, 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:

PARAMETER	TYPE	DESCRIPTION
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.
clientAccnum	integer (required)	Merchant account number.
clientSubacc	integer (required)	Merchant subaccount number.
clearPaymentInfo	boolean (optional)	An optional flag that will, if set to true, result in clearance of the customer information fields when the createPaymentToken function is called. If null is provided, this will default to false, and the payment information fields will not be cleared. Note: Even though this parameter is optional, this field should be set to 'null' if not used.
clearCustomerInfo	boolean (optional)	An optional flag that will, if set to true, result in clearance of the customer information fields when the createPaymentToken function is called. If null is provided, this will default to false, and the Customer Information fields will not be cleared. Note: Even though this parameter is optional, this field should be set to 'null' if not used.
timeToLive	integer (optional)	The time interval that defines how long the token should be valid (hours).
numberOfUse	integer (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.

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));
   }

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

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

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

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.

In case of any invalid input, the response will include validation errors that were found during input validation.

It may also include any errors that might have happened during the process of payment token generation.

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.

PARAMETER	TYPE	REQUIREMENT
clientAccnum	integer (required)	Merchant account number. A range between 90000 and 999999 and must be a number.
clientSubacc	integer (required)	Merchant subaccount number. A range of 0-9999 and must be a number.
timeToLive	integer (optional)	Has a range of 0-2147483647 and must be a number. If the max value is desired, then leave this out (or pass null).
numberOfUse	integer (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).
cardNum	string (required)	Must be a valid credit card number.
expMonth	string (required)	Card expiration month in mm format. A range of 1-12, is required and must be a number.
expYear	string (required)	Card expiration year in yyyy format. A range of 2018-2100, is required and must be a number.
firstName	string (required)	Customer's first name.
lastName	string (required)	Customer's last name.
address1	string (optional)	Customer's address.
city	string (optional)	Customer's city.
country	string (required)	Customer's country. Must be represented as a two-letter country code as defined in ISO 3166-1.
state	string (optional)	Customer's state. If provided must be a two-letter state code as defined in ISO 3166-2.
postalCode	string (required)	Customer's zip code. Is a valid postal code for the country provided.
phoneNumber	string (optional)	Customer's phone number. If provided, it must be a valid telephone number.
email	string (required)	Customer's email address.
ipAddress	string (required)	Customer's IP address. Valid IPv4 addresses must be provided as a request parameter or through the X-Origin-IP header.

{
  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);

PARAMETER	TYPE	DESCRIPTION
authToken	string (required)	Must be a valid Oauth Token for the provided Merchant Account.
clientAccnum	integer (required)	Merchant account number.
clientSubacc	integer (required)	Merchant subaccount number.

The merchant payment form needs to contain a text input field (hidden if necessary) or select element (hidden if necessary) 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

PARAMETER	TYPE	DESCRIPTION
clientAccnum	integer (required)	Has a range of 900000-999999 and must be a number.
clientSubacc	integer (required)	Has a range of 0-9999 and must be a number.
currencyCode	string (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.

PARAMETER	TYPE	DESCRIPTION
authToken	string (required)	Must be a valid Oauth Token for the provided Merchant Account.
paymentTokenId	string (required)	The payment token ID. A unique string identifying the payment token, must match regular expression <strong><em>[a-zA-Z0-9]+$</em></strong>

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

PARAMETER	TYPE	DESCRIPTION
paymentTokenId	string (required)	Must match regular expression ^[a-zA-Z0-9]+$
currencyCode	string (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.

PARAMETER	TYPE	DESCRIPTION
authToken	string (required)	Must be a valid Oauth Token for the provided Merchant Account.
clientAccnum	number (required)	The clientAccnum value must correspond to the one used in generating the OAuth token and must be a number within the 900000-999999 range.
clientSubacc	number (required)	The clientSubacc value must correspond to the one used in generating the OAuth token and should be a number within the 0-9999 range.
form	string (optional)	A form reference should either be a valid selector or an HTML Form Element that exists on the merchant's web page. Please note that if the formId is not provided, the Widget will find the first form HTML element on the page and assume that that is the payment form.
iframeId	string (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.
paymentTokenId	string (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, clientAccnum, 
clientSubacc);

Example using form

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

Example using iframeId and form

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

Example using all parameters

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

Field Data Validation

PARAMETER	TYPE	DESCRIPTION
paymentTokenId	string (required)	Must match regular expression ^[a-zA-Z0-9]+$
clientAccnum	number (required)	A number within the 900000-999999 range. It must match the value used to create the OAuth token.
clientSubacc	number (required)	A number within the 0-9999 range. It must match the value used to create the OAuth token.
form	string (optional)	A form reference should either be a valid selector or an HTML Form Element that exists on the merchant's web page. If it's not provided, the system will attempt to collect the required SCA inputs from the first HTML form it finds on the page.
iframeId	string (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.

3. Charge Payment Token

After you have generated a new OAuth token, and after you have generated a payment token, you can use those two new tokens to charge the consumer’s credit card.

Charge Payment Token (Without 3DS Authentication)

HTTP Request URL

https://api.ccbill.com/transactions/payment-tokens/{paymentTokenID}

Header

Accept: application/vnd.mcn.transaction-service.api.v.1+json

Request Parameters

PARAMETER	TYPE	DESCRIPTION
clientAccnum	integer (required)	Merchant account number.
clientSubacc	integer (required)	Merchant subaccount number.
initialPrice	float (required)	Initial transaction price.
initialPeriod	integer (required)	The length (in days) of the initial billing period.
currencyCode	string (optional)	Three-digit currency code (ISO 4217 standard) for the currency used in the transaction.
recurringPrice	float (optional)	The amount the consumer will be charged for each recurring bill.
recurringPeriod	integer (optional)	The length of time between rebills.
rebills	integer (optional)	The total number of times the subscription will rebill.
lifeTimeSubscription	boolean (optional)	The presence of this variable with a value of 1 indicates that the transaction is a lifetime subscription.
createNewPaymentToken	boolean (optional)	Return new payment token for subsequent transactions or not.
passThroughInfo	Array[any] (optional)	Key/value pairs that can be passed through to the transaction service and received in the webhook response.

curl -X POST \
  https://api.ccbill.com/transactions/payment-tokens/01047ed6f3b440c7a2ccc6abc1ad0a84 \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsibWNuLXRyYW5zYWN0aW9uLXNlcnZpY2UiLCJtY24tYWRtaW4tc2VydmljZSJdLCJzY29wZSI6WyJjcmVhdGVfdG9rZW4iLCJyZWFkX3Rva2VuIiwiY2hhcmdlX3RvaiwiY3JlYXRlX3Byb2dyYW0iLCJyZWFkX3Byb2dyYW0iLCJjcmVhdGVfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIiwicmVhZF9wcm9ncmFtX3BhcnRpY2lwYXRpb24iLCJtb2RpZnlfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIl0sImV4cCI6MTUzNzM4MDczNiwiYXV0aG9yaXRpZXMiOlsiTUNOX0FQSV9UT0tFTl9DSEFSR0VSIiwiTUNOX0FQSV9UT0tFTl9DUkVBVE9SIiwiTUNOX0FQSV9BRE1JTiJdLCJqdGkiOiI4YzI2Njg1MC00NjMzLTQzZDMtYjZjOC1lNzIyY2ExNjQ1YTUiLCJjbGllbnRfaWQiOiI1MjE3NjhhYTc1OGQxMWU4YWE2YjAwNTA1NjlkMTU4NSJ9.HRYXZFATkIcI2_LJ1W_xo67IfBnbN9atyYNzyHqseLxYUxzgwBsAV5rNqCixKemOrDIeQLBN4jrwRsBIHDpEvshwBC8XmTodDJzpGmMaU9s1r20RV68X0_d1yTgSDke_Of7VCrVmJRbSuDl7AgsfTqQ1J7nWyu9vcIaER93ms-vadser_Ot9Z68_HAmCJL3DCLpdIFq3PYtBMKKKqXbvhfhSZQZD3b6-aewAnBo0VzpvK6tREqw1rv9_73oAvYcW2aHAj79ILr8viWMM40LyDKMMYOYkneg3hJUQsUVeh9WzztYUJKzERYNXje9fYIGN-eofoLvX7OZJ3eXmIfkrfQ' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{ "clientAccnum":900123, "clientSubacc":10, "initialPrice": 9.99, "initialPeriod": 10, "recurringPrice": 15.00, "recurringPeriod": 30, "rebills": 99, "currencyCode": 840, "lifeTimeSubscription": false, "createNewPaymentToken": false, "passThroughInfo": [ { "name": "val1", "value": "val2" } ] }'

var data = JSON.stringify({
  "clientAccnum": 900123,
  "clientSubacc": 10,
  "initialPrice": 9.99,
  "initialPeriod": 10,
  "recurringPrice": 15,
  "recurringPeriod": 30,
  "rebills": 99,
  "currencyCode": 840,
  "lifeTimeSubscription": false,
  "createNewPaymentToken": false,
  "passThroughInfo": [
    {
      "name": "val1",
      "value": "val2"
    }
  ]
});

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/01047ed6f3b440c7a2ccc6abc1ad0a84");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsibWNuLXRyYW5zYWN0aW9uLXNlcnZpY2UiLCJtY24tYWRtaW4tc2VydmljZSJdLCJzY29wZSI6WyJjcVfdG9rZW4iLCJyZWFkX3Rva2VuIiwiY2hhcmdlX3Rva2VuIiwiY3JlYXRlX3Byb2dyYW0iLCJyZWFkX3Byb2dyYW0iLCJjcmVhdGVfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIiwicmVhZF9wcm9ncmFtX3BhcnRpY2lwYXRpb24iLCJtb2RpZnlfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIl0sImV4cCI6MTUzNzM4MDczNiwiYXV0aG9yaXRpZXMiOlsiTUNOX0FQSV9UT0tFTl9DSEFSR0VSIiwiTUNOX0FQSV9UT0tFTl9DUkVBVE9SIiwiTUNOX0FQSV9BRE1JTiJdLCJqdGkiOiI4YzI2Njg1MC00NjMzLTQzZDMtYjZjOC1lNzIyY2ExNjQ1YTUiLCJjbGllbnRfaWQiOiI1MjE3NjhhYTc1OGQxMWU4YWE2YjAwNTA1NjlkMTU4NSJ9.HRYXZFATkIcI2_LJ1W_xo67IfBnbN9atyYNzyHqseLxYUxzgwBsAV5rNqCixKemOrDIeQLBN4jrwRsBIHDpEvshwBC8XmTodDJzpGmMaU9s1r20RV68X0_d1yTgSDke_Of7VCrVmJRbSuDl7AgsfTqQ1J7nWyu9vcIaER93ms-vadser_Ot9Z68_HAmCJL3DCLpdIFq3PYtBMKKKqXbvhfhSZQZD3b6-aewAnBo0VzpvK6tREqw1rv9_73oAvYcW2aHAj79ILr8viWMM40LyDKMMYOYkneg3hJUQsUVeh9WzztYUJKzERYNXje9fYIGN-eofoLvX7OZJ3eXmIfkrfQ");
xhr.setRequestHeader("Cache-Control", "no-cache");

xhr.send(data);

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

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

$request->setBody('{ "clientAccnum":900123, "clientSubacc":10, "initialPrice": 9.99, "initialPeriod": 10, "recurringPrice": 15.00, "recurringPeriod": 30, "rebills": 99, "currencyCode": 840, "lifeTimeSubscription": false, "createNewPaymentToken": false, "passThroughInfo": [ { "name": "val1", "value": "val2" } ] }');

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

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
?>

Decline Response Parameters

Parameter	Type	Description
declineCode	string	The error code pertains to the error that has caused the transaction failure.
declineText	boolean	Description of decline.
denialId	string	Randomly generated GUID.
approved	boolean	Approval status of the transaction.
paymentUniqueId	string	Unique key connected to payment account.
sessionId	string	Unique session ID value for transaction.
subscriptionId	integer	Subscription ID to which the transaction belongs.
newPaymentTokenId	string	New 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

https://api.ccbill.com/transactions/payment-tokens/threeds/{paymentTokenId}

Headers

Accept: application/vnd.mcn.transaction-service.api.v.1+json

Request Parameters

PARAMETER	TYPE	DESCRIPTION
createNewPaymentToken	boolean (optional)	Return new payment token for subsequent transactions or not.
clientAccnum	integer (required)	Merchant account number.
clientSubacc	integer (required)	Merchant subaccount number.
initialPrice	float (required)	Initial transaction price.
initialPeriod	integer (required)	The length (in days) of the initial billing period.
currencyCode	string (optional)	Three-digit currency code (ISO 4217 standard) for the currency used in the transaction.
recurringPrice	float (optional)	The amount the consumer will be charged for each recurring bill.
recurringPeriod	integer (optional)	The length of time between rebills.
rebills	integer (optional)	The total number of times the subscription will rebill.
lifeTimeSubscription	boolean (optional)	The presence of this variable with a value of 1 indicates that the transaction is a lifetime subscription.
createNewPaymentToken	boolean (optional)	Return new payment token for subsequent transactions or not.
passThroughInfo	Array[any] (optional)	Paired information being passed through to the transaction service.
threedsCardToken	string (required)	The encrypted cardToken you receive through the 3DS verification process. As we require only the first 16 characters, trim the string to that length before sending it to the CCBill API. Sending a string longer than 16 characters results in an error. Example value: gjeoB5NdJ1r6p0dG
threedsEci	string (required)	An Electronic Commerce Indicator (ECI). Values: '0', '1', '2', '5', '6', or '7'.
threedsStatus	string (required)	The status of the 3DS verification ('Y', 'N', 'A', etc.)
threedsVersion	string (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
threedsXid	string (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
threedsCavv	string (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
threedsCavvAlgorithm	string (optional/required)	CAVV Algorithm for threeds request. The threedsCavvAlgorithm parameter is required for threedsVersion 1.0.2
threedsDsTransId	string (optional/required)	Directory Server Transaction ID. The threedsDsTransId parameter is required for threedsVersion 2.1.0
threedsAcsTransId	string (optional/required)	Access Control Server Transaction ID. The threedsAcsTransId parameter is required for threedsVersion 2.1.0
threedsSdkTransId	string (optional)	The 3DS vendor's transaction ID.
threedsAuthenticationType	string (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).
threedsAuthenticationValue	string (optional/required)	A digital signature that proves that the transaction has been 3DS verified. The threedsAuthenticationValue parameter is required for threedsVersion 2.1.0
threedsClientTransactionId	string (required)	The parameter is automatically generated by the Advanced Widget. Its purpose is to identify the origin of the 3DS authentication transaction.
threedsSuccess	boolean (required)	Verification of 3DS authentication success or failure.
threedsAmount	integer (optional)	The amount to be charged (same as initialPrice).
threedsCurrency	integer (optional)	The 3-digit currency code for the currency to be used in this transaction. Example value: 840
threedsError	string (optional/required)	Error received from the 3DS vendor during the strong customer authentication process. The parameter is required if no threedsVersion is provided.
threedsErrorDetail	string (optional)	Error details related to the threedsError.
threedsErrorCode	string (optional)	Error code.
threedsResponse	string (optional)	The complete response in case of an error.

Decline Response Parameters

Parameter	Type	Description
errorCode	integer	Error condition value of the transaction.
approved	boolean	Approval status of the transaction.
paymentUniqueId	string	Unique key connected to payment account.
sessionId	string	Unique session ID value for transaction.
subscriptionId	integer	Subscription ID to which the transaction belongs.
newPaymentTokenId	string	New 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

https://api.ccbill.com/payment-tokens/{paymentTokenId}

Header

Accept: application/vnd.mcn.transaction-service.api.v.2+json

Response Parameters

PARAMETER	TYPE	DESCRIPTION
paymentTokenId	string (required)	Complex representation of Payment Token ID.
programParticipationId	integer (required)	The Program connected to the Payment Token.
originalPaymentTokenId	string (optional)	Reference to a previous Token ID.
clientAccnum	integer (required)	Merchant account number.
clientSubacc	integer (required)	Merchant subaccount number.
createdDatetime	datetime-only (required)	Date and time of creation of the Payment Token.
timeToLive	integer (required)	Time for the token to exist (hours).
validNumberOfUse	integer (required)	Total number of times the Payment Token can be used for purchases.
paymentInfoId	string (optional)	Information associated with the payment.
subscriptionId	integer (required)	Identification of the subscription associated with the transaction.

{"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"}

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