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)