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 on supported processors and flows (processor/network dependent)
Required in some regions (e.g., PSD2)
May improve approval rates

Revolv3 supports merchant-supplied 3DS data on Sale and Authorize when your payment routes to a supported processor.

Important: behavior differs by processor. Worldpay accepts full 3DS pass-through from your MPI (Merchant Plug-in). TSYS accepts data-only 3DS pass-through only — risk/data share with the issuer, no cardholder challenge, no full authentication, and no liability shift. Configure your MPI (for example PAAY) for data-only before sending threeDS to a TSYS merchant.

3DS Version Support

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

Processor Support

Processor	Supported	Flow
Worldpay	Yes	Full 3DS pass-through from your MPI
TSYS	Yes	Data-only pass-through only
Nuvei	Yes	External MPI pass-through
Other processors	No	`threeDS` may be ignored

If the request routes to an unsupported processor, threeDS is not forwarded.

TSYS: Data-Only 3DS Only

For TSYS authorizations, Revolv3 supports data-only 3DS pass-through. This is not full 3DS:

No cardholder challenge step through Revolv3.
No full authentication or liability shift (Visa ECI 07, not 05).
Revolv3 does not accept eci on the Payment API for TSYS — the platform maps the data-only path internally.

Configure your MPI for data-only before enabling TSYS pass-through:

Use challenge indicator 06 (no challenge / data share) where your provider supports it.
Expect ECI 07 on Visa from the MPI — do not send full-auth results (ECI 05, authentication status Y) unless you have confirmed full TSYS 3DS support with Revolv3.
Your MPI returns cavv, dsTransactionId, and threeDsVersion from the data-only exchange.
If your MPI returns Base64 cavv, convert it to 40-character hex before calling Revolv3. Revolv3 does not convert for you.

Full 3DS on TSYS (ECI 05/06, liability shift) is not available in production today.

The `threeDS` Object

Include the threeDS object in your payment request:

{
  "threeDS": {
    "cavv": "<cavv-value>",
    "dsTransactionId": "<ds-transaction-id>",
    "threeDsVersion": "2.1.0"
  }
}

Do not send eci on Revolv3 Payment API requests. It is not supported on the threeDS object and is ignored if sent.

Field Reference

Field	Description	Required	Max length	Worldpay	TSYS
`cavv`	Authentication cryptogram from your MPI	Required if `threeDS` is sent	40	Base64	40-char hex (Visa / Amex / Discover)
`dsTransactionId`	Directory Server Transaction ID (EMV 3DS 2.x)	Recommended	36	UUID from MPI	UUID from MPI
`threeDsVersion`	Protocol version (`2.1.0`, `2.2.0`, `2.3.0`)	Required	—	Same	Same
`xid`	Legacy 3DS 1.x transaction id	Optional	40	Rare for 2.x	Usually omit for 2.x. Do not put `dsTransactionId` here
`eci`	Electronic Commerce Indicator	—	—	Not on Revolv3 DTO	Not supported — do not send

Note:
dsTransactionId is the Directory Server Transaction ID (transaction-level identifier), not a Directory Server ID.

Example Requests

Worldpay (Base64 `cavv`)

{
  "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"
    }
  }
}

Nuvei (Base64 `cavv`)

Nuvei expects the same Base64 cavv shape as Worldpay. Send values in the encoding your MPI returns for that authentication.

TSYS (Data-Only, Hex `cavv`)

{
  "paymentMethod": {
    "creditCard": {
      "paymentAccountNumber": "4111111111111111",
      "expirationDate": "0330",
      "securityCode": "737"
    }
  },
  "threeDS": {
    "cavv": "0099010349105700000007D08402307500000000",
    "dsTransactionId": "3a0d7238-79ff-4a2b-9d39-550c3527da28",
    "threeDsVersion": "2.2.0"
  },
  "invoice": {
    "amount": {
      "value": 1.03,
      "currency": "USD"
    }
  }
}

Use real values from your MPI in production. If PAAY (or another provider) returns Base64 cavv, convert to 40-character hex before calling Revolv3. Do not include eci or xid unless you have a true legacy XID.

Troubleshooting

Symptom	Likely cause	What to do
TSYS `19` / RE ENTER	Base64 `cavv` or UUID in `xid`	Use 40-char hex `cavv`; omit `xid` for 2.x
TSYS `82` / INCORRECT CVV with good CVV	Full-auth MPI data (ECI `05`, status `Y`) sent to data-only TSYS path	Reconfigure MPI for data-only (indicator `06`, ECI `07`). Control test: same card without `threeDS`
Decline only when `threeDS` present	Wrong encoding or wrong flow type	See rows above
Invalid Base64 `cavv`	Malformed Base64	Worldpay / Nuvei only — fix Base64 or see sandbox padding note below
Missing `threeDsVersion`	Required field omitted	Include `2.1.0`, `2.2.0`, or `2.3.0`
Unsupported `threeDsVersion`	Version outside supported range	Use `2.1.0`–`2.3.0`

Worldpay Sandbox Note (Base64 Padding)

Some Worldpay sandbox scenarios may reject cavv values that include trailing base64 padding (=). Example:

AAABBIIFmAAAAAAAAAAAAAAAAAA=   may fail
AAABBIIFmAAAAAAAAAAAAAAAAAA    may succeed

Only remove trailing = padding if required. Do not modify any other characters. This applies to Worldpay only, not TSYS or Nuvei.

Best Practices

Match MPI configuration to processor: Worldpay can use full 3DS; TSYS requires data-only MPI setup.
Encoding: Base64 cavv for Worldpay and Nuvei; hex cavv for TSYS Visa/Amex/Discover.
EMV 3DS 2.x: put the directory-server UUID in dsTransactionId only — leave xid empty unless you have a true legacy XID.
Do not send eci on Revolv3 Payment API requests for TSYS.
Only include fields your MPI returned (plus any required encoding conversion for TSYS).
Ensure threeDsVersion matches the authentication that produced cavv.
Test on the same processor family you use in production.
If TSYS sales fail without threeDS but fail with full-auth MPI data, switch MPI to data-only (ECI 07).

Common Questions

Can I use the same `threeDS` object for Worldpay and TSYS?

No. Worldpay uses Base64 cavv and supports full MPI pass-through. TSYS requires hex cavv and data-only MPI results only.

Should I send `eci: "05"` for TSYS?

No. Revolv3 does not accept eci for TSYS data-only pass-through. Sending full-auth ECI from your MPI while Revolv3 uses the data-only TSYS path can cause declines (for example 82 / INCORRECT CVV).

Will I get liability shift on TSYS?

Not with data-only pass-through. Liability shift requires full 3DS support, which is not available in production on TSYS today.

Can I reuse a Worldpay `threeDS` payload on Nuvei?

Usually yes for cavv encoding (both expect Base64), but confirm threeDsVersion and dsTransactionId match what your MPI returned for that authentication.

Where does the Directory Server UUID go?

In dsTransactionId. Do not put it in xid.

Next Steps

Make a Payment — See how to structure payment requests
Sale with Payment Method Details — API reference for sale requests with threeDS
Authorize with Payment Method Details — API reference for authorization requests with threeDS
Error Responses — Learn how to handle API and processor errors

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

Processor Support

TSYS: Data-Only 3DS Only

The `threeDS` Object

Field Reference

Example Requests

Worldpay (Base64 `cavv`)

Nuvei (Base64 `cavv`)

TSYS (Data-Only, Hex `cavv`)

Troubleshooting

Worldpay Sandbox Note (Base64 Padding)

Best Practices

Common Questions

Can I use the same `threeDS` object for Worldpay and TSYS?

Should I send `eci: "05"` for TSYS?

Will I get liability shift on TSYS?

Can I reuse a Worldpay `threeDS` payload on Nuvei?

Where does the Directory Server UUID go?

Next Steps

​What is 3D Secure (3DS)?

​3DS Version Support

​Processor Support

​TSYS: Data-Only 3DS Only

​The threeDS Object

​Field Reference

​Example Requests

​Worldpay (Base64 cavv)

​Nuvei (Base64 cavv)

​TSYS (Data-Only, Hex cavv)

​Troubleshooting

​Worldpay Sandbox Note (Base64 Padding)

​Best Practices

​Common Questions

​Can I use the same threeDS object for Worldpay and TSYS?

​Should I send eci: "05" for TSYS?

​Will I get liability shift on TSYS?

​Can I reuse a Worldpay threeDS payload on Nuvei?

​Where does the Directory Server UUID go?

​Next Steps

What is 3D Secure (3DS)?

3DS Version Support

Processor Support

TSYS: Data-Only 3DS Only

The `threeDS` Object

Field Reference

Example Requests

Worldpay (Base64 `cavv`)

Nuvei (Base64 `cavv`)

TSYS (Data-Only, Hex `cavv`)

Troubleshooting

Worldpay Sandbox Note (Base64 Padding)

Best Practices

Common Questions

Can I use the same `threeDS` object for Worldpay and TSYS?

Should I send `eci: "05"` for TSYS?

Will I get liability shift on TSYS?

Can I reuse a Worldpay `threeDS` payload on Nuvei?

Where does the Directory Server UUID go?

Next Steps