Cardinal Mobile SDK Android Integration Documentation V 2.2.5

Overview

Activation Steps

Cardinal wants to get you up and running with CCA as quickly and seamlessly as possible. This section of the document will outline the simple steps that are necessary in order to take advantage of Cardinal Mobile SDK.

Error rendering macro 'excerpt-include' : No link could be created for 'Setting up CardinalMobileSDK - Android - V 2.2.5'.

Step 3 - Setup the Initial Call to Cardinal

Error rendering macro 'excerpt-include' : No link could be created for 'Initial Call to Cardinal and Response - Android - V 2.2.5'.

Step 4 - Create a Lookup Request/Response to Centinel

Create an API call to your backend server in order to send a Lookup Request (cmpi_lookup) to Cardinal's Centinel platform for initiating the Consumer Authentication transaction. The Centinel platform manages all of the routing and connectivity, as well as the rules engine for all of the various 3-D Secure protocols and versions. Please follow the Getting Started and Lookup Request/Response sections for completing your backend integration: Cardinal (cmpi) Messages

Required Field for identifying as an SDK transaction :

<DeviceChannel>SDK</DeviceChannel>
<DFReferenceId>ReferenceId</DFReferenceId>

ReferenceId is consumerSessionId returned on init completion, if no referenceID is passed in serverJwt. Else you can use that referenceID as DFReferenceId

Step 5 - Handle the Centinel Lookup Response and Create the Authentication Session

Error rendering macro 'excerpt-include' : No link could be created for 'Handle the Centinel Lookup Response and SDK Handle the Challenge UI - Android - V 2.2.5'.

Step 6 - JWT Validation

Once the response JWT arrives in the onValidated, you will need to send the response JWT to your backend for verification and consumption. We recommend that any values sent to 3rd parties are sourced from the response JWT after it has been properly validated.

Security Warning

For security reasons, all JWT validation must be done on the server side.

Looking for more information?

For more in-depth information on JWT validation including code samples in a few languages, check out the JWT Validation page.

JWT Validation

Please note that each Claim key is case sensitive.

Claim	Description
aud	Merchant jti Id - This is the 'jti' field from your request JWT echoed back. This field allows you to match up your request JWT with Cardinals response JWT.
jti	JWT Id - A unique identifier for this response JWT. This value is generated by Cardinal.
iat	Issued At Time - This is a timestamp of when the JWT was created.
iss	Issuer - The request JWT's iss field echoed back.
ConsumerSessionId	The unique session Id for the current user.
Payload	The response object for your request. This field will contain any actual state information on the transaction. This is the decoded data object that is passed into the `payments.validated` event as the first argument.

JWT Payload Example

Below is an example of the JSON content of a basic response JWT Payload where we are passing an object within the Payload claim:

Raw JWT Sample

{
    "iss": "56560a358b946e0c8452365ds",
    "iat": 1471014492,
    "exp": 1471021692,
    "jti": "8af34811-f97d-495a-ad19-ec2f68004f28",
    "ConsumerSessionId": "0e1ae450-df2b-4872-94f7-f129a2ddab18",
    "Payload": {
        "Validated": true,
        "Payment": {
            "Type": "CCA",
            "ExtendedData": {
                "CAVV": "AAABAWFlmQAAAABjRWWZEEFgFz+=",
                "ECIFlag": "05",
                "PAResStatus": "Y",
                "SignatureVerification": "Y",
                "XID": "MHEyQjFRQkttemdpaFlRdHowWTA=",
                "Enrolled": "Y"
            }
        },
        "ActionCode": "SUCCESS",
        "ErrorNumber": 0,
        "ErrorDescription": "Success"
    }
}

Below is an example of the JSON content of a basic response JWT Payload where we are passing a string within the Payload claim. This would occur when the request JWT included a ObjectifyPayload flag set to false:

Stringified JWT Sample

}
    "iss": "56560a358b946e0c8452365ds",
    "iat": 1471015342,
    "exp": 1471022542,
    "jti": "55ebfa2a-665f-4d6b-81ea-37d1d4d12d9e",
    "ConsumerSessionId": "fb3a97a3-0344-4d3d-93ea-6482d866ec97",
    "Payload": "{\"Validated\":true,\"Payment\":{\"Type\":\"CCA\",\"ExtendedData\":{\"CAVV\":\"AAABAWFlmQAAAABjRWWZEEFgFz+\\u003d\",\"ECIFlag\":\"05\",\"PAResStatus\":\"Y\",\"SignatureVerification\":\"Y\",\"XID\":\"MFpjUVpwb0FXcHdwMWJBdldwNDA\\u003d\",\"Enrolled\":\"Y\"}},\"ActionCode\":\"SUCCESS\",\"ErrorNumber\":0,\"ErrorDescription\":\"Success\"}"
}

Step 7 - Cleanup

The cleanup method should be called after the transaction has completed. This clears Cardinal.java’s current instance so when Cardinal.getInstance() is called again, a new instance is created. This can be called from any location within your application.

Cardinal.getInstance().cleanup();