Overview

The iOS Native SDK provides three types of integration:

• iOS Nuvei Fields Native SDK –  Provides a UI element for receiving credit card details from the user to perform an end-to-end payment.
• iOS Simply Connect Native SDK – Provides a full checkout experience and end-to-end payment processing for cards and APMs.
• iOS Direct Native SDK – Allows to perform 3DS authentication.

SDK Installation

CocoaPods

1. At the top of the Podfile, add:
   • source 'https://github.com/CocoaPods/Specs.git'
   • source 'https://github.com/Nuvei/nuvei-mobile-pods.git'
2. In the target dependencies section, add pod ‘NuveiSimplyConnect’.
3. Run pod install.

Swift Package Manager

1. Select File > Add Package Dependency….
2. In the Search bar, type https://github.com/Nuvei/nuvei-mobile-simply-connect-ios.
3. Select the desired version.
4. Click Add Package.
5. Select the target in which to add the SDK.
6. Click Add Package.

Manual Integration

1. Download the following three frameworks from this GitHub location.
   • NuveiSimplyConnect-iOS:
     • 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.

Authentication

Authentication for Native Simply Connect is with the Nuvei server-side REST API.

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.

It is important to set the order from the server side to prevent front-end user manipulation.

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 (merchantSecretKey) at the end.

Example /openOrder Request

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

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"
}

Implementation

To integrate Nuvei payment solutions into your Native mobile apps, follow the steps in the relevant guide:

iOS Nuvei Fields Native SDK

iOS Simply Connect Native SDK

iOS Direct Native SDK

Response Verification

You should verify the payment response that you received on your server side before storing the complete payment information in your system.

Since the response from the checkout() method is returned from the client side, it is vulnerable to manipulation by the end user; therefore, you need to verify the response on your server side.

Verify the response using one of the methods described below.

Verification by DMN

Because Simply Connect also supports asynchronous APM transactions in which a final transaction status might not be immediately available, use our Direct Merchant Notification (DMN) system to verify the final status. When Nuvei receives the final transaction status from the APM provider (APPROVED or DECLINED), Nuvei sends a DMN with the final Status of the transaction to your webhook endpoint.

Example Payment DMN with Status=Approved

...ppp_status=OK&PPP_TransactionId=547&TransactionId=1110000000004146935&userid=111&merchant_unique_id=234234unique_id&customData=342dssdee&productId=12345product_id&first_name=Diyan&last_name=Yordanov&email=dido%40domain.com&totalAmount=200&currency=USD&Status=APPROVED,

Verification by /getPaymentStatus Request

Alternatively, you can call the /getPaymentStatus API method from your server side, using the sessionToken (returned from the /openOrder and used in the checkout() method).

Using the sessionToken retrieves the complete and verified payment response, including additional information about the payment and card used for the transaction.

/getPaymentStatus can only be called while the session in which the payment was performed is still open. Once the session expires, you receive a “session expired” response.

The /getPaymentStatus method can only be called at the end of payment processing for that payment. (You can detect the end of payment processing by monitoring the JavaScript events for the final transaction event.)
/getPaymentStatus is not intended for repeated status polling during the payment processing. Doing so may result in your IP address being blocked.

Example /getPaymentStatus Request

{
  "sessionToken": "274ff0d9-c859-42f5-ae57-997641f93471"
}

Example /getPaymentStatus Response

For a full description of responses, refer to /getPaymentStatus.

{
    "transactionStatus": "APPROVED",
    "gwExtendedErrorCode": 0,
    "errorCode": 0,
    "reason": "",
    "authCode": "075449",
    "clientRequestId": "9WD9JCZW9",
    "internalRequestId": 13004281,
    "version": "1.0",
    "transactionId": "2110000000001496240",
    "amount": "10",
    "currency": "USD",
    "merchantId": "<your merchantId>",
    "merchantSiteId": "<your merchantSiteId>",
    "transactionType": "Sale",
    "clientUniqueId": "695701003",
    "errCode": 0,
    "paymentOption": {
        "userPaymentOptionId": "7072706",
        "card": {
            "uniqueCC": "NuBcbNkc7kBwNExS5j/wgIS8sNk="
        }
    }
    "sessionToken": "64fe6953-69d1-440f-8e21-878c85701f09",
    "userTokenId": '<some userTokenId>',
    "status": "SUCCESS"
}

Release Notes

See https://github.com/Nuvei/nuvei-mobile-simply-connect-ios/releases.