Skip to main content

​
What is 3D Secure (3DS)?

3D Secure (also called “3DS”) is an extra security layer for online card payments. When required, customers authenticate directly with their bank. Why it matters:
  • Reduces fraud
  • Helps with liability shift (processor/network dependent)
  • Required in some regions (e.g., PSD2)
  • May improve approval rates

​
3DS Version Support

Revolv3 supports EMV 3DS 2.x pass-through only. 3DS 1.x pass-through is not supported.

​
The threeDS Object

Include the threeDS object in your payment request: 
{
  "threeDS": {
    "cavv": "<cavv-value>",
    "xid": "<xid-value>",
    "dsTransactionId": "<ds-transaction-id>",
    "threeDsVersion": "2.1.0"
  }
}

​
Field Reference

FieldDescriptionRequiredMax Length
cavvCardholder Authentication Verification Value returned by issuer/ACSRequired if threeDS is supplied40
xidTransaction identifier from ACS (legacy / optional in 2.x)Optional40
dsTransactionIdDirectory Server Transaction ID (EMV 3DS 2.x)Optional36
threeDsVersionEMV 3DS protocol version (2.1.0, 2.2.0, 2.3.0)Required for 3DS-
Note:
dsTransactionId is the Directory Server Transaction ID (transaction-level identifier), not a Directory Server ID.

​
Example Request

{
  "paymentMethod": {
    "creditCard": {
      "paymentAccountNumber": "4111111111111111",
      "expirationDate": "0330",
      "securityCode": "737"
    }
  },
  "threeDS": {
    "cavv": "AAABBIIFmAAAAAAAAAAAAAAAAAA",
    "dsTransactionId": "550e8400-e29b-41d4-a716-446655440000",
    "threeDsVersion": "2.1.0"
  },
  "invoice": {
    "amount": {
      "value": 1.03,
      "currency": "USD"
    }
  }
}

​
Troubleshooting

​
Common Issues

  • Missing threeDsVersion
  • Unsupported threeDsVersion
  • Invalid base64 format in cavv

​
Worldpay Sandbox Note (Base64 Padding)

Some Worldpay sandbox scenarios may reject cavv values that include trailing base64 padding (=). If you experience unexplained validation failures: Example: 
AAABBIIFmAAAAAAAAAAAAAAAAAA=   may fail
AAABBIIFmAAAAAAAAAAAAAAAAAA    may succeed
Only remove trailing = padding if required. Do not modify any other characters.

​
Best Practices

  • Send values exactly as received from your 3DS provider
  • Only include fields your provider returned
  • Ensure threeDsVersion matches the version used
  • Test thoroughly in sandbox before production rollout