3D Secure Authentication
3D Secure (3DS) authentication is designed to protect online purchases against credit card fraud by allowing you to authenticate the payer before you submit an AUTHORIZE or PAY transaction. The 3DS feature of the gateway and the authentication within the Mobile SDK are limited to 3DS2 only. If 3DS is not available, the authentication does not proceed. However, you can still proceed with the payment if the gateway recommends you to do so. For more information about the gateway’s 3DS feature in general, see 3D Secure Authentication.
- To authenticate the payer:
- Use your server to update the session with all the relevant details that can help the authentication to proceed smoother.
- Ask the SDK to perform the authentication.
- Interpret the results returned by the SDK.
Updating the session with authentication details
When you perform Mobile SDK authentication (verify the identity of a cardholder in a mobile app), the Mobile SDK collects device metrics to send to the gateway along with your transaction information.
Provide as much information about the payer and the transaction as possible to increase the likelihood of the authentication being successful. You can add the fields in the following table to your session with an UPDATE SESSION request.
Optional UPDATE SESSION fields
| Field | Description |
|---|---|
order.merchantCategoryCode | Merchant category code. This value is only needed if it differs from the code that has been defined for the acquirer link in your merchant profile. |
billing.address object | Payer’s billing address. It is strongly recommended you include this in your request whenever possible. |
shipping.address object | Address where this order will be shipped. It is strongly recommended you include this in your request whenever possible. |
customer object | Information associated with the payer’s account. It is strongly recommended you include this in your request whenever possible. |
device object defined in the API Reference is only relevant for browser-based payments. Do not use it for mobile-based payer authentication.The above fields help the system to determine how or if to authenticate the cardholder. During authentication, the user goes through one of the following authentication flows:
- Frictionless flow:
The Access Control Server (ACS) has collected enough information about the cardholder to authenticate them. No other action is needed by the user.
- Challenge flow:
The ACS requires the cardholder to complete an additional authentication step, which is to enter a onetime-password, log in to their issuing bank, or something similar. The embedded Mobile SDK handles displaying a native device interface for this challenge. The UI for these screens can be customized by passing UI customization fields into the Mobile SDK during initialization.
For more information, see 3DS Authentication Flow.
Performing authentication
Payer authentication is considered a transaction on its own in the gateway, and therefore needs a unique transaction ID.
If you are collecting a payment for an order:
- You can correlate a payment and an authentication transaction by using the same order ID for each transaction (for example, UUID).
- Each transaction is displayed as a separate transaction in the Merchant Administration.
To start the authentication process in the SDK, call the authenticate() function.
Example code for iOS
let request = AuthenticationRequest (navController: navController,
apiVersion: apiVersion,
sessionId: sessionId,
orderId: orderId,
transactionId: authenticationTxnId)
AuthenticationHandler.shared.authenticate(request) { (response) in
// handle response
}
authenticationTxnId is a unique ID for this transaction which distinguishes it from any other transaction within the same order. When you send the actual payment transaction request (such as PAY), the gateway uses this ID to look up the authentication results that are stored when you ask the SDK to authenticate the payer. The gateway passes the authentication results to the acquirer along with the payment transaction request.Example code for Android
AuthenticationHandler.authenticate(activityContext, session, "your-auth- transaction-id", callback)
your-auth-transaction-id is a unique ID for this transaction which distinguishes it from any other transaction within the same order. When you send the actual payment transaction request (such as PAY), the gateway uses this ID to look up the authentication results that are stored when you ask the SDK to authenticate the payer. The gateway passes the authentication results to the acquirer along with the payment transaction request.Interpreting the response
The authenticate function returns an AuthenticationResponse object that contains:
- Important information about the outcome
- Actions performed during the operation.
The most important field to check is response.recommendation. It can contain the following values:
- PROCEED: You can continue with a payment or authorization.
- DO_NOT_PROCEED: Something failed during the authentication operation. Use the
AuthenticationErrorobject to find out more.
From Gateway API version 70 and above, you can get the following errors:
AuthenticationError.recommendation_ResubmitWithAlternativePaymentDetails: You must 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: The Payment Service Provider (PSP), scheme, or issuer requires you to abandon the order.AuthenticationError.recommendation_DoNotProceed: The gateway fails the request, and there is no way for this transaction to succeed.
If the authentication fails, you can also examine response.error for more information about any other errors sent by the gateway.
Example code for iOS
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
}
}
}
Example code for Android
AuthenticationHandler.authenticate(activityContext, session, "your-auth-transaction-id") { response ->
when(response.recommendation) {
AuthenticationRecommendation.PROCEED -> {
// continue to payment/authorization
}
AuthenticationRecommendation.DO_NOT_PROCEED -> {
if (response.error !=null) {
if (response.error is AuthenticationError.RecommendationResubmitWithAlternativePaymentDetails) {
// "Authentication not successful, re-enter card details
}
} else {
// "Authentication not successful"
}
}
}
}