Overview

The iOS Simply Connect SDK integration is an SDK for native mobile apps. It provides a full checkout experience and end-to-end payment processing for cards and APMs.

This document guides you through the process of integrating Nuvei payment solutions into your native mobile apps on the iOS platform.

General Flow

• Authenticate directly from your server to Nuvei’s server (server-to-server) via API.
• Embed and invoke the SDK functionalities:
  • Set basic customization
  • Initialize the checkout
  • Call the checkout() method to invoke the Simply Connect checkout interface to Verify the response using a webhook (DMN) or the getPaymentStatus API call.

UI Implementation

With Native Simply Connect, you can customize the top bar of Simply Connect:

• Background
• Logo
• Text and font

Example UI Customization

let customization = NuveiUICustomization(

    logo: appLogo, // your app logo

    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)
NuveiSimplyConnect.setup(customization) // also supports environment argument

Testing with Nuvei’s Integration Environment

The NuveiSimplyConnect.setup function also supports the environment argument. To configure the SDK to work with Nuvei’s integration testing environment, specify NuveiSimplyConnect.setup(environment: NuveiSimplyConnect.Environment.integration, customization: customization). If you do not specify an environment, by default, the SDK works with Nuvei’s production environment.

If you do not specify environment, by default, the SDK works with Nuvei’s production environment.

Checkout Initialization

For initialization, you need to set the following input fields:

• merchantId and merchantSiteId – As received from Nuvei Integration Support.
• applePayMerchantId – Merchant ID value that appears in the app’s target settings, in Signing & Capabilities > Apple Pay capability.
• applePayMerchantName – Merchant name to appear on the Apple Pay screen, which must follow Apple’s App Review Guidelines for Apple Pay.
• sessionToken – Retrieved from /openOrder.
• amount and currency

The following optional fields and classes, which are described in https://docs.nuvei.com/api/main/indexMain_v1_0.html?json#payment, are recommended:

• clientUniqueId – To set your identifier for the transaction.
• clientRequestId – Optional for idempotency support.
• customData – Set custom data to the transaction that can be viewed on the reporting.
• billingAddress
• shippingAddress
• userDetails
• merchantDetail

let input = NVInput(
sessionToken: sessionToken,
merchantId: merchantId,
applePayMerchantId: applePayMerchantId
applePayMerchantName: applePayMerchantName
merchantSiteId: merchantSiteId,
currency: currencyField.text ?? "",
amount: amountField.text ?? "",
paymentOption: paymentOption,
userTokenId: userTokenId,// optional
//clientUniqueId: "OPTIONAL",// optional
clientRequestId: clientRequestId,// optional
//customData: "OPTIONAL",// optional
billingAddress: billingAddress,// optional
shippingAddress: shippingAddress,// optional
userDetails: userDetails,// optional
merchantDetails: merchantDetails,// optional
countryCode: 2-letter ISO country code; for example, US //optional
dynamicDescriptor: dynamicDescriptor,// optional
timeout: 10,// in minutes, optional
requestTimeout: 30// in seconds, optional	
)

Checkout Invocation

Once you have an instance of the NVInput class (e.g. “input”), call the NuveiSimplyConnect.checkout(...) method as follows:

NuveiSimplyConnect.checkout(
  // The process (UIViewController or UIApplication, or any object that extends `NVUIOwner` protocol) that presents the checkout screen
  uiOwner: navigationController,
  // NVInput object with all the required info for checkout screen and transaction
  authenticate3dInput: input,
  // Flag indicating whether 3DS challenge screen should be forced as Web challenge
  forceWebChallenge: forceWebChallenge,
  // Result callback that will be called in the end of the checkout process
  callback: {
    output in
    switch (output.result) {
      case.approved:
        /* TODO: Handle approved transaction */ debugPrint("approved")
      case.declined:
        /* TODO: Handle approved transaction */ debugPrint("declined")
      case.cancelled:
        /* TODO: Handle approved transaction */ debugPrint("cancelled")
      case.error:
        /* TODO: Handle approved transaction */ debugPrint("error")
    }
  },
  // Decline fallback decision callback that may be called during the checkout process, for instance when error detected in one of payment methods processing
  declineFallbackDecision: {
    output,
    viewController,
    completion in
    // TODO: Check the `output` and call the `completion` with `.dismiss` or `.backToCheckout`
    completion(.dismiss)
  }
)

Example Output

The output fields returned include:

• result: Values can be either APPROVED, DECLINED, or ERROR (in case of any error).
• errCode and errorDescription: In the case of an error, these fields contain the decline reason and error description. Please view Response Handling for details.

public class NVCreatePaymentOutput {
    public enum NVOutputResult: String {
        case approved, declined, cancelled, error
    }
    
    public let result: NVOutputResult
    public let userPaymentOptionId: String?
    public let ccCardNumber: String?
    public let bin: String?
    public let last4Digits: String?
    public let ccExpMonth: String?
    public let ccExpYear: String?
    public let transactionId: String?
    public let threeDReason: String?
    public let threeDReasonId: String?
    public let challengeCancelReasonId: String?
    public let challengeCancelReason: String?
    public let isLiabilityOnIssuer: Bool?
    public let challengePreferenceReason: String?
    public let errorCode: Int?
    public let errorDescription: String?
    public let rawResult: [String: Any]?
}