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 set up 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

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.

2. Create Payment Token (CCBill Advanced Widget)

Customer payment details (such as the credit card number, expiration date, cardholder name, etc.) must be collected through a payment form.

Merchants can design custom payment forms and apps to capture this information and then forward the data in an API request to the correct endpoint.

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.9.0/ccbill-advanced-widget.js" as="script"/>
<script type="text/javascript" src="https://js.ccbill.com/v1.9.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.

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:

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.

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

The merchant payment form also needs to contain text input fields, hidden if necessary (or select element for currencyCode) for the following parameters:

The Advanced Widget will automatically collect the currencyCode, nameOnCard, and email values if they follow standard naming conventions. Merchants can:

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

data-ccbill attribute example (input)

<form id="payment-form"> 
    <input data-ccbill="email" /> 
    <input data-ccbill="nameOnCard" />
    <input data-ccbill="currencyCode"  type="text" />
    <!— other fields skipped for brevity --> 
</form>

data-ccbill attribute example (select)

<select data-ccbill="currencyCode">
  <option>…</option>
  <option>…</option>
  ...
</select>

Default _ccbillId_ attribute example (input)

<form id="payment-form">
    <input id="_ccbillId_email" />
    <input id="_ccbillId_nameOnCard" />
    <input id="_ccbillId_currencyCode" type="text" />
    <!— other fields skipped for brevity -->
</form>

Default _ccbillId_currencyCode attribute example (select)

<select id="_ccbillId_currencyCode">
<option>…</option>
<option>…</option>
…
</select>

Field Data Validation

The violations object is an array of the following type:

{
  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, currency code, nameOnCard, and email.

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.isScaRequiredForPaymentToken(authToken, paymentTokenId);

The merchant payment form also needs to contain text input fields, hidden if necessary (or select element for currencyCode) for the following parameters:

The Advanced Widget will automatically collect the currencyCode, nameOnCard, and email values if they follow standard naming conventions. Merchants can:

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

data-ccbill attribute example (input)

<form id="payment-form"> 
    <input data-ccbill="email" /> 
    <input data-ccbill="nameOnCard" />
    <input data-ccbill="currencyCode"  type="text" />
    <!— other fields skipped for brevity --> 
</form>

data-ccbill attribute example (select)

<select data-ccbill="currencyCode">
<option>…</option>
<option>…</option>
…
</select>

Default _ccbillId_ attribute example (input)

<form id="payment-form">
    <input id="_ccbillId_email" />
    <input id="_ccbillId_nameOnCard" />
    <input id="_ccbillId_currencyCode" type="text" />
    <!— other fields skipped for brevity -->
</form>

Default _ccbillId_currencyCode attribute example (select)

<select id="_ccbillId_currencyCode">
<option>…</option>
<option>…</option>
…
</select>

Field Data Validation

The violations object is an array of the following type:

{
  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 strong customer authentication.

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

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.

Versioning

CCBill's RESTful API uses Media Type Versioning to specify the API version and media type. You can explicitly request a specific API version by including the desired media type in the Accept header of your requests.

To request the latest version of the API, include the following in the request headers:

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

All API request and response examples in this guide use the latest version header. Check the headers in each example to ensure it is compatible with your implementation.

Charge Payment Token (Without 3DS Authentication)

HTTP Request URL

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

Request Parameters

Decline Response Parameters

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}

Request Parameters

Decline Response Parameters

Example Response

{
  "errorCode": "integer",
  "approved": "boolean",
  "paymentUniqueId": "string",
  "sessionId": "string",
  "subscriptionId": "string",
  "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 must identify the charge by the payment token ID and include the ID as a URI element.

Example Request

GET 'https://api.ccbill.com/payment-tokens/[payment_token_id]' \
--header 'Authorization: Bearer [access_token]' \
--header 'Accept: application/vnd.mcn.transaction-service.api.v.2+json'

HTTP Request URL

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

Response Parameters

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