Java Guide

This page describes how to use Bluefin's Java SDK to access the Decryptx Parser's functionality. See our Decryptx Java SDK for download and setup instructions.

Initialize the SDK

To use the Java software development kit (SDK), first initialise the DecryptxParserApi object:

import com.bluefin.decryptx.apis.DecryptxParserApi;

final DecryptxParserApi decryptxApi = new DecryptxParserApi();

Development vs Production

The following examples use the Decryptx production environment. To evaluate your requests against the certification environment, you will 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 IDTECH Payload

To process a terminal payload with the Payload Parser, you must call the processPayload method. To do that, first create an instance of ParserParam with the parameters that you want to process. The example below uses a payload from an IDTECH terminal. See our IDTECH 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

Process the payload by calling the processPayload method, passing your 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

Retrieve the decrypted data from the PayloadDecrypted object:

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:***?*

Per the example above, decrypted.isSuccess() will return a Boolean value corresponding to the operation's 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 from processing IDTECH payloads. You will need to set the device's serial number deviceSerial on the ParserParam object. To learn how to obtain payloads and serial numbers from a device, see the Obtaining Payloads section of the parser guide for your device model.

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

If the API call is not successful, the best way to handle 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.