Standardized 3DS Fields

Moving forward, especially for 3DS2-specific options, we are adopting the following convention to pass 3DS-specific options into a gateway:

• :version
  • 3DS Version
• :eci
  • E-Commerce Indicator
• :cavv
  • Authentication Value (CAVV for Visa, AAV/UCAF for Mastercard)
• :ds_transaction_id
  • 3DS 2.0 Directory Server Transaction ID
• :acs_transaction_id
  • Access Control Server Transaction ID
• :xid
  • 3DS 1.0 Directory Server Transaction ID
• :enrolled
  • 3DS 1.0 enrollment response from the VERes message from the Directory Server
• :cavv_algorithm
  • Authentication Value algorithm
• :directory_response_status
  • 3D Secure directory server TransStatus response
• :authentication_response_status
  • 3D Secure authentication TransStatus response
• :three_ds_server_trans_id
  • 3D Secure Server Transaction ID

Note that some gateways may need both a ds_transaction_id and xid as distinct values, but some will only require the former for 3DS2-authenticated calls. Not all gateways will require all fields, but anytime one accepts or requires one of these fields, we will use these standard field names on the user-facing API of ActiveMerchant.

The currently noted fields are mostly applicable in the context of passing third-party 3DS authentication results (also often referred to as MPI authentication). We may find additional common fields and can expand the above standardized field list as needed.

Example usage in a gateway adapter #purchase call:

gateway.purchase(
  100,
  credit_card,
  three_d_secure: {
   version: '2.1.0',
   eci: '02',
   cavv: 'jJ81HADVRtXfCBATEp01CJUAAAA=',
   ds_transaction_id: '97267598-FAE6-48F2-8083-C23433990FBC',
   acs_transaction_id: '13c701a3-5a88-4c45-89e9-ef65e50a8bf9',
   xid: '00000000000000000501',
   cavv_algorithm: '1',
   directory_response_status: 'Y',
   authentication_response_status: 'Y',
   three_ds_server_trans_id: '24f701e3-9a85-4d45-89e9-af67e70d8fg8'
  }
)

Adoption Guidelines

We recommend adopting this new options convention when adding new 3DS-related features to an existing gateway adapter (e.g. adding 3DS2 auth data support to a gateway which already supports 3DS1 auth data), or when creating a new gateway adapter that includes 3DS functionality.

If making extensive changes to existing code, it may also make sense to retrofit with these conventions, but in that case ensure that the pre-existing options may continue to be used for backwards compatibility (and add ample tests for both the new options and the legacy options).

See this PR and comment for an example where we have added 3DS2 third-party auth support to the Credorax gateway adapter (while leaving the pre-existing adapter API for 3DS1 auth unaffected).