Integration Steps
To use the iOS or Android Mobile SDK with the Mastercard Gateway, follow these instructions.
Step 1: Download the SDK and documentation
The iOS and Android Mobile SDK and related documentation can be downloaded from the Merchant Administration (MA):
- Log in to the MA, and then select Admin > Software Download.
- Select the appropriate link and follow the prompts to download the required file.
The Admin - Software and Documentation Downloads screen displays. It contains the Mobile SDK and the Mobile SDK Integration Guides.
Device and simulator builds for iOS
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:
Step 2: Install and initialize the SDK
This section includes instructions on how to install and initialize the SDK.
iOS
To install the SDK into your Xcode project:
- Drag the
Gateway-SDK.xcframeworkfolder into your Xcode project. - Add the library to your target's Frameworks, Libraries and Embedded Content.
- Do import Gateway of the framework where needed.
- If needed, set the Gateway-SDK.xcframework as a local swift package with the .binaryTarget option.
- Ensure to include uSDK.xcframework in your project. The SDK depends on the uSDK.xcframework bundled in the ZIP file.
// AppDelegate.swift import Gateway
You must initialize the SDK before using it. It is recommended to perform this operation in your AppDelegate class.
// AppDelegate.swift
GatewaySDK.shared.initialize(
merchantId: "MERCHANT_ID",
merchantName: "Merchant Name",
merchantUrl: "https://merchant-url.com",
region: "Your gateway region"
Android
The SDK is packaged as a maven repository.
To install the SDK into your project:
- Unzip the file in the root directory of your Android project, For example, ~/my-android- project/gateway-repo).
- Add a reference to this local repository in the
build.gradlefile of your project. - In the
build.gradlefile of your app module, include the Mobile SDK as a dependency.
// build.gradle
allprojects {
repositories {
mavenCentral()
google()
// Gateway Android SDK repo
maven {
url "$rootDir/gateway-repo"
}
}
}
// 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>.
You must initialize the SDK before using it. It is recommended to perform this operation in your custom Application class in the onCreate()function.
// CustomApplication.kt
override fun onCreate()
{
super.onCreate()
// init Gateway SDK
GatewaySDK.initialize
(
this,
"YOUR_MERCHANT_ID",
"Your Merchant Name",
"https://your-merchant-url.com",
region: "Your gateway region",
callback
)
}
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
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.
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 SESSIONAPI request. For the request fields, see theCREATE SESSIONrequest fields table. - To update the session, send the
UPDATE SESSIONrequest with the required fields. For the request fields, see the requiredUPDATE SESSIONrequest fields table.
Table: 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 3D Secure (3DS) 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 | 3DS 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 |
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
Sessionobject.
let sessionId = "session-id" let apiVersion = "61" // 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
val session = Session(
id = "session-id",
amount = "1.23",
currency = "USD",
apiVersion = "61", // api version used to create the session
orderId = "order-id" // must match order id used on your server
)
apiVersion must be the same for the whole transaction lifecycle, from session creation to the final payment.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.
- 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 and Google Pay.
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.
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
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.
// 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) in
// handle result
}
// 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 operation in your server with the valid session ID. For more information, see Tokenization.
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 or AUTHORIZE payment transaction request from your server, including the session ID in the request. For more information, see Making a Server API Request.