Flutter iOS Integration
Compatibility
The Gateway SDK requires a minimum of iOS 11+ and is compatible with Swift 5 projects.
Installation
Follow these steps to add the Gateway SDK into your Xcode Project:
- From your Merchant Admin portal, download the latest version of the SDK as a zip file.
- Drag the Gateway-SDK.xcframework folder in your Xcode project.
- Add the library to your target's "Frameworks, Libraries, and Embedded Content".
- Do import Gateway of the framework where needed.
- You can also set the
Gateway-SDK.xcframeworkas a local swift package with the .binaryTarget option. - SDK depends on the
uSDK.xcframeworkbundled in the ZIP file format. Ensure to include this in your project.
For more information about downloading the SDK, see Mobile SDK Integration.
// AppDelegate.swift import Gateway
Initialize the SDK
The iOS SDK must be initialized before using it. It is recommended to perform this operation in your AppDelegate class.
To initialize the SDK in a Flutter application, implement the platform-specific code that handles method calls from Flutter. Follow these steps to initialize the SDK:
- Add the following code to handle SDK initialization in platform-specific code:
- Ensure that your
MethodChannelis set up correctly to call theinitialiseGatewaySDKmethod. This is typically done in theAppdelegateor another appropriate place in your iOS swift code. - To initialize SDK from dart, refer the following code.
- Reduces PCI compliance costs as you do not handle or store any payment details.
- Facilitates ease of integration as you do not need to directly handle the values for the request fields stored in a session.
- Reduces internal fraud as your staff has limited access to payer's details.
- Allows you to update the request fields and values stored against a session. This is useful when a credit card expires or other details of a payer change.
- Allows you to retrieve the request fields and values contained in a session by specifying the session identifier.
- Two API calls must be made.
- Ensure that these requests are made from your private server since they are protected by an API password.
- Return the session information back to the mobile application.
- Pass this information to SDK with the collect card information.
- Pass the information directly to the gateway using an existing session ID.
- To update card information, implement the platform specific code to handle method call from Flutter.
- You can call preceding method similar to the following method:
- Create and Update a session using the SDK.
- Update the session with the customer's card details through the Gateway SDK.
GatewayAPIupdateSessionmethod. - Return the Session ID to your server and call the Create or Update Token method on the gateway with your private API credentials.
- A token ID is returned and can be retained on your servers as a card-on-file.
- Frictionless: The Access Control Server (ACS) has collected enough information about the cardholder to authenticate them. No other action is needed by the user.
- Challenge: The ACS requires the cardholder to complete an additional authentication step, which is to enter a onetime-password, login to their issuing bank, and so on. The embedded mobile SDK handles displaying a native device interface for this challenge. The UI for these screens can be customized by passing
UICustomizationparams into the Gateway SDK during initialization. - Correlate a payment and an authentication transaction by using the same order ID for each transaction.
- Each transaction is displayed as a separate transaction in the gateway's web portal, such as UUID.
- Important information about the outcome.
- Actions performed during the operation.
- PROCEED: Indicates "OK to continue with a payment or authorization".
- DO_NOT_PROCEED: Indicates something failed during the authentication operation. The
AuthenticationErrorobject can be used to determine more. - AuthenticationError.recommendation_ResubmitWithAlternativePaymentDetails : Indicates that you should ask the payer for alternative payment details. For example, a new card or another payment method, and resubmit the request with the new details.
- AuthenticationError.recommendation_AbandonOrder : Indicates the payment service provider, scheme, or issuer require you to abandon the order.
- AuthenticationError.recommendation_DoNotProceed : Indicates the gateway fails the request, but there is no way for this transaction to succeed.
- To perform authentication, implement platform-specific code to handle method calls from Flutter.
- If the authentication fails, you can examine the
response.errorfor more information about the cause.
func initialiseSDK(call: FlutterMethodCall,result: FlutterResult){
// Extract and cast arguments
guard let merchantDetails = call.arguments as? [String: Any],
let merchantId = merchantDetails["merchantId"] as? String ,
let merchantName = merchantDetails["merchantName"] as? String,
let merchantUrl = merchantDetails["merchantUrl"] as? String,
let region = merchantDetails["region"] as? String else {
return
}
// Initialize the GatewaySDK
GatewaySDK.shared.initialize(merchantId: merchantId, merchantName: merchantName, merchantUrl: merchantUrl, region: region)
result("Success")
}
// Define the MethodChannel
static const MethodChannel _channel = MethodChannel('com.yourcompany.gateway_sdk');
// Prepare arguments for the method call
final Map<String, dynamic> arguments = {
'merchantId': merchantId, // your merchant id
'merchantName': merchantName, // your merchant name
'merchantUrl': merchantUrl, // your merchant url
'region': region, // your region
};
// Invoke the method and handle the result
_channel.invokeMethod('initialiseGatewaySDK', arguments).then((result) {
// Handle success result here
}).catchError((error) {
// Handle error result here
});
Session overview
The Gateway 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 Payment Session documentation.
Key benefits
The key benefits are as follows:
Create a session
Create a session with the gateway to initiate the payment flow on a mobile device.
To prepare the session for mobile transactions:
| Request Parameter | Example |
|---|---|
| authenticationLimit | 25 |
Update the session
This table describes the request parameters for update the session.
| Request Parameter | Existence | Example |
|---|---|---|
| order.id | Required | your-order-id |
| order.amount | Required | 1.23 |
| order.currency | Required | AUD |
| authentication.acceptVersions | Required | 3DS2 |
| authentication.channel | Required | PAYER_APP |
| authentication.purpose | Required | PAYMENT_TRANSACTION |
Once a session is created on your server, you should:
Collecting card information
The SDK method to updateSession is optional to use, but is recommended to help with merchant server PCI scope. However, the card and token information can be loaded through a different API design and must be present in the session before the call is made in the SDK to authenticate the payer.
Manual card entry
Follow these steps to make a manual card entry.
func updateSession(call:FlutterMethodCall, result: @escaping FlutterResult) {
guard let sessionDetails = call.arguments as? [String: Any],
let name = sessionDetails["nameOnCard"] as? String ,
let number = sessionDetails["number"] as? String,
let expiryMonth = sessionDetails["month"] as? String,
let expiryYear = sessionDetails["year"] as? String,
let sessionId = sessionDetails["sessionId"] as? String,
let currency = sessionDetails["currency"] as? String,
let amount = sessionDetails["amount"] as? String,
let orderId = sessionDetails["orderId"] as? String,
let cvv = sessionDetails["securityCode"] as? String,
let apiVersion = sessionDetails["apiVersion"] as? String else {
return
}
// 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.
var request = GatewayMap()
request.sourceOfFunds.provided.card.nameOnCard.value = name
request.sourceOfFunds.provided.card.number.value = number
request.sourceOfFunds.provided.card.securityCode.value = cvv
request.sourceOfFunds.provided.card.expiry.month.value = expiryMonth
request.sourceOfFunds.provided.card.expiry.year.value = expiryYear
GatewayAPI.shared.updateSession(sessionId, apiVersion: apiVersion, payload: request, completion: { response in
// Handle the response and invoke the callback function to update the dart code.
})
}
// Assuming `gatewayChannel` is an object that has `invokeMethod` function
// and `updateSessionMethod` is a string representing the method name
gatewayChannel.invokeMethod(updateSessionMethod, {
'nameOnCard': cardHolderName, // Cardholder's name
'number': cardNumber, // Card number
'securityCode': cvvCode, // CVV code
'month': expiryMonth, // Expiry month
'year': expiryYear, // Expiry year
'sessionId': sessionId, // Session ID
'amount': '1.97', // Amount to be processed
'currency': 'USD', // Currency code
'orderId': 'your-order-id', // Order ID
'apiVersion': 61, // API version
});
Tokenization
The SDK provides support to update a session with card information, you can use that session to perform several operations with the gateway. Tokenization provides a way to retain a card on file and can be performed on your server with a valid session.
Create a card token
Follow these steps to use the mobile SDK to facilitate creating a card token.
For more information about Tokenization, see Create or Update Token documentation.
Apple Pay
The Gateway SDK includes a helper utility for collecting information from a Apple Pay Wallet.
Payer authentication
3D Secure
3-D Secure or 3DS authentication is designed to protect online purchases against credit card fraud by allowing you to authenticate the payer before submitting an Authorization or Pay transaction.
The EMV 3DS, also known as 3DS2 in the gateway, is the new version designed to enhance security in online purchases while providing frictionless checkouts to payers who are considered low risk by the Access Control Server (ACS).
The ACS may determine the risk using merchant information, device fingerprinting, previous interactions with the payer, or both. The ACS subjects the payer to a challenge, for example, entering a PIN, only where additional verification is required to authenticate the payer thereby providing increased conversion rates.
Supported authentication schemes include Mastercard Identity Check, Visa Secure, and American Express SafeKey.
Authentication within the mobile SDKs is limited to 3DS2 only. If 3DS2 is not available, the authentication does not proceed. However, you can still proceed with the payment if the gateway recommends you do so.
For more information about 3D Secure Authentication, see 3-D Secure Authentication documentation.
Authentication details
The embedded mobile SDK collects device metrics to send to the gateway along with your transaction information when you perform mobile SDK authentication, that is, verify the identity of a cardholder in a mobile application.
Provide as much information as possible about the payer and the transaction to increase the likelihood of the authentication being successful.
This additional information can be added to your session with an Update session request.
| Parameter | Existence | Description |
|---|---|---|
| order.merchantCategoryCode | Optional | Same as the code in your merchant profile. |
| billing.address parameter group | Optional | It is strongly recommended you include this in your request whenever possible. |
| shipping.address parameter group | Optional | It is strongly recommended you include this in your request whenever possible. |
| customer parameter group | Optional | It is strongly recommended you include this in your request whenever possible. |
The device parameter group as seen in the documentation is only relevant for browser-based payments. It should not be used for mobile based payer authentications. These metrics help the system to determine how or if to authenticate the cardholder. During authentication, the user can expect to experience one of two authentication flows:
For more information, see Authenticate Payer documentation.
authentication.PSD2.exemption is currently not supported in the SDK. Perform authentication
Payer authentication is considered a transaction on its own in the gateway, and therefore needs a unique transaction ID.
If you are collecting payment for an order, you can:
AuthenticationHandler.authenticate(activityContext, session, "your-auth- transaction-id", callback)
your-auth-transaction-id is a unique identifier for this transaction which distinguishes it from any other transaction on the order. This is needed as the gateway will use the your-auth-transaction-id to look up the authentication results that it stored when you asked the SDK to authenticate the payer. The gateway then passes the required information to the acquirer for the pay request.Interpret the response
The authenticate method will return an AuthenticationResponse object that contains:
The most important field to consume is response.recommendation. It may contain the value PROCEED or DO_NOT_PROCEED.
From gateway API version 70 and later, you can get the following errors:
For more information, see the Integration guides.
Follow these steps to perform authentication:
func performAuthentication(call: FlutterMethodCall,result:@escaping FlutterResult) {
//Retrieve sessionID, orderId, apiVersion and transactionID from call.arguments passed from dart code. Refer updateSession function
let authenticationId = UUID().uuidString
var request = AuthenticationRequest(navController: navController,
apiVersion: apiVersion,
sessionId: sessionId,
orderId: orderId,
transactionId: authenticationId)
AuthenticationHandler.shared.authenticate(request) {
(response) in
switch response.recommendation {
case .doNotProceed: fallthrough
case .proceed:
// Handle the success response and invoke the callback function to update the dart code.
@unknown default:
//Handle the error response and invoke the callback function to update the dart code.
}
}
}
// Assuming `gatewayChannel` is an object that has `invokeMethod` function
// and `authenticateMethod` is a string representing the method name
gatewayChannel.invokeMethod(authenticateMethod, { "session": 'session-object', "authenticationId": authenticationId })
.then(result => {
// Extract the recommendation from the result
const recommendation = result['recommendation'];
// Check the recommendation and handle accordingly
if (recommendation === 'PROCEED') {
// Continue to payment/authorization
handlePaymentAuthorization();
} else if (recommendation === 'DO_NOT_PROCEED') {
//Handle Authentication not successful, re-enter card details
}
});