Forward 3D Secure Parameters to Processors

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

Field	Description	Required	Max Length
`cavv`	Cardholder Authentication Verification Value returned by issuer/ACS	Required if `threeDS` is supplied	40
`xid`	Transaction identifier from ACS (legacy / optional in 2.x)	Optional	40
`dsTransactionId`	Directory Server Transaction ID (EMV 3DS 2.x)	Optional	36
`threeDsVersion`	EMV 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

Processor Raw Response Create a Subscription

⌘I

Getting Started

Authentication & Security

Core Concepts & Data Models

Integration Flows

Plugins

API Reference

Webhooks & Event Handling

Error Codes & Troubleshooting

Testing & Sandbox

Certification & Go-Live Checklist

Appendix / Glossary

FAQ

What is 3D Secure (3DS)?

3DS Version Support

The `threeDS` Object

Field Reference

Example Request

Troubleshooting

Common Issues

Worldpay Sandbox Note (Base64 Padding)

Best Practices

​What is 3D Secure (3DS)?

​3DS Version Support

​The threeDS Object

​Field Reference

​Example Request

​Troubleshooting

​Common Issues

​Worldpay Sandbox Note (Base64 Padding)

​Best Practices

What is 3D Secure (3DS)?

3DS Version Support

The `threeDS` Object

Field Reference

Example Request

Troubleshooting

Common Issues

Worldpay Sandbox Note (Base64 Padding)

Best Practices