Implementing a 3DS Integration using the Authentication API

You can initiate authentication by providing the following fields in the Initiate Authentication request:

The gateway returns the following key fields in the Initiate Authentication response:

• authentication.version: If 3DS authentication of the payer is available, this field shows the type 3DS1 or 3DS2. If both are available, 3DS2 is returned.
• authentication.3ds2.methodSupported: If 3DS2 is available and if the issuer's ACS supports a Method call, this field shows SUPPORTED. The Method call can be used by the ACS to gather additional data prior to the authentication request to increase the likelihood of frictionless authentication being available. The method call is triggered in a hidden iframe, so is invisible to the payer. It also does not provide any callback upon completion.
• transaction.authenticationStatus: Check out this field if you want more details about the authentication status.
• response.gatewayRecommendation: This field allows you to determine the next step. Please note that this recommendation is only based on the 3DS transaction filtering rules configured by you or your payment service provider.
  
  

  response.gatewayRecommendation	Next step
  DO_NOT_PROCEED	Do not proceed with 3DS authentication for this card, but you may wish to proceed to payment without the 3DS data. Or, you can offer the payer the option to try another payment method.
  PROCEED	You can proceed to authenticate the payer using the Authenticate Payer operation.

• authentication.redirectHtml: Insert the content of this field into the page being displayed to the payer. To do this, add the text content to a hidden DIV element and specify the script identifier in the HTML DOM. This will construct and post the form automatically. For example,

  div.innerHtml= response.authentication.redirectHtml;
   
  eval(document.getElementById('initiate-authentication-script').text)
  	

  If the gateway recommends you to not proceed, then inserting the content of this field into your webpage will not execute any functionality.

Submit this operation by providing the following fields.  If you only support 3DS1, the gateway ignores the fields specific to 3DS2. 

The gateway returns the following key fields in the Authenticate Payer response:

• transaction.authenticationStatus: Check out this field if you want more details about the authentication status.
• response.gatewayRecommendation: This field allows you to determine whether you should proceed to a financial transaction or not. This recommendation is only based on the 3DS transaction filtering rules configured by you or your payment service provider.
  
  

  response.gatewayRecommendation	Next step
  DO_NOT_PROCEED	Do not proceed with this card as authentication is declined or unavailable, but you may wish to proceed to payment without the 3DS data. Or, you can offer the payer the option to try another payment method.
  PROCEED	You can proceed to complete the authentication process (challenge flow) or proceed to complete the payment (frictionless flow).

• authentication.redirectHtml: Insert the content of this field into the page being displayed to the payer. To do this, add the text content to a DIV element and specify the script identifier in the HTML DOM. This will construct and post the form automatically. For example,

  div.innerHtml= response.authentication.redirectHtml;
   
  eval(document.getElementById('authenticate-payer-script').text)
  	

  If the gateway recommends you to not proceed, then inserting the content of this field into your webpage will not execute any functionality.

Frictionless Flow

This will redirect the payer’s browser straight back to your website. You can proceed to submit a subsequent payment to the gateway. The gateway will obtain the authentication data related to the payment and will ensure that payments will only be processed where all the 3DS transaction filtering rules (configured by you or your payment service provider) have passed.

Challenge Flow

This will redirect the payer’s browser to the ACS where the issuer’s challenge UI will be presented, after which the payer will be redirected back to your web site. The following fields are returned in the callback once the payer's browser has been returned to your website.

• order.id
• transaction.id
• response.gatewayRecommendation
• result

You can determine the authentication outcome using the value returned in the response.gatewayRecommendation field. This recommendation is only based on the 3DS transaction filtering rules configured by you or your payment service provider.

If you want additional response data, you can use the Retrieve Transaction operation.

If you wish to retrieve the authentication results at any stage, use the Retrieve Transaction operation. Note that fields that are only used during the authentication, for example, authentication.redirectHtml, are not persisted in the gateway hence not returned.

If you have used an external 3DS MPI to authenticate the payer, then you must pass information about the authentication in the authentication parameter group of the Authorize or Pay operation.

All fields are optional, as whether or not they were provided to you by the external 3DS MPI depends on the authentication version (3DS1 or 3DS2) and the status of the transaction. However, if you have the data it's recommended that you provide it.

• authentication.3ds.acsEci: The Electronic Commerce Indicator that may be returned to you in the authentication response message.
• authentication.3ds.authenticationToken: The base64 encoded value generated by the card issuer that may be returned to you in the authentication response message.
• authentication.3ds.transactionId: A unique transaction identifier generated by the gateway for the 3DS authentication.
  For 3DS1, this field corresponds to XID, which is an identifier generated by the gateway on behalf of the merchant. An XID submitted in this field must be in base64 format.
  For 3DS2, this field corresponds to the identifier assigned by the scheme directory server.
• authentication.3ds1.paResStatus: Indicates the result of payer authentication with the issuer.
• authentication.3ds1.veResEnrolled: Indicates whether or not payer authentication is available for the card number you provided.
• authentication.3ds2.protocolVersion: The version of the EMV 3-D Secure protocol used to perform 3-D Secure authentication, in the format specified by EMVCo. For example, 2.1.0
• authentication.3ds2.transactionStatus: Indicates the result of payer authentication with the issuer.
• authentication.3ds2.statusReasonCode: A code indicating the reason for the transaction status returned in authentication.3ds2.transactionStatus. You must provide this when authentication.3ds2.transactionStatus returns N, U, or R.

If you want to perform authentication to only verify the identity of the payer without proceeding to the payment, you must indicate the authentication purpose in the Initiate Authentication request. For example, you may want to authenticate the payer when the payer enters their card details for later use during customer registration or account creation on your website. The ability to complete the authentication process in a non-payment environment enhances payer experience and reduces payer drop-off rates.

To perform a non-payment authentication, provide the following fields in the Initiate Authentication request:

• order.currency: Any currency supported on your acquirer link(s).
• authentication.purpose: Indicates the context in which payer authentication is being requested. You can specify one of the following:
  • ADD_CARD: Authentication performed before a payer's card is stored on file either directly by you or using the gateway's tokenization feature. A payment is not being processed.
  • MAINTAIN_CARD: Authentication performed before updating details of a payer's card stored on file either directly by you or using the gateway's tokenization feature. A payment is not being processed.

  If the authentication scheme does not support the purpose you have requested, the gateway returns AUTHENTICATION_NOT_SUPPORTED in the response. Note that by default the gateway sets this field to PAYMENT_TRANSACTION to allow the authentication to be used for a payment transaction.

If you have used a payment session (session Id) to store the authentication details, the POST request submitted by the payer’s browser to your website on completion of the Authenticate Payer request will be parameterised allowing you to determine the authentication outcome. The individual authentication parameters, for example, authentication.3ds2.transactionStatus.data, may be useful in an advanced integration or if you have the need to provide the authentication data in a payment processed via another gateway. To do this, you can submit a Retrieve Transaction request or choose to decrypt the encrypted authentication data (see the following steps):

1. Create a session using the Create Session operation.
2. Add relevant data to the session Id (returned in the Create Session response) using the Update Session request.
3. Use this session Id in the Initiate Authentication and Authenticate Payer requests.
4. The redirect of the payer's browser to your website will contain payer authentication details in the encryptedData field. It is an encrypted JSON object containing the authentication data obtained during the authentication process. It contains the following fields:
   • encryptedData.ciphertext
   • authentication.3ds.acsEci
   • authentication.3ds.authenticationToken
   • authentication.3ds.transactionId
   • authentication.3ds1.veResEnrolled
   • authentication.3ds1.paResStatus
   • authentication.3ds2.transactionStatus
   • authentication.3ds2.dsTransactionId
   • transaction.authenticationStatus
   • authentication.3ds2.statusReasonCode
   • sourceOfFunds.provided.card.number
   • sourceOfFunds.provided.card.expiry.month
   • sourceOfFunds.provided.card.expiry.year
   • sourceOfFunds.token
   • order.id
   • transaction.id
   • encryptedData.nonce
   • encryptedData.tag
5. To decrypt the content returned in the encryptedData.ciphertext field, use the session.aes256Key (returned in the Create Session response) in the GCM mode. The Base64 encoded key is a secret and must be known only by you.

public final class SessionDataDecrypter {
    /**
     * The algorithm used for encryption/decryption
     */
    private static final String SYMMETRIC_ALGORITHM = "AES/GCM/NoPadding";
  
    /**
     * The algorithm to be associated with the secret key material
     */
    private static final String SYMMETRIC_KEY_TYPE = "AES";
  
    /**
     * The secret key associated with the session, as returned in the session.aes256Key in a Create Session response.
     */
    private final byte[] key;
  
    /**
     * Constructs a new object with the given key. The key is Base64 encoded, as returned in the session.aes256Key
     * field in a Create Session response. This key must be kept secret, as it may be used to encrypt, decrypt and
     * authenticate data for that session.
     *
     * @param encodedKey Key to be used for decryption.
     */
    public SessionDataDecrypter(String encodedKey) {
        key = Base64.getDecoder().decode(encodedKey);
    }
  
    /**
     * Performs decryption of the given ciphertext, using the key passed in the constructor and the associated nonce.
     * The tag is used to authenticate the ciphertext.
     *
     * @param ciphertext Encrypted and authenticated session data
     * @param nonce Nonce/Initialization vector associated with the ciphertext
     * @param tag Authentication tag
     * @return The decrypted session data
     * @throws AEADBadTagException if the data cannot be authenticated with the given tag
     * @throws InvalidKeyException if the key cannot be constructed properly. This may indicate that it has not been
     * correctly retrieved from the response field
     * @throws GeneralSecurityException other than {@link AEADBadTagException} and {@link InvalidKeyException}, should
     * not be thrown in a correctly set up environment
     */
    public String decrypt(String ciphertext, String nonce, String tag)
            throws GeneralSecurityException {
        Key keySpec = new SecretKeySpec(key, SYMMETRIC_KEY_TYPE);
  
        // The Java crypto classes expect the ciphertext and tag to be a single input, so they need to be concatenated
        byte[] encryptedBytes = Base64.getDecoder().decode(ciphertext);
        byte[] tagBytes = Base64.getDecoder().decode(tag);
        byte[] input = new byte[encryptedBytes.length + tagBytes.length];
        System.arraycopy(encryptedBytes, 0, input, 0, encryptedBytes.length);
        System.arraycopy(tagBytes, 0, input, encryptedBytes.length, tagBytes.length);
  
        // Configure the cipher with AES, using GCM parameter specifying the nonce/initialization vector
        byte[] iv = Base64.getDecoder().decode(nonce);
        GCMParameterSpec parameterSpec = new GCMParameterSpec(tagBytes.length * Byte.SIZE, iv);
        final Cipher decrypter = Cipher.getInstance(SYMMETRIC_ALGORITHM);
        decrypter.init(Cipher.DECRYPT_MODE, keySpec, parameterSpec);
  
        // Perform the decryption and return the value.
        byte[] decryptedBytes = decrypter.doFinal(input);
        return new String(decryptedBytes, StandardCharsets.UTF_8);
    }
}
	

Aggregator merchants can enable their sub-merchants to use the Authentication API on the gateway. The sub-merchants are not required to have a contractual relationship with the acquirer nor with the gateway. The aggregator merchant can submit the sub-merchant details required for initiating the authentication via the Initiate Authentication operation. For more information, see Aggregator Support.

You can use the Authentication API as a server-side or a client-side API.

• Client-side API: You must first establish the authentication channel where your merchant server must communicate with the gateway server for creating the session on the gateway. Once the session is created, you can use it to authenticate all the subsequent API operations needed for managing the 3DS integration flows directly from the browser using the 3DS JavaScript API or using your own library.
• Server-side API: You must perform all the operations needed for managing the 3DS integration flows directly from your merchant server to the gateway server. You can support all authentication transaction modes via the Authentication API.
  
  • Authentication Only: Perform Initiate Authentication and Authenticate Payer.
  • Authentication and Payment Transaction: Perform Initiate Authentication, Authenticate Payer, and Authorize/Pay.
  • Pre-authenticated Payment Transaction: Perform Authorize/Pay using authentication details from an external provider.

The Authentication API records the details of the payer authentication using 3DS1 or 3DS2 as a separate AUTHENTICATION transaction on the order.

When you retrieve an order using the Retrieve Order operation or receive a Reporting API response, it may contain an additional AUTHENTICATION transaction. Also, when you use Webhook Notifications, you may receive an additional notification for the AUTHENTICATION transaction.

For details about AUTHENTICATION transactions please refer to the list of response parameters for the Authenticate Payer operation.

You can use network tokens for payer authentication from API v55 onwards. The Suncorp Gateway currently supports processing network tokens obtained from the following tokenization service providers: Mastercard Digital Enablement Service (MDES), Visa Token Service (VTS).

If you have obtained a network token by integrating directly to the network tokenization service provider, then you must supply token details using the following fields:

• sourceOfFunds.type=SCHEME_TOKEN: Enables the gateway to identify the source of fund provided in the request as a network token. MDES and VTS are supported from API v51 and v53 respectively.
• sourceOfFunds.provided.card.number: The network token. Supply the value for the MDES "Token PAN" or the VTS "Token".
• sourceOfFunds.provided.card.expiry: (optional) The network token expiry.

If you have been enabled for network tokenization by your payment service provider, any request to the gateway for a gateway token will also attempt to generate a corresponding network token for enabled schemes, where supported by the card issuer. The gateway will also attempt network tokenization for any applicable cards already stored in the gateway token repository. The Initiate Authentication request will use the network token if available else the Funding PAN (FPAN) stored against the gateway token will be used. This model currently only supports MDES tokens.

You can use device payment tokens for payer authentication, from API v55 onwards. Only payment tokens obtained from Google Pay SDK are supported. You can provide an encrypted payment token or the "pan" obtained from a decrypted payment token for payer authentication. The gateway only accepts authentication requests with FPAN, requests with DPANs will be rejected. To supply card details via payment token, provide the following field:

• order.walletProvider=GOOGLE_PAY
• sourceOfFunds.provided.card.devicePayment.paymentToken: Applicable only if payment token is decrypted by the gateway. It's the encrypted payment token obtained from the Google Pay SDK.
• sourceOfFunds.provided.card.number: Applicable only if payment token is decrypted by you. The value corresponding to the Google Pay JSON Key "pan".

The Authenticate Payer request can take a large volume of information about the payer and the transaction. For example, you can provide the following data in the request using the fields in the customer.account parameter group, which helps the issuer's ACS to assess the level of risk associated with the activity. This means in the case of legitimate payments it helps the ACS to confirm that the payer is likely to be the actual cardholder.

• Is the payer using an existing account?
  • customer.account.history.creationDate
• How long has the account existed?
  • customer.account.history.lastUpdated
  • customer.account.history.passwordLastChanged
• How frequently has the payer shopped with you?
  • customer.account.history.addCardAttempts
  • customer.account.history.annualActivity
  • customer.account.history.recentActivity
  • customer.account.history.shippingAddressDate
• Have they ordered these items from you previously?
  • customer.account.history.issuerAuthentication.acsTransactionId
  • customer.account.history.issuerAuthentication.time
  • customer.account.history.issuerAuthentication.type
• Have you observed suspicious activity (e.g. failed login attempts) on the account?
  • customer.account.history.suspiciousActivity
  • customer.account.authentication.method
  • customer.account.authentication.time

You can also provide the following recommended fields for each card scheme in the Authenticate Payer request. Note that this list is not definitive and may be subject to change.

The gateway provides the authentication status in the transaction.authenticationStatus field. This field may return one of the following values depending on the authentication stage:

• AUTHENTICATION_ATTEMPTED: Payer authentication was attempted and a proof of authentication attempt was obtained.
• AUTHENTICATION_AVAILABLE: Payer authentication is available for the payment method provided.
• AUTHENTICATION_FAILED: The payer was not authenticated. You should not proceed with this transaction.
• AUTHENTICATION_NOT_SUPPORTED: The requested authentication method is not supported for this payment method.
• AUTHENTICATION_NOT_IN_EFFECT: There is no authentication information associated with this transaction.
• AUTHENTICATION_PENDING: Payer authentication is pending completion of a challenge process.
• AUTHENTICATION_REJECTED: The issuer rejected the authentication request and requested that you do not attempt authorization of a payment.
• AUTHENTICATION_REQUIRED: Payer authentication is required for this payment, but was not provided.
• AUTHENTICATION_SUCCESSFUL: The payer was successfully authenticated.
• AUTHENTICATION_UNAVAILABLE: The payer was not able to be authenticated due to a technical or other issue.

You can view authentication details for both individual authentications and authentications that proceeded with the payment in the Merchant Administration portal. Search for the order or transaction in the search page and view the authentication details.

If you want to view authentication details for a 3DS1 authentication, for example, to view data for fields such as PARes, PAReq, then use the Authentications search option in the Merchant Administration portal.

Yes, you can bypass 3DS authentication for payers where payments are deemed low risk by the external risk provider. For more information, see Dynamic 3DS.

To test 3DS functionality:

1. Use a test card (from the following table) when submitting the Initiate Authentication request for your TEST merchant profile.
2. Use the expiry code "01/39" to get a successful authorization/payment in an end-to-end testing flow. Please note that the card(s) listed with * will not work for subsequent authorizations or payments.
3. Check that the authentication is available (authentication.version=3DS2 or 3DS1)
4. Submit an Authenticate Payer request and insert content of the authentication.redirectHtml field into the page displayed to the payer to redirect the payer's browser to the 3DS Emulator challenge page.
   The 3DS Emulator redirects the payer's browser back to your website once the authentication is complete.
5. Select a specific 3DS authentication result via drop-down selection in the 3DS Emulator (see values in the following table).
6. Use the transaction ID for this 3DS authentication in authentication.transactionId in a subsequent Authorize or Pay transaction request. It should indicate only where authentication is successful and if the card allows for subsequent authorization or payment.

In the case of a "C" transStatus, the following outcomes are possible via drop-down selection in the 3DS Emulator: