3-D Secure | OrderCard Documentation

Send the result of a 3-D Secure check from your own provider with a purchase or authorization.

OrderCard does not run 3-D Secure itself. If you authenticate cardholders with your own 3-D Secure provider, send its result with the purchase or authorization. OrderCard passes it to the gateway in that gateway’s own format. The authentication value in the result is what can shift fraud chargeback liability away from you.

Sending the result

Add three_d_secure to a purchase or authorization:

curl -X POST https://api.ordercard.io/v1/gateways/gw_…/purchase \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method_token": "tok_…",
    "amount": 2500,
    "three_d_secure": {
      "version": "2.2.0",
      "status": "Y",
      "eci": "05",
      "cavv": "AAABBJlhYgAAAAAAlWFiAAAAAAA=",
      "ds_transaction_id": "f38e6948-5388-41a6-bca4-b49723c19437"
    }
  }'

Field	What to send
`version`	The protocol version of the authentication, such as `2.2.0`.
`status`	`Y` when the issuer authenticated the cardholder, `A` when authentication was attempted.
`eci`	The electronic commerce indicator, such as `05` for Visa or `02` for Mastercard. A single digit is padded to two.
`cavv`	The authentication value: the CAVV, or the AAV for Mastercard, base64 encoded.
`ds_transaction_id`	The directory server transaction ID. Required for 3-D Secure 2.
`xid`	The transaction ID of a 3-D Secure 1 result. Leave it out for 3-D Secure 2.

Providers often use the EMV 3-D Secure names: messageVersion, transStatus, authenticationValue and dsTransID.

What OrderCard accepts

Purchases and authorizations only. A verification refuses three_d_secure.
Only while the cardholder is at checkout. A charge with initiator set to merchant or recurring refuses it, because the cardholder is not there to authenticate.
Only a successful result. status must be Y or A. When authentication fails, decide whether to charge without three_d_secure or not at all.

A refused request answers 422 with the field in error.errors, and nothing is charged. The authentication value is single use, so authenticate again before a new purchase or authorization.

What OrderCard records

The transaction keeps the result without its authentication value. The API, webhooks and the dashboard all show it:

"three_d_secure": {
  "version": "2.2.0",
  "status": "Y",
  "eci": "05",
  "ds_transaction_id": "f38e6948-5388-41a6-bca4-b49723c19437",
  "forwarded": true
}

forwarded is false when the gateway cannot receive the result. The charge still goes through, without it. The authentication value is never stored, and it is removed from the API and gateway request logs.

What each gateway receives

Gateway	What OrderCard sends
NMI	`cardholder_auth`, `cavv`, `three_ds_version`, `directory_server_id`, and `xid` for 3-D Secure 1.
Authorize.net	`cardholderAuthentication`, with the ECI and the authentication value.
Converge	`ssl_3dsecure_value`, `ssl_eci_ind`, `ssl_3ds_message_version`, `ssl_program_protocol`, `ssl_3ds_trans_status`, `ssl_dir_server_tran_id`, and `ssl_xid` for 3-D Secure 1.
Fortis	`threedsecure`, `secure_auth_data`, `secure_protocol_version` and `secure_directory_server_transaction_id`.
Deluxe	Nothing. Deluxe has no 3-D Secure fields for card payments, so `forwarded` is `false`.
Test gateway	Nothing. The result is recorded with `forwarded` set to `true` and never changes the test outcome.

Each gateway’s page has the details. The card network and your acquirer decide whether a result shifts liability, so check with your gateway that 3-D Secure is enabled on your account.