Tutorial

Let's try to use the SDK with a practical example.

 Initialise the Parser SDK

First, let's initialise Decryptx Parser SDK:

import com.bluefin.decryptx.apis.DecryptxApi;

// your code here

final DecryptxApi decryptxApi = new DecryptxApi();

Development vs Production

All the examples below point to Decryptx's production environment, to evaluate your requests against the certification environment you need to update the base path of the DecryptxApi REST Client. Note: to test the secure parser on either the certification or production environment you need to provision a device with Bluefin.

//switch DecryptxApi to certification environment.

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

Validate Account

To begin you might want to test your Bluefin credentials against with our DecryptxPartnerApi object.

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 :(");
}

Sample 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 our DecryptxDeviceApi.

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 :(");
}

Sample output

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

Payload Parser: Parameter Object

The ParserParam object will contain all the parameters that we want to process.

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")
               .devicePayload("02C400C037001C0A8692;6011********3331=2212:***?*15=090210=2CB56EC5E025C2F3C2C67FCF2D0C4C39BB19E60EF31192675E5F1DB6A90070E3000000000000000000000000000000000000000035343154313132373038629949960E001D20004A029603");

 Payload Parser: Processing

Next, we process the Payload:

import com.bluefin.decryptx.model.PayloadDecrypted;

//more code here

final PayloadDecrypted decrypted = decryptxApi.processPayload(param);

 Payload Parser: Successful Response

And we have our response:

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  );
    }
}

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

 Error handling

Of course, we won't know whether the API call we're going to perform will be successful or not. The best way to handle possible errors is thus by using the try/catch construct.

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()
                                .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());
    }

}

Sample output:

success   : false
messageId : 1201607010822361022502672
code      : 1102
message   : Partner Key not specified
reference : null

The ApiExceptionUtils is a handy helper that will convert the returned exception into a DecryptxError object, which will contain useful information about the error, plus the reference we defined in the request.