Encryption Support for Mobile Apps

Radial offers the capability to encrypt payment card numbers directly from your mobile app as soon as the user enters them. Doing the encryption immediately prevents raw card numbers from being sent to the webstore server. Using this capability can help reduce your PCI auditing levels.

Radial has extended its browser-based Ajax tokenization to support this capability. In the browser-based encryption process, a Radial-hosted Javascript collects the card number in the browser and sends it to a HTTPS REST endpoint. On the Radial server, this number is tokenized. The token is returned in a Javascript call back to the browser. For more details, see Ajax Tokenization and 3D Secure Support.

In the new process flow for mobile apps, Radial's HTTPS REST endpoint can accept unencrypted account numbers and CVV numbers. Those numbers are then encrypted and sent back in a HTTPS call.

Use Case: Encryption During Checkout

There are three main steps involved in the encryption call, as shown in the diagram below.

Authenticate and Get a Nonce

For security purposes, Radial must authenticate the webstore prior to transmitting any data. Radial exposes a REST HTTPS endpoint that the webstore can use for authentication.

• Test Environment: https://tst.payments.radial.com/hosted-payments/auth/nonce
• Production Environment: https://hostedpayments.radial.com/hosted-payments/auth/nonce

The endpoints listed above are available and can be tested using a REST client such as Postman after Radial provides your credentials for access.

This is a server-to-server call. Radial will provide your webstore with authentication credentials that must be used in this request. Below is a sample authentication request payload:

  {
     "username" : "username",  
     "password" : "password",
  }

The REST call will provide a response similar to the example below.

  {
      "nonce": "1a83cd28-3847-4a41-8c52-48cc5ab1af61" ,
      "expires_in_seconds": 300
  }

The webstore must capture the nonce from the response and send it to the mobile application. In case of error, the message shown below will be returned:

  {
     "error_code" : "50002",
     "error_message" : "InvalidLoginError",
  }

Possible errors that can be returned are listed below.

Initiate Encryption Call from Mobile App

The nonce received in the previous step is necessary for the encryption calls that need to be made from the mobile application. The mobile application must make an HTTPS Post request to the Radial URL listed below.

• Test Environment:
  http://tst.payments.radial.com/hosted-payments/encrypt/pancsc?access_token=<nonce>
• Production Environment:
  http://hostedpayments.radial.com/hosted-payments/encrypt/ pancsc?access_token=<nonce>

Below is a sample encryption request payload.

  {"paymentAccountNumber":"4111111111111111",
   “cardSecurityCode” : “111”
  }

Handle Encrypted Response, Failure and Error Handling

In case of success, the webstore can collect the encryptedPaymentAccountNumber from the Json object. The REST call will provide a response that would looks like the example below (HTTP Status is OK).

  {
    "encryptedPaymentAccountNumber" : "wKroqf4MUBjJjuua9EXrp9o9V ",
    "encryptedCardSecurityCode"      : "z0rM4mY41v6aqCeqCrnTzsJkIPpm5L",
    "ActionCode" : "SUCCESS"
  }

Please note that this encryption utility does not validate whether the data passed is a proper card number or if the CVV is 3 digits or 4 digits long. It simply encrypts the data as received, using the webstore's specific encryption key, and returns a blob.

In case of failure or errors, an error response is returned in one of the two formats shown below.

{
   "failure_code": "<code>",
   "failure_message": "<Message>",
   "ActionCode": "FAILURE"
}

{
   "error_code": "<code>",
   "error_message": "<message>.",
   "error": "<Exception>",
   "ActionCode": "ERROR"
}

Possible failures that can be returned are listed below.

In case of error, there may have been an issue on the network, or one of Radial’s internal services might be down. In this case, the webstore can implicitly retry the request without user intervention.

Possible errors that can be returned are listed below.

Use Case: Tokenization by REST Endpoints

It is possible to call Radial's REST endpoints from a mobile app to accomplish tokenization. The steps of this process are outlined in this section. The sequence diagram below shows the flow of this tokenization process.

Authenticate and Get a Nonce

For security purposes, Radial must authenticate the webstore prior to transmitting any data. In order to facilitate that, Radial exposes a REST https endpoint.

• Test Environment

  
  	https://tst.payments.radial.com/hosted-payments/auth/nonce
  				

• Production Environment

  
  	https://hostedpayments.radial.com/hosted-payments/auth/nonce
  			

This is a server-to-server call. The webstore will be provided with authentication credentials that they are expected to supply in this request. Below is a sample authentication request payload.

            {
                "username" : "username",
                "password" : "password",
            }
        

The REST call provides a response similar to the example below:

            {
                "nonce": "1a83cd28-3847-4a41-8c52-48cc5ab1af61" ,
                "expires_in_seconds": 1000,
            }
        

The webstore must capture the response and send the information to the browser. The nonce returned in the response is needed in the JavaScript library.

In case of error, the payload below is returned:

             {
                "error_code" : "50002",
                "error_message" : "InvalidLoginError",
            }
        

Below is a list of possible errors that can be returned:

Tokenize Payment Account Number

To tokenize the payment account number, call the POST REST endpoint listed below, using the nonce value received in the previous step.

• Test Environment

  
     https://tst.payments.radial.com/hosted-payments/pan/tokenize?access_token='nonce'
  				

• Production Environment

  
     https://hostedpayments.radial.com/hosted-payments/pan/tokenize?access_token='nonce'
  			

An example of a request payload is shown below.

    {
       "paymentAccountNumber" : "4111111111111111"
    }

The REST call provides a success response similar to the example below:

 {
   "account_token": "411111vjOiXS1111",
   "ActionCode": "SUCCESS"
 }   

Two examples of error and failure responses are shown below.

 {
   "failure_code": "40003",
   "failure_message": "The account number passed in did not pass luhn check",
   "ActionCode": "FAILURE"  
 }  

 {
   "error_code": "50003",
   "error_message": "There was an internal error in Radial’s system.",
   "error": "InvalidRequestXmlException",
   "ActionCode": "ERROR"
 }     

Below is a list of possible errors that can be returned.

Use Case: Tokenization for Later Authorization

In certain scenarios, it might be helpful to validate the card ahead of actual authorization and then authorize without user intervention or CVV entry later. For this use case, you can use Radial's ValidateCard API. ValidateCard is a server-to-server call.

In this scenario, the mobile app must first use the mechanism detailed above to encrypt the card number. Then it can call the ValidateCard API with the encrypted account number and CVV. For details of this API, see Validate Card.

After validating the card, the mobile app's authorization call must pass the element POSMethod with the value Virtual Wallet. For details of the Authorization API, see Credit Card Authorization.