This page lists JavaScript methods available for the CCBill Advanced Widget. These methods enable seamless integration of payment processing into web applications.
Below is a detailed reference for each method, including parameters, validation rules, and example responses.
The createPaymentToken() function is the primary method for generating a Payment Token using the CCBill Advanced Widget.
createPaymentToken(authToken,
clientAccnum,
clientSubacc,
clearPaymentInfo?,
clearCustomerInfo?,
timeToLive?,
numberOfUse?): Promise<Response>| NAME | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
| authToken | string | Yes | An OAuth JWT token previously obtained from the CCBill's Authorization Server. |
| clientAccnum | number | Yes | Merchant account number. Should be a number between 100000 and 999999. |
| clientSubacc | number | Yes | Merchant subaccount number. Should be a number between 0 and 9999. |
| clearPaymentInfo | boolean | No | An optional flag that will, if set to true, result in clearance of the payment information related form fields after the createPaymentToken() function is called. If null/undefined is provided, this will default to false, and the payment information related form fields will not be cleared.Note: Even though this parameter is optional, it should be set to null when subsequent parameters are provided. |
| clearCustomerInfo | boolean | No | An optional flag that will, if set to true, result in clearance of the customer information related form fields after the createPaymentToken() function is called. If null/undefined is provided, this will default to false, and the customer information related form fields will not be cleared.Note: Even though this parameter is optional, it should be set to null when subsequent parameters are provided. |
| timeToLive | number | No | The time interval that defines how long the token should be valid (hours). Should be a number between 0 and 2147483647. Note: Even though this parameter is optional, it should be set to null when subsequent parameters are provided. |
| numberOfUse | number | No | Total number of times the Payment Token can be used for purchases. Should be a number between 0 and 2147483647. |
| NAME | REQUIRED | DESCRIPTION |
|---|---|---|
| firstName | Yes | Customer's first name. |
| lastName | Yes | Customer's last name. |
| address1 | No | Customer's billing address. If provided, it should be between 1 and 50 characters long. |
| address2 | No | Customer's address (line 2). If provided, it should be between 1 and 50 characters long. |
| postalCode | Yes | Customer's billing zip code. It should be a valid zip code between 1 and 16 characters long. |
| city | No | Customer's billing city. If provided, it should be between 1 and 50 characters long. |
| state | No | Customer's billing state. If provided, it should be between 1 and 3 characters long. |
| country | Yes | Customer's billing country. If provided, it should be a two-letter country code as defined in ISO 3166-1. |
| Yes | Customer's email. Should be a well-formed email address, max 254 characters long. | |
| phoneNumber | No | Customer's phone number. If provided, it should be a well-formed phone number. |
| ipAddress | No | Customer's IP address. |
| browserHttpUserAgent | No | Browser User-Agent header value. |
| browserHttpAccept | No | Browser Accept header value. |
| browserHttpAcceptEncoding | No | Browser Accept Encoding header value. |
| browserHttpAcceptLanguate | No | Browser Accept Language header value. |
| cardNumber | Yes | A valid credit card number. |
| expMonth | Yes | Credit card expiration month in mm format. Should be a value between 1 and 12. |
| expYear | Yes | Credit card expiration year in yyyy format. Should be a value between current year and 2100. |
| cvv2 | Yes | Card security code. Should be a 3-4 digit value. |
| nameOnCard | Yes | Name displayed on the credit card. Should be between 2 and 45 characters long. |
Promise<Response> - The promise resolves to the Response object that represents the response to your request.
{
"paymentTokenId":"01d2950476214fb6953f8a4ec7006108",
"programParticipationId":null,
"originalPaymentTokenId":null,
"clientAccnum":900684,
"clientSubacc":0,
"createdDatetime":"2025-02-10T13:47:35",
"timeToLive":2147483647,
"validNumberOfUse":2147483647,
"paymentInfoId":null,
"errors":null,
"subscriptionId":"925041101000000183",
"cvv2Response":null,
"avsResponse":null
}[
{
"target":{
"customerFname":"John",
"customerLname":"",
"country":"",
"email":"johndoe@example.com"
},
"message":"CustomerInfoParams.customerLname should not be empty",
"propertyName":"customerLname"
},
{
"target":{
"customerFname":"John",
"customerLname":"",
"country":"",
"email":"johndoe@example.com"
},
"message":"CustomerInfoParams.country must be a valid ISO 3166-1 alpha-2 country code",
"propertyName":"country"
},
{
"target":{
"clientAccnum":"900684",
"clientSubacc":0,
"subscriptionId":"0",
"paymentInfo":{
"creditCardPaymentInfo":{
"cardNum":"4111111111111111",
"cvv2":"999",
"nameOnCard":"John Doe",
"expYear":"2026",
"expMonth":"02"
}
},
"customerInfo":{
"customerFname":"John",
"customerLname":"",
"country":"",
"email":"tihomirl@ccbill.com"
}
},
"message":"PaymentTokenMerchantOnlyVerifyParams.customerInfo should be valid instance",
"propertyName":"customerInfo"
}
]The isScaRequired() function returns whether a customer needs to undergo Strong Customer Authentication during the payment process.
isScaRequired(authToken, clientAccnum, clientSubacc): Promise<Response>| NAME | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
| authToken | string | Yes | An OAuth JWT token previously obtained from the CCBill's Authorization Server. |
| clientAccnum | number | Yes | Merchant account number. Should be a number between 100000 and 999999. |
| clientSubacc | number | Yes | Merchant subaccount number. Should be a number between 0 and 9999. |
| NAME | REQUIRED | DESCRIPTION |
|---|---|---|
| cardNumber | Yes | A valid credit card number. |
| currencyCode | Yes | A three-digit currency code (ISO 4217 standard) for the currency used in the transaction. |
Promise<Response> - The promise resolves to the Response object that represents the response to your request.
true[
{
"target":{
"clientAccnum":"900684",
"clientSubacc":"0",
"bin":"411111",
"last4":"1111",
"currencyCode":""
},
"message":"ThreedsRequiredParams.currencyCode must match regular expression '^\\\\d{3}$'",
"propertyName":"currencyCode"
}
]The isScaRequiredForPaymentToken() function returns whether a customer needs to undergo Strong Customer Authentication (SCA) for a previously created payment token.
isScaRequiredForPaymentToken(authToken, paymentTokenId): Promise<Response>| NAME | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
| authToken | string | Yes | An OAuth JWT token previously obtained from the CCBill's Authorization Server. |
| paymentTokenId | string | Yes | A valid previously procured Payment Token. |
| NAME | REQUIRED | DESCRIPTION |
|---|---|---|
| currencyCode | Yes | A three-digit currency code (ISO 4217 standard) for the currency used in the transaction. |
Promise<Response> - The promise resolves to the Response object that represents the response to your request.
true[
{
"target":{
"clientAccnum":"900684",
"clientSubacc":"0",
"bin":"411111",
"last4":"1111",
"currencyCode":""
},
"message":"ThreedsRequiredParams.currencyCode must match regular expression '^\\\\d{3}$'",
"propertyName":"currencyCode"
}
]The authenticateCustomer() function lets you initiate a Strong Customer Authentication (SCA) flow and obtain 3DS results before initiating a 3DS transaction and calling CCBill's Merchant Connect (RESTful) API endpoint.
authenticateCustomer(authToken,
clientAccnum,
clientSubacc,
form?,
iframeId?,
paymentTokenId?): Promise<Status>| NAME | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
| authToken | string | Yes | An OAuth JWT token previously obtained from the CCBill's Authorization Server. |
| clientAccnum | number | Yes | Merchant account number. Should be a number between 100000 and 999999. |
| clientSubacc | number | Yes | Merchant subaccount number. Should be a number between 0 and 9999. |
| form | string | No | A form reference should either be a valid selector or an HTMLFormElement 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 | No | The SCA flow 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 | No | 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 payment token ID is not provided. |
| NAME | REQUIRED | DESCRIPTION |
|---|---|---|
| amount | Yes | Transaction total. Should be value greater than 0. |
| currencyCode | Yes | A three-digit currency code (ISO 4217 standard) for the currency used in the transaction. |
| address1 | No | Customer's address. If provided, it should be between 1 and 50 characters long. |
| address2 | No | Customer's address (line 2). If provided, it should be between 1 and 50 characters long. |
| address3 | No | Customer's billing address (line 3). If provided, should be between 1 and 50 characters long. |
| postalCode | No | Customer's billing zip code. If provided, it should be a valid zip code between 1 and 16 characters long. |
| city | No | Customer's billing city. If provided, it should be between 1 and 50 characters long. |
| state | No | Customer's billing state. If provided, it should be between 1 and 3 characters long. |
| country | No | Customer's billing country. If provided, it should be a two-letter country code as defined in ISO 3166-1. |
| Yes | Customer's email. Should be a well-formed email address, max 254 characters long. | |
| cardNumber | ? (required if paymentTokenId not provided) | A valid credit card number. |
| expMonth | ? (required if paymentTokenId not provided) | Credit card expiration month in mm format. Should be a value between 1 and 12. |
| expYear | ? (required if paymentTokenId not provided) | Credit card expiration year in yyyy format. Should be a value between current year and 2100. |
| nameOnCard | Yes | Name displayed on the credit card. Should be between 2 and 45 characters long. |
Promise<Response> - The promise resolves to the Response object that represents the response to your request.
{
"eci":"05",
"protocolVersion":"2.2.0",
"cardToken":null,
"scaIndicator":true,
"success":true,
"currency":"978",
"amount":2,
"acsURL":null,
"authenticationValue":"A/2Yn5P/S85DMokJstXn/S+5qgc=",
"authenticationType":null,
"creq":null,
"dsTransId":"526578a3-25bf-40ef-b205-937e16cfd5b5",
"acsTransId":"ca5f9649-b865-47ce-be6f-54422a0fce47",
"challengeWindowURL":null,
"transStatusReason":null,
"transStatusReasonDetail":null,
"status":"Y",
"clientTransactionId":"mcn-id-1721990",
"sdkTransId":"f1af0ee0-e855-11ef-b7ca-0242ac110006"
}{
"errors":[
{
"message":"supplied currency should be a valid ISO 4217 three-digit currency code",
"field":"currencyCode"
},
{
"message":"supplied amount should be a positive number",
"field":"amount"
}
],
"generalMessage":"Validation failed!",
"timestamp":"2025-02-11T08:54:15.657Z"
}
---
{
"status":400,
"statusText":"",
"id":"ffe940ff-2ac2-4509-abb0-6d0dc8169d0d",
"errorCode":200502,
"generalMessage":"Payment token does not exist.",
"url":"/threeds/01a5f7e9a7dd4810a3aa6dbf90e56973/authenticate",
"timestamp":"2025-02-11T09:10:47.026354625Z",
"validationErrors":[],
"clientTransactionId":"mcn-id-2037620"
}The authenticateCustomerAndCreatePaymentToken() function combines Strong Customer Authentication (SCA) and payment token creation in a single call.
authenticateCustomerAndCreatePaymentToken(authToken,
clientAccnum,
clientSubacc,
optionalParameters?): Promise<Status>| NAME | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
| authToken | string | Yes | An OAuth JWT token previously obtained from the CCBill's Authorization Server. |
| clientAccnum | number | Yes | Merchant account number. Should be a number between 100000 and 999999. |
| clientSubacc | number | Yes | Merchant subaccount number. Should be a number between 0 and 9999. |
| optionalParameters | object | No | Object that holds all the optional parameters. |
| Name | Type | Required | Description |
|---|---|---|---|
| form | HTMLFormElement | string | No | A form reference should either be a valid selector or an HTMLFormElement 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 | No | The SCA flow 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. |
| clearPaymentInfo | boolean | No | An optional flag that will, if set to true, result in clearance of the payment information related form fields after the createPaymentToken() function is called. If null/undefined is provided, this will default to false, and the payment information-related form fields will not be cleared. |
| clearCustomerInfo | boolean | No | An optional flag that will, if set to true, result in clearance of the customer information-related form fields after the createPaymentToken() function is called. If null/undefined is provided, this will default to false, and the customer information-related form fields will not be cleared. |
| timeToLive | number | No | The time interval that defines how long the token should be valid (hours). Should be a number between 0 and 2147483647. |
| numberOfUse | number | No | Total number of times the Payment Token can be used for purchases. Should be a number between 0 and 2147483647. |
| NAME | REQUIRED | DESCRIPTION |
|---|---|---|
| amount | Yes | Transaction total. Should be value greater than 0. |
| currencyCode | Yes | A three-digit currency code (ISO 4217 standard) for the currency used in the transaction. |
| firstName | Yes | Customer's first name. |
| lastName | Yes | Customer's last name. |
| address1 | No | Customer's billing address. If provided, it should be between 1 and 50 characters long. |
| address2 | No | Customer's billing address (line 2). If provided, it should be between 1 and 50 characters long. |
| address3 | No | Customer's billing address (line 3). If provided, it should be between 1 and 50 characters long. |
| postalCode | Yes | Customer's zip code. It should be a valid zip code for the provided country between 1 and 16 characters long. |
| city | No | Customer's billing city. If provided, it should be between 1 and 50 characters long. |
| state | No | Customer's billing state. If provided, it should be between 1 and 3 characters long. |
| country | Yes | Customer's billing country. Should be a two-letter country code as defined in ISO 3166-1. |
| Yes | Customer's email. Should be a well-formed email address. | |
| phoneNumber | No | Customer's phone number. If provided, it should be a well-formed phone number. |
| ipAddress | No | Customer's IP address. |
| browserHttpUserAgent | No | Browser User-Agent header value. |
| browserHttpAccept | No | Browser Accept header value. |
| browserHttpAcceptEncoding | No | Browser Accept Encoding header value. |
| browserHttpAcceptLanguate | No | Browser Accept Language header value. |
| cardNumber | Yes | A valid credit card number. |
| expMonth | Yes | Credit card expiration month in mm format. Should be a value between 1 and 12. |
| expYear | Yes | Credit card expiration year in yyyy format. Should be a value between current year and 2100. |
| cvv2 | Yes | Card security code. Should be a 3-4 digit value. |
| nameOnCard | Yes | Name displayed on the credit card. Should be between 2 and 45 characters long.. |
Promise<Response> - The promise resolves to the Response object that represents the response to your request.
{
"threedsInformation":{
"eci":"05",
"protocolVersion":"2.2.0",
"cardToken":null,
"scaIndicator":true,
"success":true,
"currency":"978",
"amount":2,
"acsURL":null,
"authenticationValue":"JZKYoFdJkBI9zmvlfGNgYIOFAMM=",
"authenticationType":null,
"creq":null,
"dsTransId":"e4400a2b-45c2-4c1a-82ed-8bf641005136",
"acsTransId":"ca5f9649-b865-47ce-be6f-54422a0fce47",
"challengeWindowURL":null,
"transStatusReason":null,
"transStatusReasonDetail":null,
"status":"Y",
"clientTransactionId":"mcn-id-3563852",
"sdkTransId":"a4f35ff8-e87a-11ef-b7ca-0242ac110006"
},
"paymentToken":{
"paymentTokenId":"019167f833894394826cdf237ff952d4",
"programParticipationId":null,
"originalPaymentTokenId":null,
"clientAccnum":900684,
"clientSubacc":0,
"createdDatetime":"2025-02-11T13:18:15",
"timeToLive":2147483647,
"validNumberOfUse":2147483647,
"paymentInfoId":null,
"errors":null,
"subscriptionId":"925042201000000120",
"cvv2Response":null,
"avsResponse":null
}
}{
"errors":[
{
"message":"supplied currency should be a valid ISO 4217 three-digit currency code",
"field":"currencyCode"
},
{
"message":"supplied amount should be a positive number",
"field":"amount"
}
],
"generalMessage":"Validation failed!",
"timestamp":"2025-02-11T08:54:15.657Z"
}The createPaymentToken3DS() method authenticates the cardholder (SCA) and creates a payment token. The token can be charged at a later date without undergoing further 3DS checks.
createPaymentToken3DS(authToken,
clientAccnum,
clientSubacc,
optionalParameters?): Promise<Status>| NAME | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
| authToken | string | Yes | An OAuth JWT token previously obtained from the CCBill's Authorization Server. |
| clientAccnum | number | Yes | Merchant account number. Should be a number between 100000 and 999999. |
| clientSubacc | number | Yes | Merchant subaccount number. Should be a number between 0 and 9999. |
| optionalParameters | object | No | Object that holds all the optional parameters. |
| Name | Type | Required | Description |
|---|---|---|---|
| form | HTMLFormElement | string | No | A form reference should either be a valid selector or an HTMLFormElement 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 | No | The SCA flow 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. |
| clearPaymentInfo | boolean | No | An optional flag that will, if set to true, result in clearance of the payment information related form fields after the createPaymentToken() function is called. If null/undefined is provided, this will default to false, and the payment information-related form fields will not be cleared. |
| clearCustomerInfo | boolean | No | An optional flag that will, if set to true, result in clearance of the customer information-related form fields after the createPaymentToken() function is called. If null/undefined is provided, this will default to false, and the customer information-related form fields will not be cleared. |
| timeToLive | number | No | The time interval that defines how long the token should be valid (hours). Should be a number between 0 and 2147483647. |
| numberOfUse | number | No | Total number of times the Payment Token can be used for purchases. Should be a number between 0 and 2147483647. |
| NAME | REQUIRED | DESCRIPTION |
|---|---|---|
| firstName | Yes | Customer's first name. |
| lastName | Yes | Customer's last name. |
| address1 | No | Customer's billing address. If provided, it should be between 1 and 50 characters long. |
| address2 | No | Customer's billing address (line 2). If provided, it should be between 1 and 50 characters long. |
| address3 | No | Customer's billing address (line 3). If provided, it should be between 1 and 50 characters long. |
| postalCode | Yes | Customer's zip code. It should be a valid zip code for the provided country between 1 and 16 characters long. |
| city | No | Customer's billing city. If provided, it should be between 1 and 50 characters long. |
| state | No | Customer's billing state. If provided, it should be between 1 and 3 characters long. |
| country | Yes | Customer's billing country. Should be a two-letter country code as defined in ISO 3166-1. |
| Yes | Customer's email. Should be a well-formed email address. | |
| phoneNumber | No | Customer's phone number. If provided, it should be a well-formed phone number. |
| ipAddress | No | Customer's IP address. |
| browserHttpUserAgent | No | Browser User-Agent header value. |
| browserHttpAccept | No | Browser Accept header value. |
| browserHttpAcceptEncoding | No | Browser Accept Encoding header value. |
| browserHttpAcceptLanguate | No | Browser Accept Language header value. |
| cardNumber | Yes | A valid credit card number. |
| expMonth | Yes | Credit card expiration month in mm format. Should be a value between 1 and 12. |
| expYear | Yes | Credit card expiration year in yyyy format. Should be a value between current year and 2100. |
| cvv2 | Yes | Card security code. Should be a 3-4 digit value. |
| nameOnCard | Yes | Name displayed on the credit card. Should be between 2 and 45 characters long. |
Promise<Response> - The promise resolves to the Response object that represents the response to your request.
{
"paymentTokenId":"01d2950476214fb6953f8a4ec7006108",
"programParticipationId":null,
"originalPaymentTokenId":null,
"clientAccnum":900684,
"clientSubacc":0,
"createdDatetime":"2025-02-10T13:47:35",
"timeToLive":2147483647,
"validNumberOfUse":2147483647,
"paymentInfoId":null,
"errors":null,
"subscriptionId":"925041101000000183",
"cvv2Response":null,
"avsResponse":null
}{
"error":{
"errors":[
{
"message":"supplied cardNumber should be a valid credit card number",
"field":"cardNumber"
}
],
"generalMessage":"Validation failed!",
"timestamp":"2025-02-11T13:39:42.861Z"
}
}Additional Documentation