Passing 3D Secure Data


3D Secure is a method to shift fraud liability from the merchant’s sphere to the issuing bank or card brand sphere. That means whenever a 3D Secure protected transaction is provided to the processor and authorized, that transaction cannot become a dispute or a chargeback, as the card brand and the issuing bank previously approved it from happening. All this happens in real-time, in a variety of methods.

EMV 3DS is the upgraded version of the protocol, also known as 3DS2, 3DS V2 or 3DS 2.0.

When running 3D Secure authenticated transactions you should pass the MPI/ACS response to the gateway. Possible outcomes for a 3D Secure transaction are:

  • attempted which is returned whenever a 3DS request has been attempted but not fully validated by the card brand or issuer;
  • failed is returned whenever the card brand or issuer denied the transaction from happening;
  • success is returned whenever the transaction has been successfully protected and liability has been shifted;
  • error means the processor, issuer or card brand systems returned an error with the provided data;
  • unavailable means that 3DS is not available for the provided card.

This should be done either during a auth or sale event. Besides passing all fields for these event types, you will also need to pass the fields described below. All this data is provided by your 3DS MPI, after running the Payment Authentication Response (PaRes).

Parameter Type Length Presence Description Example
threeds_enabled boolean - Required (for 3DS) Flag to enable 3DS capabilities true
threeds_xid string 1-255 Required (for 3DS) Base-64 encoded Transaction ID MDAwMDAwMDAwMDEyMzQ2Njc4OTA=
threeds_eci string 2 Required (for 3DS) Electronic commerce indicator. 05
threeds_cavv string 1-255 Required (for 3DS) Cardholder authentication verification value. jI3JBkkaQ1p8CBAAABy0CHUAAAA=
threeds_status string 1 Required (for 3DS) Result of 3DS request. Y, N, A, U
threeds_version number 1 Optional Version of 3DS protocol used. Default 1. 1, 2
Parameter Type Length Description Example uuid 36 This transaction’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.merchant_id uuid 36 The user’s merchant ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.user_id uuid 36 The user’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.processor_id uuid 36 The processor’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.merchant_transaction_id string 1-255 The merchant assigned identifier my-order-id-0001
transaction.updated_at datetime - Last time this transaction was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.created_at datetime - Time that transaction was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00*.id uuid 36 This event’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28*.success boolean - If the event was a successful event or not true*.event_type string 4-10 The type of event being performed auth, capture, sale, void, refund*.amount number 0.01-9999999 Total event amount 3.56*.processor_code string 2-10 The processor response code 00*.processor_message string 1-255 A human readable message from the processor APPROVAL V12341*.processor_transaction_id string 1-255 A processor assigned identifier 00000000143242*.updated_at datetime - Last time this event was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00*.created_at datetime - Time that event was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
curl --request POST \
  --url \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --form 'amount=1.00' \
  --form 'card_number=4111111111111111' \
  --form 'card_expiry_month=01' \
  --form 'card_expiry_year=2021' \
  --form 'card_cvv=999' \
  --form 'first_name=John' \
  --form 'last_name=Doe' \
  --form 'street_address_1=59 N Santa Cruz Avenue' \
  --form 'street_address_2=Suite M' \
  --form 'city=Los Gatos' \
  --form 'state=CA' \
  --form 'country=US' \
  --form 'ip_address=' \
  --form 'dynamic_descripton=MY-DESCRIPTOR' \
  --form 'mobile_phone=+11231231234' \
  --form '[email protected]' \
  --form 'merchant_transaction_id=my-order-id-0001' \
  --form 'zip=95030' \
  --form 'threeds_enabled=1' \
  --form 'threeds_xid=MDAwMDAwMDAwMDEyMzQ2Njc4OTA=' \
  --form 'threeds_eci=05' \
  --form 'threeds_cavv=jI3JBkkaQ1p8CBAAABy0CHUAAAA=' \
  --form 'threeds_status=Y'

Responds with:

  "transaction": {
    "id": "3410596f-d596-42d4-9811-41d43868e984",
    "merchant_id": "455a1c64-385b-41b2-a56f-34bf6c5c5335",
    "user_id": "6e064bf5-0e18-466b-811b-f967e8d73b9f",
    "processor_id": "30ff7682-6ec7-48f3-8d7a-62319a9c3c59",
    "merchant_transaction_id": "my-order-id-0001",
    "card_number": "411111******1111",
    "card_brand": "visa",
    "card_expiry_month": "01",
    "card_expiry_year": "2021",
    "first_name": "John",
    "last_name": "Doe",
    "street_address_1": "59 N Santa Cruz Avenue",
    "street_address_2": "Suite M",
    "city": "Los Gatos",
    "state": "CA",
    "country": "US",
    "zip": "95030",
    "email": "[email protected]",
    "mobile_phone": "+11231231234",
    "updated_at": "2018-02-16T16:33:40+00:00",
    "created_at": "2018-02-16T16:33:39+00:00",
    "events": [
            "id": "84a8ab86-ee0e-47d4-8686-4e42fa58355e",
            "success": true,
            "threeds_response": "attempted",
            "avs_response": null,
            "event_type": "auth",
            "amount": "1.00",
            "ip_address": "",
            "processor_code": "00",
            "processor_message": "APPROVAL TAS656 ",
            "processor_transaction_id": "000000000252616",
            "processor_threeds_response": "4",
            "processor_avs_response": "0",
            "updated_at": "2018-02-16T16:33:40+00:00",
            "created_at": "2018-02-16T16:33:39+00:00"