Overview

The Android Native SDK provides three types of integration:

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

SDK Installation

Manual Integration

The SDK can be installed manually, as follows:

1. Download simply-connect-sdk.aar file.
2. Copy the simply-connect-sdk.aar file to the app/libs folder in your project.
3. Inside the “dependencies” section of your app/build.gradle file, add the following line:

   implementation files('libs/simply-connect-sdk.aar')

Maven/Gradle Integration

1. Inside app level build.gradle file, update the “repositories” section as follows (or add it if doesn’t exist yet):

   repositories {

       mavenCentral()

       maven {

           url ‘https://raw.githubusercontent.com/Nuvei/nuvei-maven-android/master’

       }

   }

2. Inside the “dependencies” section, add the following line:

   implementation("com.nuvei.mobile:simply-connect-sdk:1.0.0")

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:

Android Nuvei Fields Native SDK

Android Simply Connect Native SDK

Android 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 createPayment() 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

You can use our Direct Merchant Notification (DMN) system to verify the response. In this case, you receive a direct notification to the webhook endpoint on your system. Details for the payment are received as shown in the following example.

Using DMNs is always recommended because Simply Connect also supports “Async APM” transactions, which may only return a response several hours later. Nuvei sends you a DMN with a verified response as soon as we have it.

Example DMN

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