3-D Secure authentication on merchant side

General information

Customer 3-D Secure authentication can be performed either on the ECommPay payment platform side or on the merchant side. If authentication is performed on the merchant's side, the authentication result must be sent to the payment platform in order to make a payment. Repeated authentication on the payment platform side will not occur.

Sending 3-D Secure authentication result

Information about the result of passing 3-D Secure authentication is passed in the authentication_data object in a request to perform a one-time purchase, including purchase by using a token or saved card data, or to verify the card. Data is passed in the following parameters:

Parameter Type Mandatory Description
cavv string Mandatory if authentication_status=Y or A Card holder authentication verification value (base64 encoded, 20 bytes in a decoded form)
ds_operation_id string Mandatory if threeds_version=3ds_2 The unique operation identifier assigned by the Directory Servers. Supported for 3-D Secure 2
eci string Mandatory if authentication_status=Y or A The electronic commerce indicator, for more information, see the section Electronic Commerce Indicator (ECI) codes
threeds_version string Optional The version of the 3-D Secure protocol:
  • 3ds_1
  • 3ds_2
  • non_3ds
xid string Mandatory Transaction identifier resulting from authentication processing (base64 encoded, 20 bytes in a decoded form)
enrollement_status string Optional The enrollment response from the VERes message from the Directory Server : Y, N, U. Supported for 3-D Secure 1
authentication_status string Mandatory, except if enrollement_status=N or U

Card holder authentication status. Possible values are:

  • Y—the card holder successfully authenticated with their card issuer
  • A—the card holder authentication was attempted
  • U—authentication with the card issuer was unavailable
authentication_flow string Optional Scenario of 3-D Secure authentication. Supported for 3-D Secure 2
  • Frictionless,
  • Challenge

Figure: Example of a payment request with 3-D Secure 1 authentication passing on the merchant's side

{
   "general":{
      "project_id":200,
      "payment_id":"id_15514400636",
      "signature":"PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQ...=="
   },
   "card":{
      "pan":"some_string",
      "year":2025,
      "month":12,
      "card_holder":"JOHN JOHNSON",
      "cvv":"some_string"
   },
   "customer":{
      "id":"123",
      "ip_address":"217.1.1.0"
   },
   "payment":{
      "amount":1000,
      "currency":"EUR"
   },
   "authentication_data":{
      "cavv":"kEMQyiH/ASySYhP1hAErbWFO+mih",
      "ds_operation_id":"f780a79f-a5e1-44d8-bfa3-5f89432fdb79",
      "eci":"01",
      "threeds_version":"3ds_1",
      "xid":"MDAwMDAwNzYxODEwMDAwMDE3MDE=",
      "enrollement_status":"Y",
      "authentication_status":"A"
   }
}

Figure: Example of a payment request with 3-D Secure 2 authentication passing on the merchant's side

{
   "general":{
      "project_id":200,
      "payment_id":"id_15514400636",
      "signature":"PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQ...=="
   },
   "card":{
      "pan":"some_string",
      "year":2025,
      "month":12,
      "card_holder":"JOHN JOHNSON",
      "cvv":"some_string"
   },
   "customer":{
      "id":"123",
      "ip_address":"217.1.1.0"
   },
   "payment":{
      "amount":1000,
      "currency":"EUR"
   },
   "authentication_data":{
      "cavv":"kEMQyiH/ASySYhP1hAErbWFO+mih",
      "ds_operation_id":"f780a79f-a5e1-44d8-bfa3-5f89432fdb79",
      "eci":"06",
      "threeds_version":"3ds_2",
      "xid":"MDAwMDAwNzYxODEwMDAwMDE3MDE=",
      "authentication_status":"A",
      "authentication_flow":"Frictionless"
   }
}

Related topics

The following topics might be useful when implementing payments through Gate: