- Integration Guidelines
- Integrating the Merchant Boarding API
- Update Merchant Payment Details
- Enabling 3-D Secure Authentication
Enabling 3-D Secure Authentication
This page describes how to use the Update Merchant Payment Details and Update Acquirer Link requests to enable 3-D Secure authentication for a merchant.
3-Domain Secure™ (3-D Secure or 3DS) authentication is designed to protect online purchases against credit card fraud by allowing the merchant to authenticate the payer before submitting an Authorization or Pay transaction. The Spring by Citi Payment Gateway supports both 3DS versions — 3DS and EMV 3DS.
3DS, also known as 3DS1 in the gateway, is the original version that allows payers to authenticate at their issuer's Access Control Server (ACS) by entering a password previously registered with their card issuer.
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, browser fingerprinting, and/or previous interactions 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.
The Spring by Citi Payment Gateway currently supports 3DS1 authentication using Mastercard SecureCode™, Verified by Visa™, J/Secure™, American Express SafeKey™, Diners Club ProtectBuy™, and 3DS2 authentication using Mastercard SecureCode™, Verified by Visa™, and American Express SafeKey™.
For more information, see 3DS authentication integration documentation.
3DS1 Authentication
To enable 3DS1 authentication for a merchant, you must provide the configuration details for the authentication scheme for which the merchant can perform 3DS1 payer authentication. Use the merchant.acquirerLink.3DS.<authentication_scheme>.* fields in the Update Acquirer Link request to provide these details:
For Mastercard SecureCode:
merchant.acquirerLink.authentication.masterCardSecureCode.3DS1.merchantIDmerchant.acquirerLink.authentication.masterCardSecureCode.3DS1.merchantPassword
For Verified By Visa:
merchant.acquirerLink.authentication.verifiedByVisa.3DS1.cardAcceptorIdmerchant.acquirerLink.authentication.verifiedByVisa.3DS1.cardAcceptorTerminalIdmerchant.acquirerLink.authentication.verifiedByVisa.3DS1.merchantPassword
For Amex SafeKey:
merchant.acquirerLink.authentication.amexSafeKey.merchantId
For J/Secure:
merchant.acquirerLink.authentication.jSecure.3DS1.merchantIdmerchant.acquirerLink.authentication.jSecure.3DS1.merchantPassword
For Diners Club ProtectBuy:
merchant.acquirerLink.authentication.dinersProtectBuy.3DS1.merchantId
3DS1 Configuration API Reference[REST][NVP]
3DS2 Authentication
To enable 3DS2 authentication for a merchant, provide the authentication scheme(s) for which the merchant can perform 3DS2 payer authentication, in the merchant.privilege[n] field in the Update Merchant Payment Details request. The gateway uses the requestor credentials (Requestor ID and Requestor Name) for a scheme, which are identifiers for the merchant on the 3DS2 Directory Server, to processs 3DS2 authentication for that scheme. Depending on the authentication scheme, you may be required to provide these, if they are not generated by the gateway.
SECURECODE_2: Allows the merchant to perform 3DS2 Mastercard SecureCode authentication. The gateway generates the requestor credentials for this scheme.VERIFIED_BY_VISA_2: Allows the merchant to perform 3DS2 Verified By Visa authentication. From API v55 onwards, the gateway generates the requestor credentials for this scheme.For merchants who have previously configured Verified By Visa using API version < 55, and have Requestor ID and Requestor Name details configured, the gateway will continue to use the configured values in processing 3DS2 Verified By Visa authentication.AMEX_SAFEKEY_2: Allows the merchant to perform 3DS2 American Express SafeKey authentication.
For the gateway to process requests for American Express SafeKey authentication, in addition to enabling the privilege, you must provide the Requestor ID and Requestor Name details. These are provided by the merchant's acquirer when they registered to use American Express SafeKey.
merchant.authentication.3ds2.amexSafeKey.requestorIdmerchant.authentication.3ds2.amexSafeKey.requestorName
-
Provide the merchants with the following optional fields that will allow them to provide the merchant ID issued by the acquirer who has registered the merchant for payer authentication.
merchant.acquirerLink.authentication.masterCardSecureCode.3DS2.merchantIDmerchant.acquirerLink.authentication.verifiedByVisa.3DS2.merchantID
3DS2 Configuration API Reference[REST][NVP]
Enabling Acquirer BINs
For merchants that are enabled for 3DS1 or 3DS2 or both, you can configure an acquirer BIN for each supported authentication scheme on the acquirer link. This allows acquirers that act as processors to process the transaction with the correct 3DS configuration (3DS1 or 3DS2) for that acquirer.
You can use the following fields in the Update Acquirer Link request to provide an acquirer BIN for each supported authentication scheme:
- merchant.acquirerLink.authentication.masterCardSecureCode.acquirerBin
- merchant.acquirerLink.authentication.amexSafeKey.acquirerBin
- merchant.acquirerLink.authentication.dinersProtectBuy.acquirerBin
- merchant.acquirerLink.authentication.jSecure.acquirerBin
- merchant.acquirerLink.authentication.verifiedByVisa.acquirerBin