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 username that was set up for authentication of this API.
• Merchant Secret: This is the password that was set up for authentication of this 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

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.

1. Generate Frontend Bearer Token
2. Create Payment Token ID
3. Generate Backend Bearer Token
4. Charge Payment Token ID

Generate Frontend Bearer Token

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

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' \

Create Payment Token ID (CCBill Advanced Widget)

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.

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.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>

Step 2. Define Field IDs

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.

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.

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.

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

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.

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

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.

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

Visit the 3DS Authentication Error Codes page for a comprehensive list of error codes.

Charge Payment Token ID

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.

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

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}

Headers

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

Request Parameters

Decline Response Parameters

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

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