Before You Begin

Before you can implement payer authentication services, your business team must contact your acquirer and Cybersource to establish the service. Your software development team should become familiar with the API fields and technical details of this service.

Implementing the SDK in your mobile application requires either Android or iOS platform application programming skills. Android API 19 or iOS 8 and XCode 8 are required.

Credentials/API Keys

API keys are required in order to create the JSON Web Token (JWT). To obtain credentials to generate your API keys, contact Cybersource Customer Support.

You will receive an email with your user name and a temporary password. Your user name will be in the following format:

cybersource_merchant name_contact name

for example, cybersource_britishairways_peter

Once your receive your credentials, log in to your JFrog account and update your temporary password. Follow the process below to generate your API key.

To generate your API key:

Step 1Log in to to your JFrog account.

Step 2In the top-right of the JFrog Platform, select the Welcome drop-down menu and click Edit Profile.

Step 3Enter your password and click Unlock.

Step 4Under Authentication Settings, click Generate API Key.

Create the JSON Web Token (JWT)

The Cardinal Mobile SDK integration uses JWTs as the method of authentication.

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

When creating the JWT, use your company API Key as the JWT secret. You can use any JTW library that supports JSON Web Signature (JWS). For further information about JWTs, see https://jwt.io/.

JWT Claims

Table 5 lists the standard claims that can be used in a JWT claim set.

Table 5JWT Claims
Claim Name		Description
Required	Note Each claim key is case sensitive.
Required	jti	JWT ID - unique identifier for the JWT. This field should change each time a JWT is generated.
	iat	Issued at - the epoch time in seconds beginning when the JWT is issued. This value indicates how long a JWT has existed and can be used to determine if it is expired.
	iss	Issuer - identifier of who is issuing the JWT. Contains the API key identifier or name.
	OrgUnitId	The merchant SSO Org Unit Id.
	Payload	The JSON data object being sent. This object is usually an order object.
Optional	ReferenceId	Merchant-supplied identifier that can be used to match up data collected from the Cardinal Mobile SDK and enrollment check service.
	ObjectifyPayload	Boolean flag that indicates how the API should consume the payload claim. If set to true, the payload claim is an object. If set to false, the payload claim is a stringified object. Some JWT libraries do not support passing objects as claims; this allows those who only allow strings to use their libraries without customization.
	exp	Expiration - the numeric epoch time in which the JWT should be considered expired. This value is ignored if it is more than 4 hours.

JWT Examples

Example 9 shows the JSON content of a basic JWT payload that passes an object within the payload claim.

Example 9Raw JWT

{

"jti": "a5a59bfb-ac06-4c5f-be5c-351b64ae608e",

"iat": 1448997865,

"iss": "56560a358b946e0c8452365ds",

"OrgUnitId": "565607c18b946e058463ds8r",

"Payload": {

"OrderDetails": {

"OrderNumber": "0e5c5bf2-ea64-42e8-9ee1-71fff6522e15",

"Amount": "1500",

"CurrencyCode": "840"

}

"ObjectifyPayload": true,

"ReferenceId": "c88b20c0-5047-11e6-8c35-8789b865ff15",

"exp": 1449001465,

}

Example 10 shows the JSON content of a basic JWT payload that passes a string within the payload claim.

Example 10Stringified JWT

{

"jti": "29311a10-5048-11e6-8c35-8789b865ff15",

"iat": 1448997875,

"iss": "56560a358b946e0c8452365ds",

"OrgUnitId": "565607c18b946e058463ds8r",

"Payload": "{\"OrderDetails\":{\"OrderNumber\":\"19ec6910-5048-11e6-8c35-8789b865ff15\",\"Amount\":\"1500\",\"CurrencyCode\":\"840\"}}",

"ObjectifyPayload" false

"ReferenceId": "074fda80-5048-11e6-8c35-8789b865ff15"

"exp":1449001465,

}