Overview

The iOS Mobile SDK integration is an SDK for native mobile apps to perform 3D-Secure-Only validation (for 3D-Secure v1 or v2) using the Nuvei authenticate3d() method.

This topic is a step-by-step guide to integrate Nuvei payment solutions into native mobile apps on the iOS platform.

Install the iOS Mobile SDK

Install the SDK

1. Download the following three frameworks from this GitHub location – NuveiMobileSDK-iOS-Release:
   • NuveiMobileSDK.xcframework
   • JOSESwift.xcframework
   • CryptoSwift.xcframework
2. Locate these frameworks inside your Xcode project folder.
3. Then drag the frameworks to Xcode, in target settings:
   “General” tab > “Frameworks, Libraries and Embedded Content” section.
4. Mark all three frameworks as “Embed & Sign“.

Customize the UI

To be able to customize the UI of 3D challenge screens, you can provide a set of customization definition objects. This customization definition is optional and can be skipped; the default customization is used in this case.

 let customization = NuveiUICustomization(
    toolbarCustomization: NuveiToolbarCustomization(
        headerText: "SECURE CHECKOUT",
        textFont: UIFont.boldSystemFont(ofSize: 22),
        textColor: .white,
        backgroundColor: .nuveiDefaultColor
    ),
    labelCustomization: NuveiLabelCustomization(
        textFont: UIFont.systemFont(ofSize: 14),
        textColor: .black,
        headingTextFont: UIFont.systemFont(ofSize: 14),
        headingTextColor: .white
    ),
    textBoxCustomization: NuveiTextBoxCustomization(
        textFont: UIFont.systemFont(ofSize: 14),
        textColor: .black,
        borderColor: .black,
        cornerRadius: 0,
        borderWidth: 1
    )
)
let nextButtonCustomization = NuveiButtonCustomization(
    textFont: UIFont.boldSystemFont(ofSize: 17),
    textColor: .white,
    backgroundColor: .nuveiDefaultColor,
    cornerRadius: 5
)
let cancelButtonCustomization = NuveiButtonCustomization(
    textFont: UIFont.boldSystemFont(ofSize: 17),
    textColor: .nuveiDefaultColor,
    backgroundColor: .white,
    cornerRadius: 5
)
customization.setButtonCustomization(nextButtonCustomization, for: .next)
customization.setButtonCustomization(nextButtonCustomization, for: .continue)
customization.setButtonCustomization(nextButtonCustomization, for: .resend)
customization.setButtonCustomization(nextButtonCustomization, for: .submit)
customization.setButtonCustomization(cancelButtonCustomization, for: .cancel)

NuveiMobileSDK.customization = 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 also important to set the order from the server-side to prevent front-end user manipulation.
  You can simulate the Open Order functionality using a Postman script, follow our guide on using this here. Then use this Postman script to run and test the /openOrder method.

  For the /openOrder authentication, you must create the checksum field. This is a SHA-256 encryption, of the concatenation of the following fields, in this order:
  merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp and your secret key in 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"
  }

3D-Secure Authentication

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

Example Input

// Using card details
let paymentOption = try! PaymentOption(
    card: CardDetails(
        cardNumber: cardNumberField.text,
        cardHolderName: cardHolderNameField.text,
        cvv: cvvField.text,
        expirationMonth: monthField.text,
        expirationYear: yearField.text
    )
)
// Using card User Payment Option ID
let paymentOption = try! PaymentOption(
    userPaymentOptionId: userPaymentOptionId
)
// Using card User Payment Option ID with updated expiration date
let paymentOption = try! PaymentOption(
    userPaymentOptionId: userPaymentOptionId,
    card: CardDetails(
        expirationMonth: monthField.text,
        expirationYear: yearField.text
    )
)
let input = Authenticate3dInput(
    sessionToken: sessionToken,// required
    merchantId: merchantId,// required
    merchantSiteId: merchantSiteId,// required
    currency: currencyField.text!,// required
    amount: amountField.text!,// required
    paymentOption: paymentOption,// required
    clientUniqueId: clientUniqueId,// optional
    clientRequestId: clientRequestId,// optional
    customData: customData,// optional
    billingAddress: billingAddress,// optional
    shippingAddress: shippingAddress,// optional
    userDetails: userDetails,// optional
    merchantDetails: merchantDetails,// optional
    timeout: 10,// in minutes, optional
    requestTimeout: 30// in seconds, optional
)

// The viewController is used to present the challenge view controller(s) from 
NuveiMobile.authenticate3d(viewController: navigationController, input: input) { (output) in
    debugPrint("Output = \(output)")
}

In the completion block, use the output. The following is the output class:

Example Output

public class Authenticate3dOutput {
    public enum Result: String {
        case approved, declined, redirect, error, other
    }    
    public let cavv: String?
    public let eci: String?
    public let xid: String?
    public let dsTransID: String?
    public let rawResult: [String: Any]?
    public let result: Result
    public let errorCode: Int?
    public let errorDescription: String?
}

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.