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.
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.
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' \
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.
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.
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-ccbill | Default 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) |
_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) |
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) | 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. |
clearCustomerInfo | boolean (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. |
timeToLive | integer (optional) | Time for the token to exist. |
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. |
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);
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.
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. |
clientSubacc | integer (required) | Merchant subaccount number. |
timeToLive | integer (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). |
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. |
expYear | string (required) | Card expiration year in yyyy format. |
customerFname | string (required) | Customer's first name. |
customerLname | string (required) | Customer's last name. |
address1 | string (required) | Customer's address. |
city | string (required) | Customer's city. |
country | string (required) | Customer's country. |
state | string (required) | Customer's state. Required ("XX" if not available). |
zipcode | 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. |
string (required) | Customer's email address. | |
ipAddress | string (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.
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.
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 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:
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 | integer (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
}
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. |
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:
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 | integer (required) | Has to match regular expression ^\\d{3}$ |
The violations object is an array of the following object:
{
target: Object,
message: string,
propertyName: string
}
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. |
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. |
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);
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
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
paymentTokenId | string (required) | Must match regular expression ^[a-zA-Z0-9]+$ |
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. |
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.
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.
Accept: application/vnd.mcn.transaction-service.api.v.1+json
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. |
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. |
currencyCode | integer (optional) | Three-digit currency code (ISO 4217 standard) for the currency used in the transaction. |
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. |
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;
}
?>
Parameter | Type | Description |
---|---|---|
declineCode | string | Error condition value of the transaction. |
declineText | boolean | Description of decline. |
declineId | 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}
Accept: application/vnd.mcn.transaction-service.api.v.1+json
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. |
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. |
currencyCode | integer (optional) | Three-digit currency code (ISO 4217 standard) for the currency used in the transaction. |
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 | integer (required) | The payment card number (PAN). |
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) | A digital signature that proves that the transaction has been 3DS verified. The signature is obtained through a 3DS verification flow (v2.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 (optional) | 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. |
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;
}
?>
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”.
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'
Accept: application/vnd.mcn.transaction-service.api.v.2+json
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. |
cvv2Response | string (required) | The result of CVV2 verification. |
avsResponse | string (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.