What 3-D Secure data do I need to include in payments requests?

For developers. This is the 3-D Secure data that you need to send us.

To process a 3-D Secure (3DS) transaction correctly, some extra data is required in the payment request. If this extra data is not sent or is not in the correct format with correct capitalisation, the payment request can be declined by the issuer. This will affect businesses and customers.


Here’s a table that shows which details we need for each version of 3DS.

Data Version
1.0 2.x
Xid
The transaction ID from the 3-D Secure provider
Y N
DSTransId
The Directory Server Transaction ID given to a transaction following a 3-D Secure Cardholder Authentication
N Y
CAVV (Cardholder Authentication Verification Value)
The value that enables an issuer to validate the integrity of a cardholder
Y Y
ECi ((Electronic Commerce Indicator)
The authentication result
Y Y
ThreeDSecureversion
The version of 3-D Secure that was used for to authenticate the cardholder
Y Y

Important: If we don’t receive the ThreeDSecureversion, we assume version 1.0. 

Payments API

Additional fields for 3-D Secure transactions (Visa and Mastercard only)

3DS version 1.0

Field

Description

Xid

The unique Authentication ID for a transaction from the Access Control Server.

Required. 28 character string.

CAVV

The Cardholder Authentication Verification Value from the Access Control Server.

Required. 28 character string.

ECi

The response from the Access Control Server, stating the 3-D Secure method and result:

·         5 = VbyV - Full Authentication

·         6 = VbyV - Attempted Authentication

·         7 = VbyV - No Authentication

·         2 = Mastercard SecureCode - Full Authentication

·         1 = Mastercard SecureCode - Attempted Authentication

·         0 = Mastercard SecureCode - No Authentication

Required.

ThreeDSecureversion

The version of 3DS that was used to authenticate the cardholder.

Optional. If a version is not specified, version 1.0 is assumed.


3DS version 2.x

Field

Description

DSTransId

The Directory Server Transaction ID given to a transaction following a 3-D Secure Cardholder Authentication.

Required. 36 character string.

CAVV

The Cardholder Authentication Verification Value from the Access Control Server.

Required. 28 character string.

ECi

The response from the Access Control Server, stating the 3-D Secure method and result:

·         5 = VbyV - Full Authentication

·         6 = VbyV - Attempted Authentication

·         7 = VbyV - No Authentication

·         2 = Mastercard SecureCode - Full Authentication

·         1 = Mastercard SecureCode - Attempted Authentication

·         0 = Mastercard SecureCode - No Authentication

Required.

ThreeDSecureversion

The version of 3DS that was used to authenticate the cardholder.

Optional. If a version is not specified, version 1.0 is assumed


Example request

Here’s an example request that includes the data that we need for 3DS 2.x if you’re using our Payments API:

{

"ApiKey": "",

"Signature": "",

"Request": {

       "MerchantId": "1145",

       "OrderReference": "AuthOrderRef0051",

       "TestMode": 0,

       "Amount": 123.45,

       "Currency": "EUR",

       "CardHolderName": "Customer Name",

       "CardHolderAddress1": "7 Test Street",

       "CardHolderAddress2": "Address2",

       "CardHolderCity": "Test City",

       "CardHolderPostCode": "CB22 7GG",

       "CardHolderCountry": "GB",

       "CardHolderState": "Cambridgeshire",

       "CardHolderEmail": "myemail@mydomain.com",

       "CardHolderTelephone": "0777777777",

       "CardHolderIPAddress": "80.99.23.45",

       "CardNumber": "4000000000000002",

       "Cvv": "123",

       "ExpiryDateMonth": "03",

       "ExpiryDateYear": "22",

              "Is3Ds": true,

              "ThreeDSecureData": {

                    "DSTransId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645",

           "Cavv": "kNVl4PgT6mTRARANWECAVvtyiq4=",

           "Eci": 06,

                     "ThreeDSecureVersion": "2.1.0"

              },

              "Requires3Ds": false,

       "UsingStoredCredentials": false,

       "Descriptor": "only12char",

       "PaymentType": 0,

       "TransactionClass": "ecom",

       "RecurrenceType": "SUBS"

},

"Version": "1.1"

}

Remote and Remote Auth API

Additional fields for 3DS transactions (Visa and Mastercard only)

3DS version 1.0

Field

Description

acs_xid

The unique Authentication ID for a transaction from the Access Control Server.

Required. 28 character string

acs_eci

The response from the Access Control Server, stating the 3-D Secure method and result:

·         5 = VbyV - Full Authentication

·         6 = VbyV - Attempted Authentication

·         7 = VbyV - No Authentication

·         2 = Mastercard SecureCode - Full Authentication

·         1 = Mastercard SecureCode - Attempted Authentication

·         0 = Mastercard SecureCode - No Authentication

Required.

acs_cavv

The Cardholder Authentication Verification Value from the Access Control Server.

Required 28 character string

acs_3dsversion

The version of 3DS being used for authentication.

Optional. If a version is not specified, version 1.0 is assumed.


3DS version 2.x

Field

Description

acs_dstransid

The universally unique transaction identifier assigned by the Directory Server (DS) to identify a single transaction.

36 character string.

Required when acs_3dsversion = 2.1.0/2.2.0.

acs_eci

The response from the 3-D Secure server.

·         5 = VbyV - Full Authentication

·         6 = VbyV - Attempted Authentication

·         7 = VbyV - No Authentication

·         2 = Mastercard SecureCode - Full Authentication

·         1 = Mastercard SecureCode - Attempted Authentication

·         0 = Mastercard SecureCode - No Authentication

acs_cavv

The Cardholder Authentication Verification Value from 3-D Secure server.

Required. 28 character string

acs_3dsversion

The version of 3DS being used for authentication.

Optional. If a version is not specified, version 1.0 is assumed. Otherwise 2.1.0 or 2.2.0 should be set.


Example request

Here’s an example request that includes the data that we need for 3-D Secure 2.x if you’re using our Remote or Remote Auth APIs:

auth_id:YourMID
auth_pass:Mys3cr3tKey
card_num:8501525000001001
card_cvv:123
card_expiry:1120
cust_name:Mrs T Tester
cust_address:testUserApi
cust_postcode:TE456ST
cust_country:GB
cust_ip:123.45.67.89
cust_email:"myemail@mydomain.com",
cust_tel:01279859869
tran_ref:testApi
tran_amount:11.11
tran_currency:GBP
tran_testmode:0
tran_type:sale
tran_class:ecom
acs_eci:2
acs_cavv:jHVl4PgT6mTRARANWECAVvtyiq4=
acs_3dsversion:2.1.0
acs_dstransid:c5b808e7-1de1-4069-a17b-f70d3b3b1645
return_token:true
submit:submit

Setting exemption flags

At Cashflows we recommend that all payments (except MOTO and Continuous Authority payments) have 3DS checks applied. If you’re planning to use the exemptions feature of 3DS version 2.2, here are some examples to show how to use our different APIs.

Payments API

Important: You must use the same capitalisation as shown here. 

  • SCAExemptionIndicator make sure that SCA is upper case.
  • Recurring make sure that R is upper case (Mastercard and Visa transactions).
  • MerchantInitiated make sure that M and I are upper case (Mastercard only).

For a low value payment exemption, set the exemption indicator as follows:

       "SCAExemptionIndicator": "LowValue" (Mastercard and Visa)

For Merchant Initiated Transactions , set the exemption indicator as follows:

       "SCAExemptionIndicator": "MerchantInitiated" (Mastercard only)

For recurring payments, set the exemption indicator as follows:

       "SCAExemptionIndicator": "Recurring

Important: If SCAExemptionIndicator = MerchantInitiated or Recurring, RecurrenceType is required.

For recurring payments or Merchant Initiated Transactions (MITs), the supported recurrence types are:

  • INST (for Instalment payments).
  • SUBS (for Subscription payments).
  • UNSC (for Unscheduled payments).

Remote and Remote Auth APIs

Important: You must use the capitalisation as shown here.

  • SCA_exemption_indicator make sure that SCA is upper case.
  • Recurring make sure that R is upper case (Mastercard and Visa).
  • MerchantInitiated make sure that M and I are upper case (Mastercard only).

For a low value payment exemption, set the exemption indicator as follows:

       " SCA_exemption_indicator ": "LowValue"   (Visa and Mastercard)

For Merchant Initiated Transactions, set the exemption indicator as follows:

       " SCA_exemption_indicator ": "MerchantInitiated" (Mastercard only)

For recurring payments (Mastercard and Visa), set the exemption indicator as follows:

       " SCA_exemption_indicator ": "Recurring"

 

Important: If SCA_exemption_indicator = MerchantInitiated or Recurring, the recurrence type (i.e tran_recurrence) is required.


The supported recurrence types are:

  • INST (for Instalment payments)
  • SUBS (for Subscription payments)
  • UNSC (for Unscheduled payments)