Intermediate communication formats

The following topics cover information about the formats of intermediate communication which may be used depending on the authentication model when processing payments by using Gate.

Format of callback with iframe data

When you use the extended authentication workflow through Gate, the payment platform sends a callback with iframe data. The callbacks use standard formats described in more details in Callbacks.

The payment platform sends no callback with iframe data, if before receiving customer media data the issuer chooses either of the following options:

  • In challenge flow, the customer is redirected to the authentication page for validation. In this case, your web service is required to accept and process the callback with the redirection data. For more information, see Callback format for the extended authentication workflow below.
  • In frictionless flow, the issuer decides to authenticate the customer. In this case, your web service is required to accept and process the callback with the payment result.

The following example shows sample data to create an iframe. When generating iframe code, you need to use the value of the url parameter from the iframe data as the value of the action attribute in the form. Also, the names and values of the parameters contained in the params object you must to include respectively as name and value attributes inside the corresponding input tags of the iframe code, as shown in the following example.

Figure: Sample iframe data

{ 
  "threeds2":{ 
    "iframe":{ 
     "url":"https://example.com",
      "params":{
       "3DSMethodData":"eyAidGhyZWVNrkthelJSUFQwaWZYMCUzQ",
        "threeDSMethodData":"eyAidGhjNjMGQ4YWU4LTA2u0wyWmtObGRdwR"
      }
    }
  }
}

Figure: Sample iframe code

<iframe id="tdsMmethodTgtFrame" name="tdsMmethodTgtFrame" style="width: 1px; height: 1px; 
display: none;" src="javascript:false;" xmlns="http://example.com/xhtml"> <!--.--> </iframe>
<form id="tdsMmethodForm" name="tdsMmethodForm" action="https://example.com" method="post" 
target="tdsMmethodTgtFrame" xmlns="http://example.com/xhtml">
    <input type="hidden" name="3DSMethodData" value="eyAidGhyZWVNrkthelJSUFQwaWZYMCUzQ"/>
   <input type="hidden" name="threeDSMethodData" value="eyAidGhjNjMGQ4YWU4LTA2u0wyWmtObGRdwR"/>
</form>
<script type="text/javascript" xmlns="http://example.com/xhtml">
    document.getElementById("tdsMmethodForm").submit();
</script>

Format of callback with redirection data

Callback format for the basic workflow

In the basic authentication workflow, when you process payments by using Gate, the payment platform sends a callback with customer redirection data as described in more details in Callbacks.

In the following example, the callback indicates that the 424242******4243 payment card of customer with the ID customer_12 supports the 3‑D Secure 2 authentication and you need to redirect the customer to the preload page hosted on the payment platform. The callback contains an acs object that includes the PAReq message, the address of the payment platform preload page, and merchant data stored in the payment system.

Figure: Example of a callback with the redirection data

{  
  "project_id":42,
  "customer":{  
    "id":"customer_12"
  },
  "payment":{  
    "id":"456789",
    "type":"purchase",
    "status":"awaiting 3ds result",
    "date":"2019-07-19T06:21:40+0000",
    "method":"card",
    "sum":{  
      "amount":10000,
      "currency":"EUR"
    },
    "description":""
  },
  "account":{  
    "number":"424242******4243",
    "type":"visa",
    "card_holder":"JOHN JONSON",
    "expiry_month":"08",
    "expiry_year":"2025"
  },
  "operation":{  
    "id":13002103,
    "type":"auth",
    "status":"awaiting 3ds result",
    "date":"2019-07-19T06:21:40+0000",
    "created_date":"2019-07-19T06:21:37+0000",
    "request_id":"e2fd233d27c064fbe01af291039e6478341a0489-3...9",
    "sum_initial":{  
      "amount":10000,
      "currency":"EUR"
    },
    "sum_converted":{  
      "amount":10000,
      "currency":"EUR"
    },
    "provider":{  
      "id":414,
      "payment_id":"",
      "result_code":"0",
      "result_message":"",
      "endpoint_id":414
    },
    "code":"9999",
    "message":"Awaiting processing",
    "description":"",
    "eci":"07"
  },
  "acs":{  
    "pa_req":"inLgICAiYWNzVHIDAtMDAwMDAwMDAwNHv5hu", // PAReq message
    "acs_url":"https://example.com/ACS", // The payment platform preloader
    "md":"eyJwdXJjaGFzZV9vcGVyYXRpb25faWRfaWJ9" // Merchant data in the payment system
  },
  "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}

Callback format for the extended authentication workflow

In the extended authentication workflow, when you process payments by using Gate, the payment platform may send a callback with the data to redirect the customer to the authentication page at issuer's Access Control Server. For more information about callback format, see Callbacks. If the issuer decides to use frictionless flow, the payment platform sends no callback with the customer redirection data. In this case, your web service is required to accept and process the callback with the payment result.

The following example shows sample data for redirecting the customer to the authentication page. When generating the HTML page code, you need to use the value of the url parameter from the redirection data as the value for the action attribute in the form tag. Also, the names and values of the parameters contained in the params object you must to include respectively as name and value attributes inside the corresponding input tags of the HTML code, as shown in the following example.

Figure: Sample data for customer redirection

{ 
  "threeds2":{ 
    "redirect":{ 
      "url":"https://example.com/ACS",
      "params":{
        "creq":"ewogICAiYWNzVHJhbnNJCIDAtMDAwMDAwMDAwN2Q5Ip9",
        "threeDSSessionData":"240000549",
        "TermUrl":"http://example.com/termurl"
      }
    }
  }
}

Figure: Sample HTML page code

<!DOCTYPE html SYSTEM "about:legacy-compat">
<html class="no-js" lang="en" xmlns="http://example.com/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta charset="utf-8" />
    <title>3D Secure Processing</title>
    <link href="https://example.com/mpi.css" rel="stylesheet" type="text/css" />
  </head>
  <body>
    <div id="main">
      <div id="content">
        <div id="order">
          <h2>3D Secure Processing</h2>
          <img src="https://example.com/preloader.gif" alt="Please wait.." /> <img src="https://
example.com/verifiedbyvisa.png" alt="Verified by VISA" />
          <div id="formdiv">
            <script type="text/javascript">
              function hideAndSubmitTimed(formid) { timer=setTimeout("hideAndSubmit('"+formid+"');",
100);} function hideAndSubmit(formid) { var formx=document.getElementById(formid); tif (formx!=null)
{ formx.style.visibility="hidden"; formx.submit(); } }
            </script>
            <div>
              <form id="webform0" name="red2ACSv2" method="POST" action="https://example.com/ACS" accept_charset="UTF-8"> 
<input type="hidden" name="_charset_" value="UTF-8" /> 
<input type="hidden" name="creq" value="ewogICAiYWNzVHJhbnNJCIDAtMDAwMDAwMDAwN2Q5Ip9" /> 
<input type="hidden" name="threeDSSessionData" value="240000476" /> 
<input type="hidden" name="TermUrl" value="http://example.com/termurl" /> 
<input type="submit" name="submitBtn" value="Please click here to continue" /> 
              </form>
            </div>
          </div>
          <script type="text/javascript">
           thideAndSubmitTimed('webform0');
          </script>
          <noscript>
            <div align="center"> <b>Javascript is turned off or not supported!</b> <br/> </div>
          </noscript>
        </div>
      </div>
    </div>
  </body>
</html>

Format of the acknowledgement of receiving customer device data

If the initial payment request contains the 3ds_notification_url parameter, in the extended authentication workflow, issuer's Access Control Server sends a callback with an acknowledgement of receiving the customer device data. Otherwise, the ACS sends to the payment platform the callback. The callback is transmitted in issuer's format.

Figure: Sample operation ID on the 3DS Server side

threeDSServerTransID=3abd37b3-afa6-53cf-8000-000000006455

Format of authentication initiation request

When you use the extended authentication workflow through Gate and specify the 3ds_notification_url parameter in the payment initiation request, you initiate the authentication by sending a POST request to the /v2/payment/card/3ds_check_iframe endpoint. If you do not specify the parameter, the payment platform initiates the authentication. The request must contain the following objects and parameters:

  • general—general identification information:
    • project_id—the project ID obtained from ECommPay
    • payment_id—payment ID which must be unique within the project
    • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification
  • threeds_completion_indicator—indicates whether the acknowledgement about data reception was received in ten seconds after the iframe object was closed. The true value must be specified if the acknowledgement was received in time, and the false value if not.

In other words, a valid request for authentication must contain project ID, payment ID, and signature.

Figure: Sample authentication request data

{ 
  "general":{ 
    "project_id":42,
    "payment_id":"456789",
    "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
  "threeds_completion_indicator":true
}

Format of authentication result notification

Format of result notification in the basic workflow

In the basic authentication workflow in Gate, web service receives authentication result in the payment platform format. Similarly to 3‑D Secure 1, the result is passed in the pares parameter, although 3‑D Secure 2 uses a different result value format.

Figure: Example of notification with successful authentication result

pares=eyJ4aWQiOiJNREF3TURBd01EQXdNREF5TkRBd01ERXhNVFU9IiwibWRTdGF0dXMiOjEsIm1kRXJyb3JNc2ciOiJBdXRoZW5
            0aWNhdGVkIiwiZW5yb2xsbWVuU3RhdHVzIjpudWxsLCJhdXRoZW50aWNhdGlvblN0YXR1cyI6IlkiLCJjYXZ2I
            joiUVVOVFJVMVZLMkI5UFV4MWFXRXBhMlJpTjJVPSIsImVjaSI6IjA1In0=

Figure: Example of notification with failed authentication result

pares=eyJ4aWQiOiJNREF3TURBd01EQXdNREF5TkRBd01ERXhNVFk9IiwibWRTdGF0dXMiOjAsIm1kRXJyb3JNc2ciOiJOb3QgYXV
            0aGVudGljYXRlZCIsImVucm9sbG1lblN0YXR1cyI6bnVsbCwiYXV0aGVudGljYXRpb25TdGF0dXMiOiJOIiwiY
            2F2diI6IiIsImVjaSI6IiJ9

Format of result notification in the extended workflow

In the extended authentication workflow in Gate, web service receives authentication result in the issuer format. The result is passed as the value of the cres parameter inside the notification message.

Figure: Example of notification with successful authentication result

cres=ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMiLAogICJtZXNzYWdlVHl
             wZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlRFNTZXJ2ZXJUcmFu
             c0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1N0YXR1cyIgO
             iAiWSIKfQ&threeDSSessionData=240000554

Figure: Example of notification with failed authentication result

cres=ewogICAiYWNzUmVmZXJlbmNlTnVtYmVyIiA6ICJBQ1NFbXUyIiwKICAgImFjc1RyYW5zSUQiIDog%0D%0AIjAwMDAwMDA
             wLTAwMDUtNWE1YS04MDAwLTAxNmQzZTI2ZWU2YyIsCiAgICJtZXNzYWdlVHlwZSIg%0D%0AOiAiQ1JlcyIsCi
             AgICJtZXNzYWdlVmVyc2lvbiIgOiAiMi4xLjAiLAogICAidGhyZWVEU1NlcnZl%0D%0AclRyYW5zSUQiIDogI
             jhiMjM0Y2ZmLTkzNjAtNTc5Yy04MDAwLTAwMDAwMDAwMDlhNiIsCiAgICJ0%0D%0AcmFuc1N0YXR1cyIgOiAi
             TiIKfQ==&threeDSSessionData=240000622

Format of payment completion request

When you process payment by using Gate and follow either basic or extended authentication workflow, after the authentication procedure is successfully completed, you need to send to the payment platform a request to complete the payment procedure and transfer actual money. You must create and send the request to the /v2/payment/card/3ds_result endpoint. The request must contain the following objects and parameters:

  • general—general identification information:
    • project_id—the project ID obtained from ECommPay
    • payment_id—payment ID which must be unique within the project
    • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification
  • pares—this parameter is used in the basic workflow and contains the 3‑D Secure 2 authentication result you obtain from the payment platform
  • cres—this parameter is used in the extended workflow and contains the 3‑D Secure 2 authentication result you obtain from the Access Control Server

In other words, a valid request for payment completion after authentication is complete must contain project ID, payment ID, signature and authentication result message.

Figure: Sample payment completion request

{
   "general": {
   "project_id": 42,
   "payment_id": "456789",
   "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
   },
   "cres": "ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMi
LAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlR
FNTZXJ2ZXJUcmFuc0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1
N0YXR1cyIgOiAiWSIKfQ"
}