CommWeb payment gateway iOS SDK

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:

1. From your Merchant Admin portal, download the latest version of the SDK in a ZIP file format.

For more information about downloading the SDK, see Mobile SDK Integration.

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

// AppDelegate.swift
import Gateway

5. You can also set the Gateway-SDK.xcframework as a local swift package with the .binaryTarget option.
6. The SDK depends on the uSDK.xcframework bundled in the zip file. Ensure to include this in your project.

Initialize the SDK

The iOS SDK must be initialized before using it. It is recommended to perform this operation in your AppDelegate class.

// AppDelegate.swift
GatewaySDK.shared.initialize(
    merchantId: "YOUR_MERCHANT_ID",
    merchantName: "Your Merchant Name",
    merchantUrl: "https://your-merchant-url.com",
    region: GatewayRegion.mtf
)

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

• 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.

Create a session

Create a session with the gateway to initiate the payment flow on a mobile device.

• Two API calls must be made to prepare this session for mobile transactions.
• These calls are secured by an API password and thus need to be called from your private server.

Update the session

Once a session is created on your server, you should return the session information back for use in further operations.

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

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

Pass the information directly to the gateway using an existing session.

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

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.

Follow these steps to use the mobile SDK to facilitate creating a card token.

1. Create and Update a Session using the SDK.
2. Update the session with the customers card details via the Gateway SDK. GatewayAPIupdateSession method.
3. Return the Session Id to your server and call the Create or Update Token method on the gateway with your private API credentials.
4. A token Id is returned and can be retained on your servers as a card-on-file.

For more information about Tokenization, see Create or Update Token documentation.

Apple Pay

Your app may use Apple Pay to collect card details as an alternative to collecting payment card details using fields.

Configuration

To accept payments with Apple Pay, you must first configure your app for Apple Pay. For more information see Configuring your Environment in Apple's developer documentation.

Apple Pay button display

Apple provides the PKPaymentButton that you may use on your app's payment screens.

To determine if the device supports Apple Pay, use the canMakePayments method on PKPaymentAuthorizationController.

Construct and use a PKPaymentRequest

For information about how to construct and use a PKPaymentRequest, see Creating Payment Requests in Apple's developer documentation.

Update a session with a PKPAYMENTTOKEN

After a user has authorized Apple Pay, your app needs to update the gateway session with that payment token.

Follow these steps to update a session with a PKPAYMENTTOKEN.

1. Get the payment token as a String to send the payment token to the gateway.

let tokenString = String(data: payment.token.paymentData, encoding.utf8)

2. Populate the token string into the GatewayMap as the devicePayment and specify that the token came from Apple Pay by setting the walletProvider.

var request = GatewayMap()
request.sourceOfFunds.provided.card.devicePayment.paymentToken = tokenString
request.order.walletProvider = "APPLE_PAY"

3. The GatewayMap for your request can now be sent to the gateway using the updateSession method on the GatewayAPI object.

GatewayAPI.shared.updateSession("< session id#>", apiVersion: ""< Gateway API Version#>", payload: request) { (result) in
    switch result {
    case .successi(let response):
        print(response.description)
    case .error(let error):
        print(error)
    }
}

Complete an Apple Pay transaction

Once a session has been updated with the payment token from Apple Pay

• the payment can be completed from your merchant service just as any other payment.
• set the order.walletProvider field to APPLE_PAY when completing a payment on a session that is using Apple Pay.

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 information provided by the merchant, device fingerprinting, previous interactions, or both, with the payer. 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 will not proceed. However, you can still proceed with the payment if the gateway recommends you do so.

For more information on 3D Secure, 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 app.

Provide as much information about the payer and the transaction as possible to increase the likelihood of the authentication being successful.

This additional information can be added to your session with an Update session request.

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 auth flows:

1. Frictionless: The ACS has collected enough information about the cardholder to authenticate them. No other action is needed by the user.
2. Challenge: The ACS requires the cardholder complete an additional authentication step which is to enter a onetime-password, login to their issuing bank, and so on. The new mobile SDK handles displaying a native device interface for this challenge. The UI for these screens can be customized by passing UICustomization params into the Gateway SDK during initialization.

For more information, see Authenticate Payer documentation.

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

• 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.

let request = AuthenticationRequest (navController: navController,
            apiVersion: apiVersion,
            sessionId: sessionId,
            orderId: orderId,
            transactionId: authenticationTxnId)
AuthenticationHandler.shared.authenticate(request) { (response) in
    // handle response
}

Interpret the response

The authenticate method returns an AuthenticationResponse object that contains:

• important information about the outcome, and
• actions performed during the operation.

The most important field to consume is response.recommendation. It may contain the value proceed or doNotProceed.

• proceed: Indicates "OK to continue with a payment or authorization".
• doNotProceed: Indicates something failed during the authentication operation. The AuthenticationError object can be used to determine more.

From Gateway API version 70 and above, you can get the following errors:

• 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.

For more information, see the Integration guides.

AuthenticationHandler.shared.authenticate(request) { (response) in
    DispatchQueue.main.async {
        switch response.recommendation {
        case .doNotProceed:
            if let error = response.error {
            print ("SDK Error:\(error.localizedDescription)")
            if let authError = error as? AuthenticationError,
            authError ==
        .recommendation_ResubmitWithAlternativePaymentDetails {
                //"Authentication not successful, re-enter card details"
              }
            }
        // "Authentication not successful"
        case .proceed:
            // Proceed to submit the payment, authorization etc
            }
        }
    }

If the authentication fails, examine the response.error for more information about the cause.

Additional information

Device and simulator builds

The Gateway SDK is released with two builds, a device version and a simulator version.

Bitcode can only be enabled for binaries that do not support x86_64. Customers are likely to prefer the device version of SDK at release, so they can enable bitcode in their apps which allows the app to have a smaller footprint on a userʼs device.

However, many developers prefer to use a simulator while developing, so the x86_64 architecture is necessary. Additionally, during development, the app footprint is usually not a big concern. The gateway releases both bitcode-enabled Device and bitcode-disabled Simulator versions of the SDK to allow customers to choose what they want to work with in any given scenario.

It is important to emphasize that the functionality and interface is exactly the same.

See Apple's documentation for more information.

• Apple thinning overview
• Basic optimization