This page outlines how you can use our Java SDK to access the Parser functionality. See our Decryptx Java SDK for download and setup instructions.

Initialize the SDK

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

import com.bluefin.decryptx.apis.DecryptxParserApi;

final DecryptxParserApi decryptxApi = new DecryptxParserApi();

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 DecryptxParserApi REST Client.

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

//point the DecryptxParserApi Client to certification environment.

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

Authentication Headers

As of version 1.1.0, we have 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 DecryptxParserApi object, the SDK will automatically generate the auth headers needed.

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

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

Decryptx Parser

To process a terminal payload with the Payload Parser, you must call the processPayload method. To do that you must first create an instance of ParserParam with the parameters that we want to process. In the following example, we are parsing a payload from an IDTECH terminal. See our IDTECH Payloads page for instructions on how to obtain these payloads.

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 parameter is required for some device types")
               //.ksn("this property is required to process some device types")
               .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 a boolean value corresponding to the operations success or failure. You can also look into the PayloadDecrypted docs for more details on the generated response.

Decryptx Parser 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 DecryptxParserApi decryptxApi = new DecryptxParserApi();

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


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 will not 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 useful helper that will convert the returned exception into a DecryptxError object. The DecryptxError object will contain useful information about the error.