{"id":9777,"date":"2025-02-21T09:48:18","date_gmt":"2025-02-21T09:48:18","guid":{"rendered":"https:\/\/ccbill.com\/doc\/?p=9777"},"modified":"2026-03-17T10:59:41","modified_gmt":"2026-03-17T10:59:41","slug":"method-reference","status":"publish","type":"post","link":"https:\/\/ccbill.com\/doc\/method-reference","title":{"rendered":"CCBill Advanced Widget API Reference"},"content":{"rendered":"\n
\n
\n
<\/div>\n\n\n\n

This page lists JavaScript methods available for the CCBill Advanced Widget. These methods enable seamless integration of payment processing into web applications.<\/p>\n\n\n\n

Below is a detailed reference for each method, including parameters, validation rules, and example responses.<\/p>\n\n\n\n

<\/div>\n\n\n\n

Constructor<\/h2>\n\n\n\n
<\/div>\n\n\n\n

Creates an instance of the CCBill Advanced Widget. It binds the widget to your application and optionally maps custom form fields.<\/p>\n\n\n\n

<\/circle><\/circle><\/circle><\/g><\/svg><\/span>
constructor<\/span>(applicationId: string<\/span>,<\/span> customIds<\/span>?:<\/span> Object)<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
<\/div>\n\n\n\n
Parameters<\/h3>\n\n\n\n
<\/div>\n\n\n\n
NAME<\/th>TYPE<\/th>REQUIRED<\/th>DESCRIPTION<\/th><\/tr><\/thead>
applicationId<\/strong><\/td>string<\/td>Yes<\/td>Frontend merchant application ID provided by CCBill.<\/td><\/tr>
customIds<\/strong><\/td>object<\/td>No<\/td>An optional object that maps relevant input fields to custom IDs used on your form. Pass this parameter if you are not using default data-ccbill <\/strong>attributes or default IDs<\/strong>.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
<\/div>\n\n\n\n
createPaymentToken<\/h2>\n\n\n\n
<\/div>\n\n\n\n
The createPaymentToken()<\/code><\/strong> function is the primary method for generating a Payment Token using the CCBill Advanced Widget.<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span>
createPaymentToken<\/span>(authToken<\/span>,<\/span> <\/span><\/span>\n    clientAccnum<\/span>,<\/span> <\/span><\/span>\n    clientSubacc<\/span>,<\/span> <\/span><\/span>\n    clearPaymentInfo<\/span>?,<\/span> <\/span><\/span>\n    clearCustomerInfo<\/span>?,<\/span> <\/span><\/span>\n    timeToLive<\/span>?,<\/span> <\/span><\/span>\n    numberOfUse<\/span>?<\/span>)<\/span>:<\/span> <\/span>Promise<\/span><<\/span>Response<\/span>><\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
<\/div>\n\n\n\n
Parameters<\/h3>\n\n\n\n
<\/div>\n\n\n\n
NAME<\/th>TYPE<\/th>REQUIRED<\/th>DESCRIPTION<\/th><\/tr><\/thead>
authToken<\/strong><\/td>string<\/td>Yes<\/td>An OAuth JWT token previously obtained from the CCBill's Authorization Server.<\/td><\/tr>
clientAccnum<\/strong><\/td>number<\/td>Yes<\/td>Merchant account number. Should be a number between 100000<\/strong> and 999999<\/strong>.<\/td><\/tr>
clientSubacc<\/strong><\/td>number<\/td>Yes<\/td>Merchant subaccount number. Should be a number between 0<\/strong> and 9999<\/strong>.<\/td><\/tr>
clearPaymentInfo<\/strong><\/td>boolean<\/td>No<\/td>An optional flag that will, if set to true<\/strong><\/code>, result in clearance of the payment information related form fields after the createPaymentToken()<\/code><\/strong> function is called. If null<\/code>\/undefined<\/code> <\/strong>is provided, this will default to false<\/strong><\/code>, and the payment information related form fields will not be cleared.

Note:<\/strong> Even though this parameter is optional, it should be set to null<\/code><\/strong> when subsequent parameters are provided.<\/td><\/tr>
clearCustomerInfo<\/strong><\/td>boolean<\/td>No<\/td>An optional flag that will, if set to true<\/strong><\/code>, result in clearance of the customer information related form fields after the createPaymentToken()<\/code><\/strong> function is called. If null<\/code>\/undefined<\/code> <\/strong>is provided, this will default to false<\/strong><\/code>, and the customer information related form fields will not be cleared.

Note:<\/strong> Even though this parameter is optional, it should be set to null<\/code><\/strong> when subsequent parameters are provided.<\/td><\/tr>
timeToLive<\/strong><\/td>number<\/td>No<\/td>The time interval that defines how long the token should be valid (hours). Should be a number between 0 <\/strong>and 2147483647<\/strong>.

Note:<\/strong> Even though this parameter is optional, it should be set to null<\/code><\/strong> when subsequent parameters are provided.<\/td><\/tr>
numberOfUse<\/strong><\/td>number<\/td>No<\/td>Total number of times the Payment Token can be used for purchases. Should be a number between 0 <\/strong>and 2147483647<\/strong>.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
<\/div>\n\n\n\n
Form Fields<\/h3>\n\n\n\n
<\/div>\n\n\n\n
NAME<\/th>REQUIRED<\/th>DESCRIPTION<\/th><\/tr><\/thead>
firstName<\/strong><\/td>Yes<\/td>Customer's first name.<\/td><\/tr>
lastName<\/strong><\/td>Yes<\/td>Customer's last name.<\/td><\/tr>
address1<\/strong><\/td>No<\/td>Customer's billing address. If provided, it should be between 1<\/strong> and 50<\/strong> characters long.<\/td><\/tr>
address2<\/strong><\/td>No<\/td>Customer's address (line 2). If provided, it should be between 1<\/strong> and 50<\/strong> characters long.<\/td><\/tr>
postalCode<\/strong><\/td>Yes<\/td>Customer's billing zip code. It should be a valid zip code between 1<\/strong> and 16<\/strong> characters long.<\/td><\/tr>
city<\/strong><\/td>No<\/td>Customer's billing city. If provided, it should be between 1<\/strong> and 50<\/strong> characters long.<\/td><\/tr>
state<\/strong><\/td>No<\/td>Customer's billing state. If provided, it should be between 1<\/strong> and 3<\/strong> characters long.<\/td><\/tr>
country<\/strong><\/td>Yes<\/td>Customer's billing country. If provided, it should be a two-letter country code as defined in ISO 3166-1<\/a>.<\/td><\/tr>
email<\/strong><\/td>Yes<\/td>Customer's email. Should be a well-formed email address, max 254<\/strong> characters long.<\/td><\/tr>
phoneNumber<\/strong><\/td>No<\/td>Customer's phone number. If provided, it should be a well-formed phone number.<\/td><\/tr>
ipAddress<\/strong><\/td>Yes<\/td>Customer's IP address. (IPv4 only<\/strong>)<\/td><\/tr>
browserHttpUserAgent<\/strong><\/td>No<\/td>Browser User-Agent header value.<\/td><\/tr>
browserHttpAccept<\/strong><\/td>No<\/td>Browser Accept header value.<\/td><\/tr>
browserHttpAcceptEncoding<\/strong><\/td>No<\/td>Browser Accept Encoding header value.<\/td><\/tr>
browserHttpAcceptLanguate<\/strong><\/td>No<\/td>Browser Accept Language header value.<\/td><\/tr>
cardNumber<\/strong><\/td>Yes<\/td>A valid credit card number.<\/td><\/tr>
expMonth<\/strong><\/td>Yes<\/td>Credit card expiration month in mm<\/em><\/strong> format. Should be a value between 1<\/strong> and 12<\/strong>.<\/td><\/tr>
expYear<\/strong><\/td>Yes<\/td>Credit card expiration year in yyyy<\/em><\/strong> format. Should be a value between current year<\/strong> and 2100<\/strong>.<\/td><\/tr>
cvv2<\/strong><\/td>Yes<\/td>Card security code. Should be a 3-4 digit value<\/strong>.<\/td><\/tr>
nameOnCard<\/strong><\/td>Yes<\/td>Name displayed on the credit card. Should be between 2<\/strong> and 45<\/strong> characters long.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
<\/div>\n\n\n\n
Returns<\/h3>\n\n\n\n
<\/div>\n\n\n\n
Promise<Response><\/code><\/strong> - The promise resolves to the Response<\/code><\/strong> object that represents the response to your request.<\/p>\n\n\n\n
<\/div>\n\n\n\n
Success<\/a>Error<\/a><\/div>
\n
\n
<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span>
{<\/span><\/span>\n   <\/span>"<\/span>paymentTokenId<\/span>"<\/span>:<\/span>"<\/span>01d2950476214fb6953f8a4ec7006108<\/span>"<\/span>,<\/span><\/span>\n   <\/span>"<\/span>programParticipationId<\/span>"<\/span>:<\/span>null,<\/span><\/span>\n   <\/span>"<\/span>originalPaymentTokenId<\/span>"<\/span>:<\/span>null,<\/span><\/span>\n   <\/span>"<\/span>clientAccnum<\/span>"<\/span>:<\/span>900684<\/span>,<\/span><\/span>\n   <\/span>"<\/span>clientSubacc<\/span>"<\/span>:<\/span>0<\/span>,<\/span><\/span>\n   <\/span>"<\/span>createdDatetime<\/span>"<\/span>:<\/span>"<\/span>2025-02-10T13:47:35<\/span>"<\/span>,<\/span><\/span>\n   <\/span>"<\/span>timeToLive<\/span>"<\/span>:<\/span>2147483647<\/span>,<\/span><\/span>\n   <\/span>"<\/span>validNumberOfUse<\/span>"<\/span>:<\/span>2147483647<\/span>,<\/span><\/span>\n   <\/span>"<\/span>paymentInfoId<\/span>"<\/span>:<\/span>null,<\/span><\/span>\n   <\/span>"<\/span>errors<\/span>"<\/span>:<\/span>null,<\/span><\/span>\n   <\/span>"<\/span>subscriptionId<\/span>"<\/span>:<\/span>"<\/span>925041101000000183<\/span>"<\/span>,<\/span><\/span>\n   <\/span>"<\/span>cvv2Response<\/span>"<\/span>:<\/span>null,<\/span><\/span>\n   <\/span>"<\/span>avsResponse<\/span>"<\/span>:<\/span>null<\/span><\/span>\n}<\/span><\/span><\/code><\/pre><\/div>\n<\/div>\n\n\n\n
\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span>