External 3DS Integration

If you use your own 3DS provider (or a third-party 3DS service) to authenticate cardholders, you can pass the authentication results directly to NetValve when submitting a payment. NetValve will forward the 3DS values to the processor — no additional 3DS configuration is required on the NetValve side.

tip

This guide is for merchants who handle 3DS authentication outside of NetValve. If you want NetValve to manage 3DS for you, see the NetValve 3DS integration guide.

How it works

1. Your system authenticates the cardholder using your own 3DS provider
2. You receive the authentication results (ECI, CAVV, etc.) from your provider
3. You include these values in the 3DS object when calling the NetValve Sale or Auth API
4. NetValve passes the 3DS data to the processor along with the payment

The 3DS object

Add a 3DS object to your Sale or Auth request payload with the following fields:

Field	Type	Required	Description
dsTransactionId	String	Yes	The Directory Server Transaction ID from your 3DS authentication
eci	String	Yes	Electronic Commerce Indicator value (e.g., "05" for Visa, "02" for Mastercard)
cavv	String	Yes	Cardholder Authentication Verification Value — the cryptographic proof of authentication
xid	String	No	Transaction identifier used by some 3DS providers. Include it if your provider returns one

note

The version field is not required when using an external 3DS provider. NetValve only needs the authentication values listed above.

Sale with external 3DS

POST /sale

{
  "amount": 1.00,
  "clientOrderId": "order-12345",
  "currency": "USD",
  "siteId": "your-site-id",
  "cardExpireMonth": "12",
  "cardExpireYear": "2030",
  "cardHolderName": "John Doe",
  "cardSecurityCode": "123",
  "cardNumber": "4012000098765439",
  "3DS": {
    "dsTransactionId": "81d23cfd-aa55-4fc4-ab12-138b74dd6b2b",
    "xid": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",
    "eci": "05",
    "cavv": "AJkBBkhgQQAAAE4gSEJydQAAAAA="
  }
}

Auth with external 3DS

The same 3DS object works with the Auth API:

POST /auth

{
  "amount": 1.00,
  "clientOrderId": "order-12345",
  "currency": "USD",
  "siteId": "your-site-id",
  "cardExpireMonth": "12",
  "cardExpireYear": "2030",
  "cardHolderName": "John Doe",
  "cardSecurityCode": "123",
  "cardNumber": "4012000098765439",
  "3DS": {
    "dsTransactionId": "81d23cfd-aa55-4fc4-ab12-138b74dd6b2b",
    "xid": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",
    "eci": "05",
    "cavv": "AJkBBkhgQQAAAE4gSEJydQAAAAA="
  }
}

CIT with external 3DS

For Customer Initiated Transactions (CIT), combine the 3DS object with the additionalData fields:

POST /sale

{
  "amount": 1.00,
  "clientOrderId": "order-12345",
  "currency": "USD",
  "siteId": "your-site-id",
  "cardExpireMonth": "12",
  "cardExpireYear": "2030",
  "cardHolderName": "John Doe",
  "cardSecurityCode": "123",
  "cardNumber": "4012000098765439",
  "additionalData": {
    "requestTransactionType": "ECOMMERCE",
    "recurringScheduleType": "CIT_COF",
    "recurrenceMode": "Initial"
  },
  "3DS": {
    "dsTransactionId": "81d23cfd-aa55-4fc4-ab12-138b74dd6b2b",
    "xid": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",
    "eci": "05",
    "cavv": "AJkBBkhgQQAAAE4gSEJydQAAAAA="
  }
}

note

MIT (Merchant Initiated Transactions) do not require 3DS, since the cardholder is not present. 3DS is only applicable to customer-initiated flows.

Supported payment flows

External 3DS works with the following NetValve API operations:

Operation	Supported
Sale	Yes
Auth	Yes
CIT (Customer Initiated)	Yes
MIT (Merchant Initiated)	Not applicable — no cardholder present. Reference the initial CIT transactionId

Frequently asked questions

Do I need to configure anything in NetValve to use external 3DS? No. Simply include the 3DS object in your payment request. No additional setup is needed.

Does NetValve restrict external 3DS by MCC (Merchant Category Code)? No. There are no MCC restrictions for 3DS with NetValve.

Which 3DS version should I use? NetValve accepts authentication values from any 3DS 2.x version. You do not need to send the version number — just the authentication results.

Is 3DS mandatory? 3DS is mandatory for transactions in the EU/EEA region under PSD2 regulations. For other regions, the merchant evaluates risk and decides whether to apply 3DS. See What is 3D Secure? for more details.