# Integrate Mobile Payments
source: https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/mobile-integration/integrate-mobile-payments/index.md

To use the iOS or Android Mobile SDK with the Mastercard Gateway, follow these instructions.

## Step 1: Download the SDK and documentation {#step-1-download-the-sdk-and-documentation}

The iOS and Android Mobile SDK and related documentation can be downloaded from the Merchant Administration (MA) portal:

1. Log in to the MA portal, and then select Admin \> Software Download.

   Note: If you cannot see Software Download in the Admin menu, ask your payment service provider for Mobile SDK access. The Admin - Software and Documentation Downloads screen displays. It contains the Mobile SDK and the Mobile SDK Integration guides.

   <br />

2. Select the appropriate link and follow the prompts to download the required file.

### Device and simulator builds for iOS {#device-and-simulator-builds-for-ios}

The gateway releases both bitcode-enabled device and bitcode-disabled simulator versions of the SDK to allow you to choose what you want to work with in any given scenario. The functionality and interface are the same for both versions.

The Mobile SDK for iOS is released with two builds:

* **Device version**: Device version has bitcode enabled, which allows the app to have a smaller footprint on a userʼs device. However, the version does not support the x86_64 architecture. Developers tend to prefer the device version of the SDK as the release version.
* **Simulator version**: To use a simulator, you need the x86_64 architecture. This means that the bitcode is disabled, resulting in a larger app footprint. Developers tend to prefer the simulator version during development, where the footprint is not a real concern.

For more information, see Apple's documentation:

* [Apple thinning overview](https://help.apple.com/xcode/mac/8.3/index.html?localePath=en.lproj#/devbbdc5ce4f)
* [Basic optimization](https://developer.apple.com/documentation/xcode/doing-basic-optimization-to-reduce-your-app-s-size)

## Step 2: Install and initialize the SDK {#step-2-install-and-initialize-the-sdk}

This section includes instructions on how to install and initialize the SDK.

### iOS {#ios}

To install the SDK into your Xcode project:

1. Drag the `Gateway-SDK.xcframework` folder into your Xcode project.
2. Add the library to your target's Frameworks, Libraries and Embedded Content.
3. Do import Gateway of the framework where needed.

```swift
// AppDelegate.swift
import Gateway
```

4. If needed, set the `Gateway-SDK.xcframework` as a local swift package with the `.binaryTarget` option.
5. Ensure to include `uSDK.xcframework` in your project. The SDK depends on the `uSDK.xcframework` bundled in the zip file.

Initialize the SDK before using it. It is recommended to perform this operation in your AppDelegate class.

Warning: Contact [your payment service provider](mailto:gateway-support@mastercard.com) to know your gateway region.

<br />

```swift
// AppDelegate.swift
GatewaySDK.shared.initialize(
    merchantId: "MERCHANT_ID",
    merchantName: "Merchant Name",
    merchantUrl: "https://mtf.gateway.mastercard.com",
    region: "Your gateway region"
    )
```

### Android {#android}

The SDK is packaged as a maven repository.

To install the SDK into your project:

1. Unzip the file in the root directory of your Android project, for example, \~/my-android- project/gateway-repo.
2. Add a reference to this local repository in the `build.gradle` file of your project.

```groovy
// build.gradle

allprojects {
    repositories {
        mavenCentral()
        google()

        // Gateway Android SDK repository
        maven {
            url "$rootDir/gateway-repo"
        }
    }
}
```

3. In the `build.gradle` file of your app module, include the Mobile SDK as a dependency.

Warning: Replace X.X.X with the current version number.

```groovy
// app/build.gradle
implementation 'com.mastercard.gateway:Mobile_SDK_Android:x.x.x'
```

The Mobile_SDK_Android folder contains a maven-metadata.xml file that has information to build the implementation reference for the library. The implementation gradle format is implementation `<groupId>:<artifactId>:<version>`.

Initialize the SDK before using it. It is recommended to perform this operation in your custom Application class in the `onCreate()function`.
Warning: Contact [your payment service provider](mailto:gateway-support@mastercard.com) to know your gateway region.

```kotlin
// CustomApplication.kt
 override fun onCreate()
 {
    super.onCreate()

    // init Gateway SDK
    GatewaySDK.initialize
    (
        this,
        "YOUR_MERCHANT_ID",
        "Your Merchant Name",
        "https://mtf.gateway.mastercard.com",
        region: "Your gateway region",
        callback
    )
 }
```

### Security recommendations for integrating our SDK {#security-recommendations-for-integrating-our-sdk}

* **Update Session Attempts Limitation**: Implement session update attempt limitation to prevent brute force attacks and unauthorized access.
* **Additional Security Measures**:

<!-- -->

* **CAPTCHA Integration**: Use CAPTCHA to validate user authenticity and prevent automated attacks.
* **Biometric Authentication**: Employ fingerprint or face recognition for robust user authentication and to thwart unauthorized access attempts.
* **DDoS Protection**: Implement robust DDoS protection mechanisms to safeguard against volumetric attacks and ensure continuous service availability.
* **Bot Detection**: Incorporate advanced techniques to identify and mitigate malicious bot activities exploiting application vulnerabilities.
* **Rate Limiting**: Enforce strict rate limiting policies to regulate requests from clients or IP addresses, ensuring fair resource allocation and mitigating abuse.
* **SSL Pinning with Our Own Server**: Include SSL pinning to ensure secure communication, preventing man-in-the-middle attacks and unauthorized server access.

## Step 3: Create and update a session {#step-3-create-and-update-a-session}

The Mobile SDK flow is based around the concept of a session. A session is a temporary container for any request fields and values of operations that reference a session. For more information, see [Session Basics](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-session/integrate-hosted-session/create-payment-session/index.md).

Create and update a session with the gateway to initiate the payment flow on a mobile device:

* To prepare this session for mobile transactions, send a [CREATE SESSION](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#session) API request. For the request fields, see the CREATE SESSION request fields table. Warning: As the session requests are secured by an API password, send them from your server, not from the mobile app.
* To update the session, send the [UPDATE SESSION](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#session) request with the required fields. For the request fields, see the required UPDATE SESSION request fields table.

### CREATE SESSION request fields {#create-session-request-fields}

|   Request Parameter   |                                                                                                    Description                                                                                                     | Example |
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|
| `authenticationLimit` | Number of operations which can be submitted to the gateway using this session's ID as a password. The session ID is used as a password in session-authenticated requests related to EMV 3-D Secure authentication. | 25      |

Table: Required UPDATE SESSION request fields

|        Request Parameter        |                                                                                                                Description                                                                                                                 |       Example       |
|---------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------|
| `order.id`                      | Unique identifier for this order.                                                                                                                                                                                                          | your-order-id       |
| `order.amount`                  | Total amount of the order.                                                                                                                                                                                                                 | 1.23                |
| `order.currency`                | Currency of the order.                                                                                                                                                                                                                     | AUD                 |
| `authentication.acceptVersions` | EMV 3-D Secure version that you accept for this payment. If you do not specify a version, 3DS2 is accepted. The gateway uses 3DS2, if supported by the issuer and the card. If 3DS2 is not available, the authentication does not proceed. | 3DS2                |
| `authentication.channel`        | Channel in which the authentication request is being initiated.                                                                                                                                                                            | PAYER_APP           |
| `authentication.purpose`        | Purpose of the authentication.                                                                                                                                                                                                             | PAYMENT_TRANSACTION |

Warning: To authenticate the payer in the SDK, the CREATE SESSION and UPDATE SESSION requests must be made and the session updated with the payment details. The API design determines how and when the payment details are loaded into the session.

Once a session is created on your server:

* Return the session information back to the mobile app for use in further operations.
* Create an instance of the Session object.

#### Example code for iOS {#example-code-for-ios}

```swift
let sessionId = "session-id"
let apiVersion = "100" // API version used to create the session
let orderId = "order-id" // must match order id used on your server
let amount = "1.23"
let currency = "USD"
```

#### Example code for Android {#example-code-for-android}

```swift
val session = Session(
    id         = "session-id",
    amount     = "1.23",
    currency   = "USD",
    apiVersion = "100",       // API version used to create the session
    orderId    = "order-id"  // must match order id used on your server
)
```

Warning: The apiVersion must be the same for the whole transaction lifecycle, from session creation to the final payment.

## Step 4: Collect payment information {#step-4-collect-payment-information}

You can collect the payment information from the payer in multiple ways:

* If your PCI compliance level allows it, you can gather the card details manually and add them to the session. For more information, see [Manual Card Details](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/mobile-integration/integrate-mobile-payments/index.md#manual-card-details).
* If your PCI compliance level does not allow you to handle sensitive data, you can use the Apple Pay or Google Pay payment method to obtain a payment token that represents a card the payer has added to their Apple or Google Pay wallet. You then add the token to the session. For more information, see [Apple Pay](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/mobile-integration/apple-pay/index.md) and [Google Pay](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/mobile-integration/google-pay/index.md). The `updateSession()` function is used in the Mobile SDK to add the payment information, card details, or token to the session. The payment information must be present in the session before you proceed with optional payer authentication and the actual payment transaction.

Warning: The `updateSession()` function is the easiest way to upload the payment details into the session without impacting your PCI scope. However, if the PCI scope is not a concern, you can upload the details in other ways too, such as through the UPDATE SESSION request from your server.

### Manual card details {#manual-card-details}

Gather the card details from the payer on the app screen and pass the information directly to the gateway using the session ID that was returned in the CREATE SESSION response earlier.

#### Example code for iOS {#example-code-for-ios-1}

```kotlin
// The GatewayMap object provides support for building a nested map structure using key-based dot(.) notation.
// Each parameter is similarly defined in your online integration guide.

val request = GatewayMap()

request.sourceOfFunds.provided.card.nameOnCard.value     = nameOnCard
request.sourceOfFunds.provided.card.number.value         = cardNumber
request.sourceOfFunds.provided.card.securityCode.value   = cvv
request.sourceOfFunds.provided.card.expiry.month.value   = cardExpiryMM
request.sourceOfFunds.provided.card.expiry.year.value    = cardExpiryYY

GatewayAPI.shared.updateSession(
    sessionId,
    apiVersion = apiVersion,
    payload = request
) { response ->
    // handle result
}
```

#### Example code for Android {#example-code-for-android-1}

```kotlin
// The GatewayMap object provides support for building a nested map structure using key-based dot(.) notation.
// Each parameter is similarly defined in your online integration guide.

val request = GatewayMap()
    .set("sourceOfFunds.provided.card.nameOnCard", nameOnCard)
    .set("sourceOfFunds.provided.card.number", cardNumber)
    .set("sourceOfFunds.provided.card.securityCode", cardCvv)
    .set("sourceOfFunds.provided.card.expiry.month", cardExpiryMM)
    .set("sourceOfFunds.provided.card.expiry.year", cardExpiryYY)

GatewayAPI.updateSession(session, request, callback)
```

After updating the session with the card details, you can tokenize the card details to allow you to store the token for future use when the payer returns or when you need to perform merchant-initiated transactions. For example, due to recurring payments. To tokenize the card details, use the [CREATE OR UPDATE TOKEN](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#tokenization) operation in your server with the valid session ID. For more information, see [Tokenization](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/tokenization/gw-tokenization/index.md).

## Step 5: Create the payment transaction {#step-5-create-the-payment-transaction}

When the payer has been authenticated and the session contains the payment details such as card details or a token, send the [PAY](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) or [AUTHORIZE](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) payment transaction request from your server, including the session ID in the request. For more information, see [Making a Server API Request](https://developer.mastercard.com/mastercard-gateway/documentation/getting-started/make-server-api-req/index.md).