General FAQs

This section provides answers to frequently asked questions.

The 3D Secure Service

Q. How does the 3DS authentication affect authorisation?

3DS authentication happens before payment authorisation. If the cardholder passes authentication, the transaction is sent to Thredd for authorisation: either Thredd or your systems authorise, depending on whether the card balance is maintained by Thredd or on your systems. (This is the following EHI modes: Gateway Processing (mode 1), Cooperative Processing (mode 2), Gateway Processing with STIP (mode 4) and Gateway Processing with STIP (mode 5).

If the cardholder does not pass 3DS authentication, the transaction will not reach Thredd for authorisation. The transaction will not be visible in Smart Client or Thredd Portal.

Q. What versions of 3D Secure are available and will Apata work with all of them?

There are two current versions of 3D Secure: EMV 3DS 2.1 and 2.2.

We are awaiting finalised roll-out details of 2.3 from EMVCo EMVCo is a technical body which manages and evolves EMV Specifications and supporting programmes that enable card-based payment products to work together seamlessly and securely worldwide.. See the EMVCo website > Enhancing the 3D Secure Specifications.

The rules you set up on the Apata Portal apply to both EMV 3DS 2.1 and 2.2. Both versions work with all the authentication types available within 3D Secure (OTP SMS or Biometric/In App).

For more information, see Support for 3D Secure Versions.

Q. Where can I find out more background information about 3D Secure?

The EMVCo website provides detailed specifications for anyone implementing a 3D Secure project. This includes information not covered in the Thredd guides, such as authentication message flows between Issuer (BIN sponsor), ACS provider and merchant (PReq Message sent from the 3DS Server to the Directory Server (DS) to request information about the Protocol Version Number(s) supported by available ACSs and the DS and if one exists, any corresponding 3DS Method URL. This message is not part of the 3-D Secure authentication message flow., PRes The Directory Server (DS) response to the PReq message. The 3DS Server can use the PRes message to cache information about the Protocol Version(s) supported by available ACSs and the DS, and if one exists, about the corresponding 3DS Method URL. This message is not part of the 3-D Secure authentication message flow., AReq The initial message in the 3-D Secure authentication flow. The 3DS Server forms the AReq message when requesting authentication of the Cardholder. It can contain Cardholder, payment, and Device information for the transaction. There is only one AReq message per authentication., ARes The Issuer’s ACS response to the AReq message. It can indicate that the Cardholder has been authenticated, or that further Cardholder interaction is required to complete the authentication. There is only one ARes message per transaction.), and specific internal message fields that may be passed or validated (e.g., CAVV For Visa Secure transactions, a CAVV is generated by the issuer's (BIN sponsor) Access Control Server (ACS). The CAVV provides evidence that cardholder authentication occurred or that the merchant attempted authentication. A CAVV is unique for each authentication transaction./ AAV Unique 32-character transaction token for a Mastercard 3D Secure transaction. For Mastercard Identity Check, the AAV is named the UCAF.).

Starting a 3D SecureProject

Q. What are the steps in an 3D Secure project?

For details, see Steps in a 3D Secure Project.

Q. Can we use a dynamic IP address cloud environment for REST-based API calls?

No, Thredd are unable to handle dynamic IP addresses behind the fixed DNS name.

Testing

Q. How do we test 3D Secure authentication?

Testing can start once your requirements are built and released to the UAT environment, and you have successfully set up your network connection and enroled test cards.

Thredd provides a UAT environment, where you can use the Apata Merchant Simulator to test transactions. See Completing UAT Testing.

Q. How do we test 3D Secure in Production?

When you have completed testing in the UAT environment, Thredd will set up your products in the production environment and you can start pilot testing. This works as follows:

You can use the Card Create web service (Ws_CreateCard) to create pilot cards in the production environment. For details, refer to the Thredd Web Services Guide.
If you are using Thredd's Cards API, for similar create card functionality, see the Cards API Website.
Your issuer (BIN sponsor) must enrol your pilot card ranges at the card scheme (payment network).
Thredd activate your products for 3D Secure , and you enrol your cards in 3D Secure by calling the 3D Secureweb service (Ws_AddUpDelCredentials) or the Create 3DS Credentials Cards API. See Using the Card Enrolment API.
You need to set rules in the Apata Portal to challenge transactions, so transactions are authenticated.
Once the Scheme confirms that the pilot cards are live, you can start using your pilot cards: online transactions with 3DS merchants will route through Apata.

Q. Can we use the Thredd Card Transaction System (CTS) to test a 3D Secure transaction?

No, the Thredd CTS system does not currently have a connect to Apata and cannot be used for this purpose. Note that the e-commerce transaction option on the Thredd CTS system does not include any 3D Secure authentication elements.

If you want to test your 3D Secure transactions, you can use the Merchant Simulator in the Apata Portal. See Completing UAT Testing.

3D Secure Card Enrolment

Using Cards API

Q. How can I enrol cards in 3D Secure and manage them using Cards API?

For details, see the Cards API Website.

Using Web Services

Q. Which web services do I use to enrol cards in 3D Secure?

When using the Apata 3D Secure service, you only need to use a single a web service (Ws_AddUpDelCredentials) for enroling cards and for editing and deleting 3D Secure records. See Using the Card Enrolment API.

Q. What is the Web Service WSDL file format and content?

The SOAP web services WSDL is available here:

https://ws-uat.globalprocessing.net:13682/service.asmx?WSDL

Q. Can I auto-enrol all cards in 3D Secure 3D Secure?

Yes, Thredd can auto-enrol your cards.

Auto-enrolment may not be available for all BINs and card products.

There are two options for auto-enrolment, set up per credential type: Initial Load and Continuous. For details, see Completing your 3DS Product Setup Form.

You must ensure that both existing and new cards have the information required for 3DSecure in Smart Client, such as a valid mobile phone number to use for OTP authentication.

You still need to use the 3D Secure Thredd API or Cards API to manage your cardholder records (e.g., to update the linked cardholder mobile phone number or delete a card from 3D Secure authentication).

Q. How can I check if a card is enroled in 3D Secure?

You can use the 3D Secure Thredd API (Ws_AddUpDelCredentials) with the Get option provided in the <Action> field to return details of the card’s Credential IDs. See Using the Card Enrolment API.

If the card is not enroled in 3D Secure (no credentials are found), then the Thredd API returns an action code of 437. (See the Web Services Guide (SOAP) > Action Codes.)

If you are using our Cards API, then you can use the List 3DS Credentials API endpoint. If the card is not enroled in 3D Secure, then the API returns a blank 200 code response.

Q. How can I unenrol a card from 3D Secure?

You can remove any credentials linked to a card using Thredd API or the Cards API with the Delete option specified in the <Action> field. See Using the Card Enrolment API.

Please check with your 3DS Project Manager for unenrolment restrictions if you have continuous auto-enrolment enabled for your cards.

Thredd does not unenrol cards on behalf of Program Managers. If your card status changes to any of the following: Card destroyed, Lost card, Stolen Card, the Program Manager will need to unenrol the respective cards. They can unenrol using: Ws_AddUpDelCredentials (SOAP) or the 3DS Credentials API (REST).

Q. How do I add multiple authentication types to a card?

In your 3DSecure enrolment request (using Ws_AddUpDelCredentials) you can specify the Add action and include an array of <credentials> to enrol a card in multiple types of authentication. See the example code snippet below:

Copy

<hyp:Action>Add</hyp:Action>
<hyp:Credentials>
   <hyp:Credential>
         <hyp:ID>0</hyp:ID>
         <hyp:Type>OTPEMAIL</hyp:Type>
         <hyp:Value>john.carter@test.com</hyp:Value>
   </hyp:Credential>   
          <hyp:Credential>
          <hyp:ID>0</hyp:ID>
          <hyp:Type>OTPSMS</hyp:Type>
          <hyp:Value>+5858585858588</hyp:Value>
   </hyp:Credential>               
 </hyp:Credentials>

Q. How can I list what type of authentication methods are configured for a card?

You can use the 3D Secure Thredd API (Ws_AddUpDelCredentials) and specify the Get Action to request the authentication methods for any enroled card.
If you are using our Cards API, then you can use the List 3DS Credentials API endpoint.

This returns a list of all the type of authentication the card is enroled in. This is displayed in the Credentials fields: ID lists the unique ID of the authentication method and Type list the type of authentication. Value lists the mobile phone number linked to the card.

You can use the ID, Type and Value fields in a request to update the authentication type and mobile number.

Q. What is the Credential ID?

The Credential ID is a unique identifier of the type of authentication. If the same card is enroled for two different types of authentication, then each enrolment will have a unique Credential ID.

In the Ws_AddUpDelCredentials web service and Cards API 3ds-credentials endpoint, this is up to 8 characters. For example: 669

Default and Fallback Authentication Types

Q. How do I choose the default and the fallback authentication types?

When you complete your 3D Secure Product Setup Form, you can specify the default and fallback authentication methods for your card product (e.g., Biometric as default with fall back as OTP SMS). See Completing your 3DS Product Setup Form.

The supported authentication types must then be added to the card using using either the Thredd API or the Cards API; see Using the Card Enrolment API. Alternatively, if enabled for your account, through auto-enrolment.

Q. When is fallback authentication used and how is it triggered?

If a cardholder cannot authenticate using your default method (e.g. their phone or device doesn’t support biometric or they do not have their phone to hand so cannot receive SMS) and you have a fallback authentication option configured, the cardholder can select an alternative option on the challenge screen. Please note this applies to browser-initiated transactions only.

Q. Can cardholders be given the choice of the authentication method?

Yes, you can allow cardholders to select the type of authentication.

During the project implementation stage, you can customise the text that appears on the Apata Choice screen shown to cardholders: you specify this on the 3DS Product Setup Form; see Challenge Screens.

To populate the options that appear on this screen, you need to register your cards for the required authentication types using using either the Thredd API or the Cards API; see Using the Card Enrolment API. Alternatively request auto-enrolment from your 3DS Project Manager.

Knowledge-Based Authentication (KBA)

Q. What happens if the card is not enroled with a sufficient number of KBA questions?

If your organisation is configured to use multiple questions, you should enrol cards with the correct number of questions. Otherwise, Thredd selects one question at random to complete the KBA authentication.

Language Support

Q. Can the OTP messages be displayed in different languages?

Yes, the dynamic OTP SMS message can be configured in a language other than English if you request this; you can only have one SMS language per card product. Please provide the translation for the OTP message. The list of supported languages is regularly updated.

See Appendix 2: OTP Message Templates.

Apata Portal

Q. How can I access the Apata Portal?

For more information on how to access the Apata Portal, see Using the Apata Portal.

Q. How do I define and set up Risk Profiles ?

You can set up your risk profiles in the Apata Portal. See Managing Authentication Rules.

Q. How do I set up rules to pass Mastercard PSD2 Test Cases?

Mastercard provides test cases for Program Managers to verify the 3D secure authentication process under the PSD2 rules. If you have been contacted by your issuer (BIN sponsor) to complete Mastercard PSD2 test cases, please contact your 3DS Project Manager.

Q. How can I manage my PSD2 and SCA requirements and exemptions?

The Authentication section on the Apata Portal allows you to manage any PSD2 and Strong Customer Authentication (SCA) requirements and exemptions relating to cardholder authentication; see Managing Authentication Rules. Please check with your issuer (BIN sponsor) for any Scheme-mandated requirements relating to PSD2 and Strong Customer Authentication (SCA).

There are also a number of SCA settings you can configure with Thredd. For information on the PSD2 and SCA checks run by Thredd, see the PSD2 and SCA Guide.

3D Secure Fields

Q. Does Thredd provide data linked to the merchant's Requestor App URL?

Yes, during an app-based transaction with authentication, if provided by the merchant, then Thredd receives data from Apata in an optional redirectAppUrl field which indicates the merchant’s app URL. For more information, see Initiating a Biometric Session.

Q. Who validates the CAVV or AAV, and how are these details used?

The Accountholder Authentication Value (AAV) Unique 32-character transaction token for a Mastercard 3D Secure transaction. For Mastercard Identity Check, the AAV is named the UCAF. for Mastercard programmes or Cardholder Authentication Verification Value (CAVV) For Visa Secure transactions, a CAVV is generated by the issuer's (BIN sponsor) Access Control Server (ACS). The CAVV provides evidence that cardholder authentication occurred or that the merchant attempted authentication. A CAVV is unique for each authentication transaction. for Visa programmes is a cryptographic value which is included in the authorisation message request from the Merchant1. It indicates that the 3D secure authentication session was successful or attempted. Merchants include this value in the authorisation request which follows after a 3D authentication session. The value is encrypted to ensure that merchant's cannot tamper with the authentication result. You can request that either Thredd or the Card Scheme (Mastercard or Visa) validate this value. Card Scheme 'on behalf' validation is typically required if you want the card Scheme to provide Stand-In processing. For more information, see Completing your 3DS Product Setup Form.

If Thredd was selected to validate and the CAVV For Visa Secure transactions, a CAVV is generated by the issuer's (BIN sponsor) Access Control Server (ACS). The CAVV provides evidence that cardholder authentication occurred or that the merchant attempted authentication. A CAVV is unique for each authentication transaction./AAV Unique 32-character transaction token for a Mastercard 3D Secure transaction. For Mastercard Identity Check, the AAV is named the UCAF. is not valid (or 3D secure failed or was not performed), then Thredd will decline the authorisation request with CAVV error. Thredd provides relevant details relating to 3D secure (e.g., method of authentication used and result) in the GPS_POS_Data field. For more information, see the External Host Interface (EHI) Guide > GPS_POS_Data Field.

Q. Do you provide details of the acsInfoInd Field?

No, this is a Scheme-generated optional field in the message between the ACS and the merchant server; you will not need this information.The acsinfoind is the ACS information indicator which indicates all of the authentication services (e.g., Device Binding, Transaction Risk Analysis, Authentication, Attempts, Trust Listing, Secure Corporate Payments Exemption and so on) supported by the ACS for the issuer's (BIN sponsor) card ranges. Refer to the EMVCo guides for details.

Troubleshooting

Q. Why are some cardholders not receiving the OTP?

Below are possible reasons why cardholders may not receive the OTP:

SMS is successfully delivered to the mobile phone carrier, but has not been received: possible issue with the carrier passing it to the cardholder; this could be due to spam filtering , blocking overseas SMS messages or mobile network reception issues
SMS provider (Thredd uses AWS SNS) does not send SMS to sanctioned countries
Network issue affecting the message transmission on the Thredd side