Java Tutorial

Initialise the Parser SDK

To use the Java SDK, first we initialise the DecryptxApi object:

import com.bluefin.decryptx.apis.DecryptxApi;

// your code here

final DecryptxApi decryptxApi = new DecryptxApi();


Development vs Production

All these examples use the Decryptx production environment, to evaluate your requests against the certification environment you need to update the base path of the DecryptxApi REST Client.

At Bluefin we protect our REST endpoints with a IP address whitelist. If you'd like to try the examples below please contact us to request access.

//switch DecryptxApi to certification environment.

decryptxApi.getApiClient().setBasePath("https://cert-parser.decryptx.com/api/v1");


Authentication Headers

As of version 1.1.0 we've updated our Java SDK to support the Basic, Digest, HMAC, and RSA authentication methods. For more details on these new methods see our Authentication (Hmac/Rsa) Guide. If you specify your desired authentication method and credentials when instantiating the DecryptxApi object, the SDK will automatically generate the auth headers needed.

final DecryptxApi decryptxApi = new DecryptxApi( AuthenticationMethod.HMAC, "WATERFORD", "ef1ad938150fb15a1384b883a104ce70" );

If the DecryptxApi object is instantiated without specifying an Authentication method, then the credentials must be sent in the body of the API request.


Validate Account

To test your Bluefin credentials against our /api/v1/partner/validate endpoint use the validatePartner method.

final PartnerParam partnerParam = new PartnerParam()
        .partnerId("WATERFORD")
        .partnerKey("ef1ad938150fb15a1384b883a104ce70")
        .reference("723f57e1-e9c8-48cb-81d9-547ad2b76435");

final ValidationResponse resp = decryptxApi.validatePartner(partnerParam);

if (resp.isSuccess()){
    System.out.println("success    :" + resp.isSuccess());
    System.out.println("message id :" + resp.getMessageId());
    System.out.println("reference  :" + resp.getReference());
}
else{
    System.out.println("failed :(");
}

System output:

success    :true
message id :1201607010831171011230067
reference  :723f57e1-e9c8-48cb-81d9-547ad2b76435


Validate Device

Next, you might want to check that your device is correctly registered against your account by using the validateDevice method of the DecryptxApi object.

final DeviceParam deviceParam = new DeviceParam()
        .partnerId("WATERFORD")
        .partnerKey("ef1ad938150fb15a1384b883a104ce70")
        .reference("723f57e1-e9c8-48cb-81d9-547ad2b76435")
        .serial("541T112708")
        .clientId("bobs_burgers");

final ValidationResponse resp = decryptxApi.validateDevice(deviceParam);

if (resp.isSuccess()){
    System.out.println("success    :" + resp.isSuccess());
    System.out.println("message id :" + resp.getMessageId());
    System.out.println("reference  :" + resp.getReference());
}
else{
    System.out.println("failed :(");
}

System output:

success    :true
message id :1201607010831171011230067
reference  :723f57e1-e9c8-48cb-81d9-547ad2b76435


Payload Parser

To process a terminal payload, use the processPayload method of the DecryptxApi Object with your Bluefin credentials and a payload.

Parameter Object

First we create an instance of ParserParam class with the parameters that we want to process. In the following example we are parsing a payload from an IDTECH terminal. See our Obtaining Payloads page for instructions on how to obtain payloads and serial numbers from a device.

import com.bluefin.decryptx.model.ParserParam;

//more code here

final ParserParam param = new ParserParam()
               .partnerId("WATERFORD")
               .partnerKey("ef1ad938150fb15a1384b883a104ce70")
               .reference("723f57e1-e9c8-48cb-81d9-547ad2b76435")
               .clientId("my_client")
               .deviceType(ParserParam.DeviceTypeEnum.IDTECH)
               //.deviceSerial("this property is required to process Ingenico payloads")
               //.ksn("this property is required to process Miura payloads")
               .devicePayload("02C400C037001C0A8692;6011********3331=2212:***?*15=090210=2CB56EC5E025C2F3C2C67FCF2D0C4C39BB19E60EF31192675E5F1DB6A90070E3000000000000000000000000000000000000000035343154313132373038629949960E001D20004A029603");


Processing

Next, we process the payload by calling the processPayload method, passing our ParserParam object as a parameter. If the API call is a success an instance of the PayloadDecrypted class is returned:

import com.bluefin.decryptx.model.PayloadDecrypted;

//more code here

final PayloadDecrypted decrypted = decryptxApi.processPayload(param);


Successful Response

From the PayloadDecrypted object we can retrieve the decrypted data:

if (decrypted.isSuccess()) {
    final String pan  = decrypted.getExtracted().getPAN();
    final String expy = decrypted.getExtracted().getEXPY();

    System.out.println( "Card: " + pan  );
    System.out.println( "Expy: " + expy );

    if ( null != decrypted.getTrack2() ){
        final String track2ascii = decrypted.getTrack2().getAscii();
        final String track2mask  = decrypted.getTrack2().getMasked();

        System.out.println( "Track 2 plain text : "  + track2ascii );
        System.out.println( "Track 2 masked text: " + track2mask  );
    }
}

System output:

Card: 6011013333333331
Expy: 1222
Track 2 plain text : ;6011013333333331=2212:555?0
Track 2 masked text: ;6011********3331=2212:***?*

As you can see, decrypted.isSuccess() will return either true or false based on whether the operation was successful or not. You can also look into the PayloadDecrypted docs for more details on the generated response.


Processing Ingenico Payload

Processing Ingenico RBA payloads is slightly different to processing IDTECH payloads, you need to set the device's serial number deviceSerial on the ParserParam object. See our Obtaining Payloads page for instructions on how to obtain payloads and serial numbers from a device.


final DecryptxApi decryptxApi = new DecryptxApi();

decryptxApi.getApiClient().setBasePath("https://cert-parser.decryptx.com/api/v1");

final ParserParam param = new ParserParam()
               .partnerId("WATERFORD")
               .partnerKey("ef1ad938150fb15a1384b883a104ce70")
               .reference("723f57e1-e9c8-48cb-81d9-547ad2b76435")
               .clientId("bobs_burgers")
               .deviceType(ParserParam.DeviceTypeEnum.INGENICO_RBA)
               .deviceSerial("80612860")
               .devicePayload("54152444441612212101912TEST/BLUEFIN1B0B0229000000000000020114334787735642891651=726961371397062832AF86BB9DB92C98416AAB5BCA769D565A96C1E5C07F1D49A912C9919DBD3EA0661DF20CAC633BC330ECF753994278F50F56F7A2CE0C7212BAACFDED1632B98BE3EC8");

final PayloadDecrypted decrypted = decryptxApi.processPayload(param);

if (decrypted.isSuccess()) {
    final String pan  = decrypted.getExtracted().getPAN();
    final String expy = decrypted.getExtracted().getEXPY();

    System.out.println( "Card: " + pan  );
    System.out.println( "Expy: " + expy );

    if ( null != decrypted.getTrack2() ){
        final String track2ascii = decrypted.getTrack2().getAscii();
        final String track2mask  = decrypted.getTrack2().getMasked();

        System.out.println( "Track 2 plain text : "  + track2ascii );
        System.out.println( "Track 2 masked text: " + track2mask  );
    }
}

System output:

Card: 5415244444444444
Expy: 1222
Track 2 plain text : 4152444444444442212101123456789
Track 2 masked text: ;541524******4444=2212***********?

Error handling

We won't know whether the API call will be successful or not. The best way to handle possible errors is by using the try/catch construct with our ApiExceptionUtils class like this:

import com.bluefin.decryptx.ApiException;
import com.bluefin.decryptx.ApiExceptionUtils
import com.bluefin.decryptx.model.DecryptxError;

//more code here

try{
    final ParserParam param = new ParserParam()
                                .reference("723f57e1-e9c8-48cb-81d9-547ad2b76435")
                                .partnerId("not_a_real_key");

    final PayloadDecrypted  decrypted = decryptxApi.processPayload(param);

    // if successful, do something here
}  catch(ApiException e) {

    if ( ApiExceptionUtils.isDecryptxError(e) ){

        //convert the APIException object to a DecryptxError object.
        final DecryptxError err = ApiExceptionUtils.getDecryptxError(e);

        System.err.println("success   : " + err.isSuccess());
        System.err.println("messageId : " + err.getMessageId());
        System.err.println("code      : " + err.getErrCode());
        System.err.println("message   : " + err.getErrMessage());
        System.err.println("reference : " + err.getReference());
    }
    else{
        //a non Decryptx api related error (network issues, etc).
        System.err.println("e: " + e.getMessage());
        System.err.println("code: " + e.getCode());
        System.err.println("body: " + e.getResponseBody());
    }

}

Output:

success   : false
messageId : 1201607010822361022502672
code      : 3000
message   : Authentication required.
reference : 723f57e1-e9c8-48cb-81d9-547ad2b76435

The ApiExceptionUtils is a handy helper that will convert the returned exception into a DecryptxError object. The DecryptxError object will contain useful information about the error.