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.
Key | REST | Format | CND | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
BasicAuth.Username | ans..30 | M | MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too. | |||||||||||
msgver | not used | ans..5 | M | Computop Paygate Message version. Valid values:
| ||||||||||
TransID | "transactionId": "..." | ans..64 | M | TransactionID provided by you which should be unique for each payment | ||||||||||
ReqId | "requestId": "..." | ans..32 | O | To avoid double payments or actions (e.g. by ETM), enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction or action is submitted again with the same ReqID, Computop Paygate will not carry out the payment or new action, but will just return the status of the original transaction or action. Please note that the Computop Paygate must have a finalized transaction status for the first initial action (authentication/authorisation). This does not apply to 3-D Secure authentications that are terminated by a timeout. The 3-D Secure Timeout status does not count as a completed status in which the ReqID functionality on Paygate does not take effect. Submissions with identical ReqID for an open status will be processed regularly. Notice: Please note that a ReqID is only valid for 12 month, then it gets deleted at the Paygate. | ||||||||||
RefNr | "referenceNumber": "..." | O | Merchant’s unique reference number, which serves as payout reference in the acquirer EPA file. Please note, without the own shop reference delivery you cannot read out the EPA transaction and regarding the additional Computop settlement file (CTSF) we cannot add the additional payment data.
Only ASCII characters allowed, special characters ("Umlaute", diacritics) are not allowed and must be replaced by their ASCII-representation (e.g. ü → ue, é → e, ...). | |||||||||||
schemeReferenceID | "payment": {"card": { "schemeReferenceId": "..." }} | ans..64 | C | Card scheme specific transaction ID required for subsequent credential-on-file payments, delayed authorizations and resubmissions. Mandatory: CredentialOnFile – initial false – unscheduled MIT / recurring schemeReferenceID is returned for 3DS2-payments. In case of fallback to 3DS1 you will also need to check for TransactionId. The schemeReferenceID is a unique identifier generated by the card brands and as a rule Computop merchants can continue to use the SchemeReferenceIDs for subscription plans that were created while using another PSP environment / Paygate MerchantID / Acquirer ContractID / Acquirer. | ||||||||||
industrySpecificTxType | "payment": {"card": { "industrySpecificTransactionType": "..." }} | ans..20 | C | This parameter is required whenever an industry specific transaction is processed according to the card brands MIT (Merchant Initiated Transactions) Framework, i.e.: specific use cases like described below.
Values accepted:
Note: It is always submitted in conjunction with the "schemeReferenceID" parameter. Please contact Computop Helpdesk for the supported Acquirer and card brands. | ||||||||||
Amount | "amount": { "value": ...} | n..10 | M | Amount in the smallest currency unit (e.g. EUR Cent). Please contact the Computop Helpdesk, if you want to capture amounts <100 (smallest currency unit). | ||||||||||
Currency | "amount": { "currency": "..."} | a3 | M | Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: A1 Currency table | ||||||||||
card | "payment": {"card": JSON} | JSON | M | Card data | ||||||||||
Capture | an..6 | OM | Determines the type and time of capture.
| |||||||||||
billingDescriptor | "billing": {"addressInfo": { "descriptor": "..." }} | ans..22 | O | A descriptor to be printed on a card holder’s statement. Please also refer to the additional comments made elsewhere for more information about rules and regulations. | ||||||||||
OrderDesc | "order": {"description": "..."} | ans..768 | O | Order description | ||||||||||
AccVerify | "payment": {"card": { "accountVerification": "..." }} | a3 | O | Indicator to request an account verification (aka zero value authorization). If an account verification is requested the submitted amount will be optional and ignored for the actual payment transaction (e.g. authorization). Values accepted:
| ||||||||||
"payment": {"card": { "threeDsPolicy": JSON }} | JSON | O | Object specifying authentication policies and exemption handling strategies | |||||||||||
"payment": {"card": { "threeDSData": JSON }} | JSON | C | Object detailing authentication data in case authentication was performed through a third party or by the merchant | |||||||||||
"payment": {"card": { "priorAuthenticationInfo": JSON }} | JSON | O | Prior Transaction Authentication Information contains optional information about a 3-D Secure cardholder authentication that occurred prior to the current transaction | |||||||||||
"browserInfo": JSON | JSON | C | Accurate browser information are needed to deliver an optimized user experience. Required for 3-D Secure 2.0 transactions. | |||||||||||
"accountInfo": JSON | JSON | O | The account information contains optional information about the customer account with the merchant. Optional for 3-D Secure 2.0 transactions. | |||||||||||
"billing": JSON | JSON | C | The customer that is getting billed for the goods and / or services. Required unless market or regional mandate restricts sending this information. | |||||||||||
"shipping": JSON | JSON | C | The customer that the goods and / or services are sent to. Required (if available and different from billToCustomer) unless market or regional mandate restricts sending this information. | |||||||||||
"billing": {"addressInfo": JSON} | JSON | C | Billing address. Required for 3-D Secure 2.0 (if available) unless market or regional mandate restricts sending this information. | |||||||||||
"shipping": {"addressInfo": JSON} | JSON | C | Shipping address. If different from billingAddress, required for 3-D Secure 2.0 (if available) unless market or regional mandate restricts sending this information. | |||||||||||
"credentialOnFile": JSON | JSON | C | Object specifying type and series of transactions using payment account credentials (e.g. account number or payment token) that is stored by a merchant to process future purchases for a customer. Required if applicable. | |||||||||||
"riskIndicator": JSON | JSON | O | The Merchant Risk Indicator contains optional information about the specific purchase by the customer | |||||||||||
subMerchantPF | "subMerchantPaymentFacilitator": JSON | JSON | O | Object specifying SubMerchant (Payment Facilitator) details
| ||||||||||
TermURL | "payment": {"threeDSLegay": { "termUrl": "..." }} | ans..256 | C | Only for 3-D Secure: URL of the shop which has been selected by the Access Control Server (ACS) of the bank to transmit the result of the authentication. The bank transmits the parameters PayID, TransID and MerchantID via GET and the PAResponse parameter via POST to the TermURL. 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. | ||||||||||
URLNotify | "urls": {"notify": "..."} | ans..256 | C | Complete URL which Paygate calls up in order to notify the shop about the payment result. The URL may be called up only via port 443. It may not contain parameters: Use the UserData parameter instead. 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.
| ||||||||||
UserData | ans..1024 | O | If specified at request, Paygate forwards the parameter with the payment result to the shop. | |||||||||||
not used | an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: |
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. "paymentId": "..." May be "00000000000000000000000000000000" if not yet set by Computop Paygate "application/json" Merchant can use inquire.aspxREST Format CND Description an32 M "_Links.self.type": "..." an..20 M "_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"
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. MerchantId, RefNr) should not be checked case-sentive
Key | REST | Format | CND | Description |
---|---|---|---|---|
"merchantId": "..." | ans..30 | M | MerchantID, assigned by Computop | |
PayID | "paymentId": "..." | an32 | M | ID assigned by Paygate for the payment, e.g. for referencing in batch files as well as for capture or credit request. |
XID | "xId": "..." | an32 | M | ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate |
TransID | "transactionId": "..." | ans..64 | M | TransactionID provided by you which should be unique for each payment |
refnr | "referenceNumber": "..." | O | Reference number taken from request | |
Status | a..20 | M | Status of the transaction. Values accepted:
In case of Authentication-only the Status will be either | |
Description | "description": "..." | ans..1024 | M | Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis! |
Code | "code": ... | n8 | M | Error code according to Paygate Response Codes (A4 Error codes) |
"payment": {"card": JSON} | JSON | M | Card data | |
versioningdata | "payment": {"versioningdata": JSON} | JSON | M | The Card Range Data data element contains information that indicates the most recent EMV 3-D Secure version supported by the ACS that hosts that card range. It also may optionally contain the ACS URL for the 3-D Secure Method if supported by the ACS and the DS Start and End Protocol Versions which support the card range. |
threeDSLegacy | "payment": {"threeDSLegacy": JSON} | JSON | C | Object containing the data elements required to construct the Payer Authentication request in case of a fallback to 3-D Secure 1.0. |
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. "paymentId": "..." May be "00000000000000000000000000000000" if not yet set by Computop Paygate "application/json" Merchant can use inquire.aspxREST Format CND Description an32 M "_Links.self.type": "..." an..20 M "_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"
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. MerchantId, 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