Specific parameters for iCard
Besides the general parameters described above for the credit card connection, iCard requires the following additional parameters. An authorisation with 3-D Secure is possible.
Notice: For security reasons, Computop Paygate rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter. The following table describes the additional encrypted payment request parameters described below for "interface via form" and "interface via Server-to-Server" :
Additional parameters for credit card payments
The following table describes the result parameters with which the Computop Paygate responds to your system. these result parameters are additional to the standard parameters for "interface via form" and "interface via Server-to-Server" described below pls. be prepared to receive additional parameters at any time and do not check the order of parameters the key (e.g. mid, RefNr) should not be checked case-sentive
Additional response parameters for credit card payments
Payment Request
To retrieve a Computop card form please submit the following data elements via HTTP POST request method to https://www.computop-paygate.com/payssl.aspx.
Notice: For security reasons, Computop Paygate rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.
The following table describes the encrypted payment request parameters:
Computop Paygate will return an HTML document in the response body representing the requested card form. The form may be included in the merchant checkout page or used as a standalone page to redirect the card holder to.
Card holder authentication and payment authorization will take place once the the cardholder entered all required card details and submitted the form data to Computop Paygate.
Note: In case you are using your own templates (Corporate Payment Page), please make sure you include Cardholder name on your custom template. Cardholder name is mapped to Paygate API parameter "CreditCardHolder". Cardholder name field must not contain any special characters and must have minimal length of 2 characters and maximum length of 45 characters.
When the payment is completed Computop Paygate will send a notification to the merchant server (i.e. URLNotify) and redirect the browser to the URLSuccess respectively to the URLFailure.
The blowfish encrypted data elements as listed in the following table are transferred via HTTP POST request method to the URLNotify and URLSuccess/URLFailure.
The credit card form can be highly customized by using your own template.
Details are available here: Corporate PayPage and templates
HTTP POST to URLSuccess / URLFailure / URLNotify
In case of using REST API
In case of using REST API you will always receive a link where the merchant has to redirect the consumer to complete the payment.
REST | Format | CND | Description |
---|---|---|---|
"paymentId": "..." | an32 | M | May be "00000000000000000000000000000000" if not yet set by Computop Paygate |
"_Links.self.type": "..." | an..20 | M | "application/json" |
"_Links.redirect.href": "..." | an..1024 | M | Merchant needs to redirect consumer to this URL to complete payment |
"_Links.redirect.type": "..." | an..20 | M | "text/html" |
Merchant can use inquire.aspx
The following table gives the result parameters which Computop Paygate transmits to URLSuccess or URLFailure and URLNotify. If you have specified the Response=encrypt parameter, the following parameters are sent Blowfish encrypted to your system:
pls. be prepared to receive additional parameters at any time and do not check the order of parameters
the key (e.g. mid, RefNr) should not be checked case-sentive
Credit card payments with separate authorisation
For credit card payments the ORDER can be separated from the subsequent authorisation and the following steps. Therefore initially the SSL credit card payment is initiated via Paygate form or via Server-to-Server-connection like in the chapters above with an additional parameter. Later it is authorised using the interface authorize.aspx via server-to-server connection. For initialising visit the following URL:
https://www.computop-paygate.com/payssl.aspx |
For Server-to-Server-connection it is the following URL:
https://www.computop-paygate.com/direct.aspx |
The following table describes the encrypted payment request parameters:
Additional parameters for credit card payments with separate authorisation
In order to authorise a previously with TxType=Order initiated SSL credit card payment, please use the following URL:
https://www.computop-paygate.com/authorize.aspx |
Notice: Please note, that for an initial order KPN/CVC/CVV-check is not possible. For the subsequent reservation request this ID also cannot be passed on.
Notice: For security reasons, Computop Paygate rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.
The following table describes the encrypted payment request parameters:
Parameters for credit card payments via authorize.aspx
The following table describes the result parameters with which the Computop Paygate responds to your system
pls. be prepared to receive additional parameters at any time and do not check the order of parameters
the key (e.g. mid, RefNr) should not be checked case-sentive
Extended Sequence Diagram
Payment Initiation
The initial request to Computop Paygate will be the same regardless of the underlying 3-D Secure Protocol.
In order to start a server-to-server 3-D Secure card payment sequence please post the following key-value-pairs to https://www.computop-paygate.com/ direct.aspx.
Call of interface: general parameters
Notice: For credit card payments with 3-D Secure, please note the different cases as explained separately in the chapter at the start of the handbook. If the credit card is registered for Verified or SecureCode or SafeKey, the next phase is divided into two steps of authentication and payment. However it always begins in the same way via the direct.aspx interface. The first response however is the receipt of Javascript code or other parameters in order to carry out a second call up of the direct3d.aspx interface. Only after that, do you receive the listed parameter as a response.
To carry out a credit card payment via a Server-to-Server connection, please use the following URL:
https://www.computop-paygate.com/direct.aspx |
Request Elements
Notice: For security reasons, Computop Paygate rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.
The following table describes the encrypted payment request parameters:
Notice: In case of a merchant initiated recurring transaction the JSON objects (besides credentialOnFile and card), the URLNotify and TermURL are not mandatory parameters, because no 3-D Secure and no risk evaluation is done by the card issuing bank and the payment result is directly returned within the response.
General parameters for credit card payments via socket connection
Please note the additional parameter for a specific credit card integration in the section "Specific parameters"
Response Elements (authentication)
In case of using REST API
In case of using REST API you will always receive a link where the merchant has to redirect the consumer to complete the payment.
REST | Format | CND | Description |
---|---|---|---|
"paymentId": "..." | an32 | M | May be "00000000000000000000000000000000" if not yet set by Computop Paygate |
"_Links.self.type": "..." | an..20 | M | "application/json" |
"_Links.redirect.href": "..." | an..1024 | M | Merchant needs to redirect consumer to this URL to complete payment |
"_Links.redirect.type": "..." | an..20 | M | "text/html" |
Merchant can use inquire.aspx
The following table describes the result parameters with which the Computop Paygate responds to your system
pls. be prepared to receive additional parameters at any time and do not check the order of parameters
the key (e.g. mid, RefNr) should not be checked case-sentive
versioningData
The
versioningData
object will indicate the EMV 3-D Secure protocol versions (i.e. 2.1.0 or higher) that are supported by Access Control Server of the issuer.
If the corresponding protocol version fields are NULL it means that the BIN range of card issuer is not registered for 3-D Secure 2.0 and a fallback to 3-D Secure 1.0 is required for transactions that are within the scope of PSD2 SCA.
When parsing versioningData
please also refer to the subelement errorDetails
which will specify the reason if some fields are not pupoluated (e.g. Invalid cardholder account number passed, not available card range data, failure in encoding/serialization of the 3-D Secure Method data etc).
BASEURL= https://www.computop-paygate.com/
{ "threeDSServerTransID": "14dd844c-b0fc-4dfe-8635-366fbf43468c", "acsStartProtocolVersion": "2.1.0", "acsEndProtocolVersion": "2.1.0", "dsStartProtocolVersion": "2.1.0", "dsEndProtocolVersion": "2.1.0", "threeDSMethodURL": "http://www.acs.com/script", "threeDSMethodDataForm": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly93d3cuY29tcHV0b3AtcGF5Z2F0ZS5jb20vY2JUaHJlZURTLmFzcHg_YWN0aW9uPW10aGROdGZuIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIxNGRkODQ0Yy1iMGZjLTRkZmUtODYzNS0zNjZmYmY0MzQ2OGMifQ==", "threeDSMethodData": { "threeDSMethodNotificationURL": "BASEURL/cbThreeDS.aspx?action=mthdNtfn", "threeDSServerTransID": "14dd844c-b0fc-4dfe-8635-366fbf43468c" } }
3-D Secure Method
The 3-D Secure Method allows for additional browser information to be gathered by an ACS prior to receipt of the authentication request message (AReq) to help facilitate the transaction risk assessment. Support of 3-D Secure Method is optional and at the discretion of the issuer.
The versioningData
object contains a value for
threeDSMethodURL
. The merchant is supposed to invoke the 3-D Secure Method via a hidden HTML iframe in the cardholder browser and send a form with a field named threeDSMethodData
via HTTP POST to the ACS 3-D Secure Method URL.
3-D Secure Method: threeDSMethodURL
Please note that the threeDSMethodURL
will be populated by Computop Paygate if the issuer does not support the 3-D Secure Method. The 3-D Secure Method Form Post as outlined below must be performed independently from whether it is supported by the issuer. This is necessary to facilitate direct communication between the browser and Computop Paygate in case of a mandated challenge or a frictionless flow.
3-D Secure Method: No issuer threeDSMethodURL
3-D Secure Method Form Post
<form name="frm" method="POST" action="Rendering URL"> <input type="hidden" name="threeDSMethodData" value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNhYzdjYWE3LWFhNDItMjY2My03OTFiLTJhYzA1YTU0MmM0YSIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIn0"> </form>
Netcetera 3DS Web SDK
You may use the operations init3DSMethod
or createIframeAndInit3DSMethod
at your discreation from the nca3DSWebSDK in order to iniatiate the 3-D Secure Method. Please refer to the Integration Manual at https://mpi.netcetera.com/3dsserver/doc/current/integration.html#Web_Service_API.
Once the 3-D Secure Method is concluded the ACS will instruct the cardholder browser through the iFrame response document to submit threeDSMethodData
as a hidden form field to the 3-D Secure Method Notification URL.
ACS Response Document
<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"/> <title>Identifying...</title> </head> <body> <script> var tdsMethodNotificationValue = 'eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImUxYzFlYmViLTc0ZTgtNDNiMi1iMzg1LTJlNjdkMWFhY2ZhMiJ9'; var form = document.createElement("form"); form.setAttribute("method", "post"); form.setAttribute("action", "notification URL"); addParameter(form, "threeDSMethodData", tdsMethodNotificationValue); document.body.appendChild(form); form.submit(); function addParameter(form, key, value) { var hiddenField = document.createElement("input"); hiddenField.setAttribute("type", "hidden"); hiddenField.setAttribute("name", key); hiddenField.setAttribute("value", value); form.appendChild(hiddenField); } </script> </body> </html>
3-D Secure Method Notification Form
<form name="frm" method="POST" action="3DS Method Notification URL"> <input type="hidden" name="threeDSMethodData" value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImUxYzFlYmViLTc0ZTgtNDNiMi1iMzg1LTJlNjdkMWFhY2ZhMiJ9"> </form>
Please note that the threeDSMethodNotificationURL
as embedded in the Base64 encoded threeDSMethodData
value points to Computop Paygate and must not be modified. The merchant notification is delivered to the URLNotify as provided in the original request or as configured for the MerchantID in Computop Paygate .
Authentication
If 3-D Secure Method is supported by the issuer ACS and was invoked by the merchant Computop Paygate will automatically continue with the authentication request once the 3-D Secure Method has completed (i.e. 3-D Secure Method Notification).
The authentication result will be transferred via HTTP POST to the URLNotify
. It may indicate that the Cardholder has been authenticated, or that further cardholder interaction (i.e. challenge) is required to complete the authentication.
In case a cardholder challenge is deemed necessary Computop Paygate will transfer a JSON object within the body of HTTP browser response with the elements acsChallengeMandated
, challengeRequest
, base64EncodedChallengeRequest
and acsURL
. Otherwise, in a frictionless flow, Computop Paygate will automatically continue and respond to the cardholder browser once the authorization completed.
Cardholder Challenge: Browser Response
Browser Challenge Response
Data Elements
Schema: Browser Challenge Response
{ "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "acsChallengeMandated": {"type": "boolean"}, "challengeRequest": {"type": "object"}, "base64EncodedChallengeRequest": {"type": "string"}, "acsURL": {"type": "string"} }, "required": ["acsChallengeMandated", "challengeRequest", "base64EncodedChallengeRequest", "acsURL"], "additionalProperties": false }
Sample: Browser Challenge Response
{ "acsChallengeMandated": false, "challengeRequest": { "threeDSServerTransID": "8a880dc0-d2d2-4067-bcb1-b08d1690b26e", "acsTransID": "d7c1ee99-9478-44a6-b1f2-391e29c6b340", "messageType": "CReq", "messageVersion": "2.1.0", "challengeWindowSize": "01", "messageExtension": [ { "name": "emvcomsgextInChallenge", "id": "tc8Qtm465Ln1FX0nZprA", "criticalityIndicator": false, "data": "messageExtensionDataInChallenge" } ] }, "base64EncodedChallengeRequest": "base64-encoded-challenge-request", "acsURL": "acsURL-to-post-challenge-request" }
Authentication Notification
The data elements of the authentication notification are listed in the table below.
Browser Challenge
If a challenge is deemed necessary (see challengeRequest) the browser challenge will occur within the cardholder browser. To create a challenge it is required to post the value base64EncodedChallengeRequest
via an HTML iframe to the ACS URL.
Challenge Request
<form name="challengeRequestForm" method="post" action="acsChallengeURL"> <input type="hidden" name="creq" value="ewogICAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjogIjhhODgwZGMwLWQyZDItNDA2Ny1iY2IxLWIwOGQxNjkwYjI2ZSIsCiAgICAiYWNzVHJhbnNJRCI6ICJkN2MxZWU5OS05NDc4LTQ0YTYtYjFmMi0zOTFlMjljNmIzNDAiLAogICAgIm1lc3NhZ2VUeXBlIjogIkNSZXEiLAogICAgIm1lc3NhZ2VWZXJzaW9uIjogIjIuMS4wIiwKICAgICJjaGFsbGVuZ2VXaW5kb3dTaXplIjogIjAxIiwKICAgICJtZXNzYWdlRXh0ZW5zaW9uIjogWwoJCXsKCQkJIm5hbWUiOiAiZW12Y29tc2dleHRJbkNoYWxsZW5nZSIsCgkJCSJpZCI6ICJ0YzhRdG00NjVMbjFGWDBuWnByQSIsCgkJCSJjcml0aWNhbGl0eUluZGljYXRvciI6IGZhbHNlLAoJCQkiZGF0YSI6ICJtZXNzYWdlRXh0ZW5zaW9uRGF0YUluQ2hhbGxlbmdlIgoJCX0KICAgIF0KfQ=="> </form>
init3DSChallengeRequest
or createIFrameAndInit3DSChallengeRequest
from the nca3DSWebSDK in order submit the challenge message through the cardholder browser.Init 3-D Secure Challenge Request - Example
<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <script src="nca-3ds-web-sdk.js" type="text/javascript"></script> <title>Init 3-D Secure Challenge Request - Example</title> </head> <body> <!-- This example will show how to initiate Challenge Reqeuests for different window sizes. --> <div id="frameContainer01"></div> <div id="frameContainer02"></div> <div id="frameContainer03"></div> <div id="frameContainer04"></div> <div id="frameContainer05"></div> <iframe id="iframeContainerFull" name="iframeContainerFull" width="100%" height="100%"></iframe> <script type="text/javascript"> // Load all containers iFrameContainerFull = document.getElementById('iframeContainerFull'); container01 = document.getElementById('frameContainer01'); container02 = document.getElementById('frameContainer02'); container03 = document.getElementById('frameContainer03'); container04 = document.getElementById('frameContainer04'); container05 = document.getElementById('frameContainer05'); // nca3DSWebSDK.init3DSChallengeRequest(acsUrl, creqData, container); nca3DSWebSDK.init3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', iFrameContainerFull); // nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest(acsUrl, creqData, challengeWindowSize, frameName, rootContainer, callbackWhenLoaded); nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '01', 'threeDSCReq01', container01); nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '02', 'threeDSCReq02', container02); nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '03', 'threeDSCReq03', container03); nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '04', 'threeDSCReq04', container04); nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '05', 'threeDSCReq05', container05, () => { console.log('Iframe loaded, form created and submitted'); }); </script> </body> </html>
Please note that the notification URL submited in the challenge request points to Computop Paygate and must not be changed.
Authorization
After successful cardholder authentication or proof of attempted authentication/verification is provided Computop Paygate will automatically continue with the payment authorization.
In case the cardholder authentication was not successful or proof proof of attempted authentication/verification can not be provided Computop Paygate will not continue with an authorization request.
In both cases Paygate will deliver a notification with the authentication result to the merchant specified
URLNotify
with the data elements as listed in the table below.
Payment Notification
In case of using REST API
In case of using REST API you will always receive a link where the merchant has to redirect the consumer to complete the payment.
REST | Format | CND | Description |
---|---|---|---|
"paymentId": "..." | an32 | M | May be "00000000000000000000000000000000" if not yet set by Computop Paygate |
"_Links.self.type": "..." | an..20 | M | "application/json" |
"_Links.redirect.href": "..." | an..1024 | M | Merchant needs to redirect consumer to this URL to complete payment |
"_Links.redirect.type": "..." | an..20 | M | "text/html" |
Merchant can use inquire.aspx
In case of using Key-Value-Pair API
The following table gives the result parameters which Computop Paygate transmits to URLSuccess or URLFailure and URLNotify. If you have specified the Response=encrypt parameter, the following parameters are sent Blowfish encrypted to your system:
pls. be prepared to receive additional parameters at any time and do not check the order of parameters
the key (e.g. mid, RefNr) should not be checked case-sentive
Browser Payment Response
Additionally the JSON formatted data elements as listed below are transferred in the HTTP response body to the cardholder browser. Please note that the data elements (i.e. MID
, Len
, Data
) are base64 encoded.
Data Elements
Schema
{ "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "MID": { "type": "string" }, "Len": { "type": "integer" }, "Data": { "type": "string" } }, "required": ["MID", "Len", "Data"], "additionalProperties": false }
Decrypted Data
Sample decrypted Data
MID=YourMID&PayID=PayIDassignedbyPlatform&TransID=YourTransID
Capture / Credit / Reversal
Capture
Captures are possible via a Server-to-Server connection. To perform a capture via a Server-to-Server connection please use the following URL:
https://www.computop-paygate.com/capture.aspx |
Notice: For security reasons, Computop Paygate rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter. The following table describes the encrypted payment request parameters:
Parameters for captures of credit card payments
The following table describes the result parameters with which the Computop Paygate responds to your system pls. be prepared to receive additional parameters at any time and do not check the order of parameters the key (e.g. mid, RefNr) should not be checked case-sentive
Response parameters for captures of credit card payments
Capture (Multiple Partial)
Captures are possible via a Server-to-Server connection. In case of multiple partial captures, an extra JSON object needs to be sent. To perform a capture via a Server-to-Server connection please use the following URL:
https://www.computop-paygate.com/capture.aspx |
Notice: For security reasons, Computop Paygate rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter. The following table describes the encrypted payment request parameters:
Parameters for multiple partial captures of credit card payments
The following table describes the result parameters with which the Computop Paygate responds to your system pls. be prepared to receive additional parameters at any time and do not check the order of parameters the key (e.g. mid, RefNr) should not be checked case-sentive
Response parameters for multiple partial captures of credit card payments
Credit with reference
Credits (refunds) are possible via a Server-to-Server connection. Paygate permits credits which relate to a capture previously activated by Paygate and allows merchants to carry out credits without a reference transaction. This section describes the processing of credits with reference transactions. If you refer to a capture for a Credit, the amount of the Credit is limited to the amount of the previous capture.
To carry out a credit with a reference transaction, please use the following URL:
https://www.computop-paygate.com/credit.aspx |
Notice: For security reasons, Computop Paygate rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter. The following table describes the encrypted payment request parameters:
Parameters for credits of credit card payments
The following table describes the result parameters with which the Computop Paygate responds to your system pls. be prepared to receive additional parameters at any time and do not check the order of parameters the key (e.g. mid, RefNr) should not be checked case-sentive
Response parameters for credits of credit card payments
Credit with reference (for multiple captures)
Credits (refunds) are possible via a Server-to-Server connection. Paygate permits credits which relate to a capture previously activated by Paygate and allows merchants to carry out credits without a reference transaction. This section describes the processing of credits with reference transactions. This action will credit a specific partial capture , using a specific identifier (XID), the same received when performing the capture.
To carry out a credit with a reference transaction done using the multiple partial capture feature, please use the following URL:
https://www.computop-paygate.com/credit.aspx |
Notice: For security reasons, Computop Paygate rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter. The following table describes the encrypted payment request parameters:
Parameters for credits of multiple captures of credit card payments
The following table describes the result parameters with which the Computop Paygate responds to your system pls. be prepared to receive additional parameters at any time and do not check the order of parameters the key (e.g. mid, RefNr) should not be checked case-sentive