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)

Checkout Initialization

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

• merchantId and merchantSiteId as received from Nuvei Integration Support
• 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,
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(
  /*Activity*/
  activity = this, // The activity that presents the checkout screen
  /*NVPayment*/
  input = input, // NVPayment object with all the required info for checkout screen and transaction
  /*Boolean*/
  forceWebChallenge = true, // Flag indicating whether 3DS challenge screen should be forced as Web challenge
  callback = object: Callback < NVOutput > {
    override fun onComplete(response: NVOutput) {
      when(response.result) {
        NVOutput.APPROVED - > {
          /* TODO: Handle approved transaction */ }
        NVOutput.CANCELLED - > {
          /* TODO: Handle cancelled transaction */ }
        NVOutput.DECLINED - > {
          /* TODO: Handle declined transaction */ }
        NVOutput.ERROR - > {
          /* TODO: Handle error */ }
      }
    }
  }
) {
  response,
  activity,
  declineFallback - >
  // TODO: Check the response and call the `declineFallback` with `dismiss` or `backToCheckout`
  declineFallback(CheckoutCompletionAction.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]?
}