Overview

The Android Direct Native SDK integration is an SDK for native mobile apps to perform 3D-Secure-Only validation using the Nuvei authenticate3d() method.

This topic steps you through the process of integrating Nuvei payment solutions into your native mobile apps on the Android platform.

UI Implementation

3D Authentication presents challenge screens to the user. You can customize the UI of these screens by changing the values in the set of customization definition objects. This customization definition is optional and may be skipped; the default customization is used in this case.

Example Android SDK UI Customization

// Customization
val customization = NuveiUiCustomization(
    toolbarCustomization = NuveiToolbarCustomization(
        "SECURE CHECKOUT",
        "sans-serif",
        22,
        "#FFFFFF",
        "#40C1AC"
    ),
    labelCustomization = NuveiLabelCustomization(
        "sans-serif",
        14,
        "#000000",
        "sans-serif",
        14,
        "#40C1AC"
    ),
    textBoxCustomization = NuveiTextBoxCustomization(
        "sans-serif",
        14,
        "#000000",
        "#000000",
        0,
        1
    )
)
// Next button customization
NuveiButtonCustomization(
    "sans-serif",
    "#FFFFFF",
    17,
    "#40C1AC",
    5
).also {
    customization.setButtonCustomization(it, NuveiButtonCustomization.Type.NEXT)
    customization.setButtonCustomization(it, NuveiButtonCustomization.Type.CONTINUE)
    customization.setButtonCustomization(it, NuveiButtonCustomization.Type.RESEND)
    customization.setButtonCustomization(it, NuveiButtonCustomization.Type.SUBMIT)
}
// Cancel button customization
NuveiButtonCustomization(
    "sans-serif",
    "#40C1AC",
    17,
    "#FFFFFF",
    5
).also {
    customization.setButtonCustomization(it, NuveiButtonCustomization.Type.CANCEL)
}
MobileSDK.setUiCustomization(customization)

Submit a Payment Request

Initiate a Session

Send the /openOrder API call, which does the following:

• Authenticates you as our merchant using your given credentials.
• Sets up an order on our system that contains your transaction details, which are referenced later in the payment flow.
  
  Before using the Server SDK, make sure to initialize the SDK before any request by including the relevant SDK initialization.

• This call must be performed on your backend server, never on the front end. The /openOrder call described here requires your password, which should NOT be exposed on the client side.

  It is important to set the order from the server side to prevent front-end user manipulation.
  You can use Postman to simulate the /openOrder workflow using the “Server to Server with Web SDK” postman collection in the Nuvei sandbox environment.
  To install Postman and the relevant simulation collection, follow the steps in the Testing APIs with Postman topic.

  For the /openOrder authentication, you must create a checksum. This is a SHA-256 encryption of the concatenation of the following fields in this order:

  merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, and your merchantSecretKey at the end.

Example /openOrder Request

• {  
     "merchantId":"<your merchantId goes here>",
     "merchantSiteId":"<your merchantSiteId goes here>",
     "clientUniqueId":"<unique transaction ID in merchant system>",
     "clientRequestId":"<unique request ID in merchant system>",
     "currency":"USD",
     "amount":"200",
     "timeStamp":"<YYYYMMDDHHmmss>",
     "checksum":"<calculated checksum>"
  }

  <?php
  $safecharge = new \SafeCharge\Api\RestClient([
  'environment' => \SafeCharge\Api\Environment::INT,
  'merchantId' => '<your merchantId>',
  'merchantSiteId' => '<your merchantSiteId>',
  'merchantSecretKey' => '<your merchantSecretKey>',
  ]);
  
  $openOrderRequest = $SafeCharge->getPaymentService()->openOrder([
      'clientUniqueId'    => '<unique transaction ID in merchant system>',
      'clientRequestId'    => '<unique request ID in merchant system>',
      'currency'          => 'USD',
      'amount'            => '200'
  ]);
  ?>

  public static void main(String[] args) {
  // for initialization 
  String merchantId = "<your merchantId>";
  String merchantSiteId = "<your merchantSiteId>";
  String merchantKey = "<your merchantKey>";
  safecharge.initialize(merchantId, merchantSiteId, merchantKey, 
  APIConstants.Environment.INTEGRATION_HOST.getUrl(), Constants.HashAlgorithm.SHA256);
  
  //for openOrder
  String clientUniqueId = "<unique transaction ID in merchant system>";
  String clientRequestId = "<unique request ID in merchant system>";
  String currency = "USD";
  String amount = "200";
  SafechargeResponse response = safecharge.openOrder(userTokenId, clientRequestId,
  clientUniqueId, null, null, null, null, currency, amount, null, null, null, null, 
  null, null, null, null, null, null, null, null, null, null, null, null, 
  null, null, null, null, null, null);
  }

  var safecharge = new Safecharge(
  "<your merchantKey>",
  "<your merchantId>",
  "<your merchantSiteId>",
  "<your server host value",
  HashAlgorithmType.SHA256
  );
  var response = safecharge.OpenOrder(
   "USD",
   "200",
   clientUniqueId: "<unique transaction ID in merchant system>",
   clientRequestId: "<unique request ID in merchant system>"
  );

  const safecharge = require('safecharge');
  safecharge.initiate(<merchantId>, <merchantSiteId>, <merchantSecretKey>, <env>);
  safecharge.paymentService.openOrder({
      'clientUniqueId'   : '<unique transaction ID in merchant system>',
      'clientRequestId'   : '<unique request ID in merchant system>',
      'currency'         : 'USD',
      'amount'           : '200'
  }, function (err, result) {
      console.log(err, result)
  });

Example /openOrder Response

• {
      "sessionToken": "64fe6953-69d1-440f-8e21-878c85701f09",
      "orderId": "39272",
      "merchantId": "427583496191624621",
      "merchantSiteId": "142033",
      "clientUniqueId": "12345",
      "clientRequestId": "1484759782197",
      "internalRequestId": 866,
      "status": "SUCCESS",
      "errCode": 0,
      "reason": "",
      "version": "1.0"
  }

Create a Payment

Submit a NuveiSimplyConnect.createPayment() request.

NuveiSimplyConnect.createPayment(
    /*Activity*/ activity = this,
    /*NVPayment*/ input = input,
    /*Map<String, Any>?*/ additionalParams = null,
    /*Boolean*/ forceWebChallenge = true,
    object : Callback<NVCreatePaymentOutput> {
        override fun onComplete(response: NVCreatePaymentOutput) {
            // TODO: Handle response
        }
    }
)

Tokenization

Submit a NuveiSimplyConnect.tokenize() request.

NuveiSimplyConnect.tokenize(
    /*Activity*/ activity = this,
    /*NVPayment*/ input = input,
    object : TokenizeCallback {
        override fun onComplete(token: String?, error: Error?, additionalInfo: Map<String, Any>?) {
            // TODO: Handle token or error
        }
    }
)

3D-Secure Authentication

Once you have collected all the required transaction details, create an instance of Authenticate3dInput class with all the data and call NuveiMobileSDK.authenticate3d(...) method as follows:

Example Input

val paymentOption = PaymentOption(
    /*String?*/ userPaymentOptionId = "UPO ID if you have one or null",
    CardDetails(
        /*String?*/ cardNumber = "CARD NUMBER WITHOUT FORMATTING",
        /*String?*/ cardHolderName = "CARD HOLDER NAME",
        /*String?*/ cvv = "CVV",
        /*String*/ expirationMonth = "EXP MONTH IN 2 DIGITS",
        /*String*/ expirationYear = "EXP YEAR IN 2 DIGITS"
    )
)
val billingAddress = BillingAddress(/* Fill billing address if needed */)
val shippingAddress = ShippingAddress(/* Fill shipping address if needed */)
val userDetails = UserDetails(/* Fill user details if needed */)
val merchantDetails = MerchantDetails(/* Fill merchant details if needed */)
val input = NVPayment(
    /*String*/ sessionToken = "sessionToken",
    /*String*/ merchantId = "merchantId",
    /*String*/ merchantSiteId = "merchantSiteId",
    /*String*/ googlePayMerchantId = "googlePayMerchantId",
    /*String*/ googlePayMerchantName = "googlePayMerchantName",
    /*String*/ googlePayGateway = "googlePayGateway",
    /*String*/ googlePayGatewayMerchantId = "googlePayGatewayMerchantId",
    /*String*/ currency = "currency",
    /*String*/ amount = "amount",
    /*PaymentOption*/ paymentOption = paymentOption,
    /*String?*/ userTokenId = "userTokenId",// Optional
    /*String?*/ clientUniqueId = "clientUniqueId",// Optional
    /*String*/ clientRequestId = "clientRequestId",
    /*BillingAddress?*/ billingAddress = billingAddress,// Optional
    /*ShippingAddress?*/ shippingAddress = shippingAddress,// Optional
    /*UserDetails?*/ userDetails = userDetails,// Optional
    /*MerchantDetails?*/ merchantDetails = merchantDetails,// Optional
    /*String*/ countryCode = "countryCode"// Optional, 2 digits country code
)

Example Output

class Authenticate3dOutput(
    val result: String ? ,
    val userPaymentOptionId : String ? ,
    val cavv : String ? ,
    val eci : String ? ,
    val dsTransID : String ? ,
    val ccCardNumber : String ? ,
    val bin : String ? ,
    val last4Digits : String ? ,
    val ccExpMonth : String ? ,
    val ccExpYear : String ? ,
    val ccTempToken : String ? ,
    val transactionId : String ? ,
    val threeDReasonId : String ? ,
    val threeDReason : String ? ,
    val challengePreferenceReason : String ? ,
    val isLiabilityOnIssuer : Boolean ? ,
    val cancelled : Boolean,
    val challengeCancelReasonId: String ? ,
    val challengeCancelReason : String ? ,
    val errorCode : Int ? ,
    val errorDescription : String ? ,
    val rawResult : Map < String, Any > ?
)

Handling the authenticate3d() Response

The response from the authenticate3d() call includes the result parameter, which can have one of these values:

Perform the Server-Side Payment

Please press here to continue.