Integration Types
Other Features
Card Payments
Mobile Wallets
Alternative Payment Methods
Resources
To use the iOS or Android Mobile SDK with the American Express Payment Gateway, follow these instructions.
The iOS and Android Mobile SDK and related documentation can be downloaded from the Merchant Administration (MA):
The Admin - Software and Documentation Downloads screen displays. It contains the Mobile SDK and the Mobile SDK Integration Guides.
The Mobile SDK for iOS is released with two builds:
For more information, see Apple's documentation:
This section includes instructions on how to install and initialize the SDK.
To install the SDK into your Xcode project:
Gateway-SDK.xcframework
folder into your Xcode project.// 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"
The SDK is packaged as a maven repository.
To install the SDK into your project:
build.gradle
file of your project.// build.gradle allprojects { repositories { mavenCentral() google() // Gateway Android SDK repo maven { url "$rootDir/gateway-repo" } } }
build.gradle
file of your app module, include the Mobile SDK as a dependency.// 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", GatewayRegion.MTF, callback ) }
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:
CREATE SESSION
API request. For the request fields, see the CREATE SESSION
request fields table.UPDATE SESSION
request with the required fields. For the request fields, see the required UPDATE SESSION
request 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:
Session
object.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.You can collect the payment information from the payer in multiple ways:
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.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.
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.