CCBill API Payment Widget integration guide

Java

The code example is written in Java. It describes the steps required to perform authentication with the CCBill API and the payment token obtained using the CCBill API Payment Widget to perform the charge by payment token action (non-3DSecure and 3DSecure versions). This script covers the backend portion of the integration with the CCBill's RESTful Transaction API.

1. Install Dependencies

Add the dependencies for building and importing the libraries. For example, if using Maven, you need a pom.xml file that lists all the dependencies with version numbers you want to use:

<dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <version>2.7.1</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-webflux</artifactId> <version>2.7.1</version> </dependency> </dependencies>

2. Define Endpoints

The endpoints section defines the API endpoints you will use throughout the process.

The example uses three endpoints to demonstrate the charge flow:

1. getAuthToken allows requesting the CCBill Auth (Bearer) token required for authentication in subsequent operations.

2. createTransactionallows performing a non-3DSecured charge transaction using the payment token.

3. createThreedsTransactionallows performing a 3DSecured charge transaction using the payment token and previously obtained SCA parameters.

3. Provide Client Credentials

Set your Merchant Application ID as the value of username, and the Merchant Secret as the value of password.

The example code will set theaccess_tokenvalue when the script executes.

4. Add Data

Provide the appropriate data for the request. To create a charge, the following parameters are obtained using the payment widget:

1. The paymentToken previously obtained using the payment widget. Ensure the client's IP address is added as a payload (ipAddress) or header (X-Origin-IP) parameter.

2. TransactionRequestParams, including the client account number, subaccount, the initial price, and period.

3. If using 3DS, provide the ThreedsTransactionRequestParams previously obtained using the payment widget.

5. Generate OAuth Token

Create a function to fetch the OAuth token (getAuthToken). The function requires the username, password, and token endpoint to request the token.

The token helps authenticate the payment requests.

6. Charge Transaction and Handle Response

ThecreateTransactionand createThreedsTransaction functions perform the charge based on the provided endpoint, data, payment token, and generated access token.

If calling the functions throws no errors, the response is passed to the TransactionResponse function.

In this case, it only logs the response data. In a realistic scenario, it would allow you to continue processing the transaction and return the response to your client.

7. Test Transaction

The code fetches the OAuth token based on the previously provided data.

If the access token is generated successfully, the code performs a non-3DS transaction and then a 3DSecure transaction using the previously obtained SCA and other transaction data.

backend.java 
package com.ccbill.mcn.transaction.service.integration.example;

import org.apache.tomcat.util.codec.binary.Base64;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Component;
import org.springframework.web.reactive.function.BodyInserters;
import org.springframework.web.reactive.function.client.WebClient;

import java.math.BigDecimal;
import java.math.BigInteger;

@Component
public class IntegrationCodeExamples {




   public ResponseEntity<AuthTokenResponse> getAuthToken(String username, String password) {
   


   
        String base64Credentials = getCredentials(username, password);
	


	
        WebClient webClient = WebClient.create("https://api.ccbill.com");
        return webClient.post()
                .uri("/ccbill-auth/oauth/token?grant_type=client_credentials")
	


	
                .header("Authorization", "Basic " + base64Credentials)
                .header("Content-Type", "application/x-www-form-urlencoded")
                .retrieve()
                .toEntity(AuthTokenResponse.class)
                .block();
    }
	


	
    public ResponseEntity<TransactionResponse> createTransaction(String authToken, String paymentToken,
    TransactionRequestParams transactionRequestParams) { 
	




	
        WebClient webClient = WebClient.create("https://api.ccbill.com");
        return webClient.post()
                .uri("transactions/payment-tokens/" + paymentToken)
	


	
                .header("Authorization", "Bearer " + authToken)
                .bodyValue(transactionRequestParams)
                .retrieve()
                .toEntity(TransactionResponse.class)
                .block();
    }
	


	
    public ResponseEntity<TransactionResponse> createThreedsTransaction(String authToken, String paymentToken,
    ThreedsTransactionRequestParams threedsTransactionRequestParams) {
	




	
        WebClient webClient = WebClient.builder().baseUrl("https://api.ccbill.com").build();
        return webClient.post()
                .uri("/transactions/payment-tokens/threeds/" + paymentToken)
	


	
                .header("Authorization", "Bearer " + authToken)
                .body(BodyInserters.fromValue(threedsTransactionRequestParams))
                .retrieve()
                .toEntity(TransactionResponse.class)
                .block();
    }
	


	
    private String getCredentials(String username, String password) {
        String credentials = username + ":" + password;
        byte[] credentialsBytes = credentials.getBytes();
        byte[] base64 = Base64.encodeBase64(credentialsBytes);
        return new String(base64);
    }
	




	

    public static class AuthTokenResponse {
        private String access_token;
        private String token_type;
        private Long expires_in;
        private String scope;
        private String jti;

        public String getAccess_token() {
            return access_token;
        }
        public void setAccess_token(String access_token) {
            this.access_token = access_token;
        }
        public String getToken_type() {
            return token_type;
        }
        public void setToken_type(String token_type) {
            this.token_type = token_type;
        }
        public Long getExpires_in() {
            return expires_in;
        }
        public void setExpires_in(Long expires_in) {
            this.expires_in = expires_in;
        }
        public String getScope() {
            return scope;
        }
        public void setScope(String scope) {
            this.scope = scope;
        }
        public String getJti() {
            return jti;
        }
        public void setJti(String jti) {
            this.jti = jti;
        }
    }
	




	
 
    public static class TransactionRequestParams {
        private Integer clientAccnum;
        private Integer clientSubacc;
        private BigDecimal initialPrice;
        private Long initialPeriod;
        
        public Integer getClientAccnum() {
            return clientAccnum;
        }
        public void setClientAccnum(Integer clientAccnum) {
            this.clientAccnum = clientAccnum;
        }
        public Integer getClientSubacc() {
            return clientSubacc;
        }
        public void setClientSubacc(Integer clientSubacc) {
            this.clientSubacc = clientSubacc;
        }
        public BigDecimal getInitialPrice() {
            return initialPrice;
        }
        public void setInitialPrice(BigDecimal initialPrice) {
            this.initialPrice = initialPrice;
        }
        public Long getInitialPeriod() {
            return initialPeriod;
        }
        public void setInitialPeriod(Long initialPeriod) {
            this.initialPeriod = initialPeriod;
        }
    }
	




	
    
    public static class ThreedsTransactionRequestParams extends TransactionRequestParams {
        private String threedsEci;
        private String threedsError;
        private String threedsStatus;
        private String threedsSuccess;
        private String threedsVersion;
        private String threedsXid;
        private String threedsCavv;
        private BigDecimal threedsAmount;
        private String threedsClientTransactionId;
        private String threedsAcsTransId;
        private String threedsDsTransId;
        private String threedsCurrency;
        private String threedsCardToken;
        private String threedsAuthenticationType;
        private String threedsAuthenticationValue;

        public String getThreedsAuthenticationType() {
            return threedsAuthenticationType;
        }
        public void setThreedsAuthenticationType(String threedsAuthenticationType) {
            this.threedsAuthenticationType = threedsAuthenticationType;
        }
        public String getThreedsAuthenticationValue() {
            return threedsAuthenticationValue;
        }
        public void setThreedsAuthenticationValue(String threedsAuthenticationValue) {
            this.threedsAuthenticationValue = threedsAuthenticationValue;
        }
        public String getThreedsClientTransactionId() {
            return threedsClientTransactionId;
        }
        public void setThreedsClientTransactionId(String threedsClientTransactionId) {
            this.threedsClientTransactionId = threedsClientTransactionId;
        }
        public String getThreedsAcsTransId() {
            return threedsAcsTransId;
        }
        public void setThreedsAcsTransId(String threedsAcsTransId) {
            this.threedsAcsTransId = threedsAcsTransId;
        }
        public String getThreedsEci() {
            return threedsEci;
        }
        public void setThreedsEci(String threedsEci) {
            this.threedsEci = threedsEci;
        }
        public String getThreedsError() {
            return threedsError;
        }
        public void setThreedsError(String threedsError) {
            this.threedsError = threedsError;
        }
        public String getThreedsStatus() {
            return threedsStatus;
        }
        public void setThreedsStatus(String threedsStatus) {
            this.threedsStatus = threedsStatus;
        }
        public String getThreedsSuccess() {
            return threedsSuccess;
        }
        public void setThreedsSuccess(String threedsSuccess) {
            this.threedsSuccess = threedsSuccess;
        }
        public String getThreedsVersion() {
            return threedsVersion;
        }
        public void setThreedsVersion(String threedsVersion) {
            this.threedsVersion = threedsVersion;
        }
        public String getThreedsXid() {
            return threedsXid;
        }
        public void setThreedsXid(String threedsXid) {
            this.threedsXid = threedsXid;
        }
        public String getThreedsCavv() {
            return threedsCavv;
        }
        public void setThreedsCavv(String threedsCavv) {
            this.threedsCavv = threedsCavv;
        }
        public BigDecimal getThreedsAmount() {
            return threedsAmount;
        }
        public void setThreedsAmount(BigDecimal threedsAmount) {
            this.threedsAmount = threedsAmount;
        }
        public String getThreedsDsTransId() {
            return threedsDsTransId;
        }
        public void setThreedsDsTransId(String threedsDsTransId) {
            this.threedsDsTransId = threedsDsTransId;
        }
        public String getThreedsCurrency() {
            return threedsCurrency;
        }
        public void setThreedsCurrency(String threedsCurrency) {
            this.threedsCurrency = threedsCurrency;
        }
        public String getThreedsCardToken() {
            return threedsCardToken;
        }
        public void setThreedsCardToken(String threedsCardToken) {
            this.threedsCardToken = threedsCardToken;
        }
    }
	




	

    public static class TransactionResponse {
        private Long declineCode;
        private String declineText;
        private BigInteger denialId;
        private boolean approved;
        private String paymentUniqueId;
        private String sessionId;
        private Long subscriptionId;
        private String newPaymentTokenId;

        public Long getDeclineCode() {
            return declineCode;
        }
        public void setDeclineCode(Long errorCode) {
            this.declineCode = errorCode;
        }
        public String getDeclineText() {
            return declineText;
        }
        public void setDeclineText(String declineText) {
            this.declineText = declineText;
        }
        public BigInteger getDenialId() {
            return denialId;
        }
        public void setDenialId(BigInteger denialId) {
            this.denialId = denialId;
        }
        public boolean isApproved() {
            return approved;
        }
        public void setApproved(boolean approved) {
            this.approved = approved;
        }
        public String getPaymentUniqueId() {
            return paymentUniqueId;
        }
        public void setPaymentUniqueId(String paymentUniqueId) {
            this.paymentUniqueId = paymentUniqueId;
        }
        public String getSessionId() {
            return sessionId;
        }
        public void setSessionId(String sessionId) {
            this.sessionId = sessionId;
        }
        public Long getSubscriptionId() {
            return subscriptionId;
        }
        public void setSubscriptionId(Long subscriptionId) {
            this.subscriptionId = subscriptionId;
        }
        public String getNewPaymentTokenId() {
            return newPaymentTokenId;
        }
        public void setNewPaymentTokenId(String newPaymentTokenId) {
            this.newPaymentTokenId = newPaymentTokenId;
        }
    }
}