Card processing - Credit Card Form
When requesting card payments via Computop hosted forms the complexity of 3-D Secure is completely removed from the merchant implementation. From a merchant point of view the sequence itself does not differ between 3DS authenticated and non-authenticated payments though 3DS requires consideration of additional data elements in the request and response. Notice about Cookie-/Session Handling Please note that some browsers might block necessary cookies when returning to Your shop. Here you will find additional information and different solution approaches.
Simplified Sequence Diagram
When requesting card payments via Computop hosted forms the complexity of 3-D Secure is completely removed from the merchant implementation. From a merchant point of view the sequence itself does not differ between 3DS authenticated and non-authenticated payments though 3DS requires consideration of additional data elements in the request and response. Notice about Cookie-/Session Handling Please note that some browsers might block necessary cookies when returning to Your shop. Here you will find additional information and different solution approaches.
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:
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:
| ||||||||
| 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. | ||||||||
| TransID | "transactionId": "..." | ans..64 | M | TransactionID provided by you which should be unique for each payment | ||||||||
| 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, ...). | |||||||||
| not used | an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: | |||||||||
| 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 | ||||||||
| Capture | an..6 | OM | Determines the type and time of capture.
| |||||||||
| PayTypes | "payment": {"cardForm": { "payTypes": "..." }} | ans..256 | O | With this parameter you can override the accepted schemes, i.e. you can decide within this parameter separated by pipe which of the available credit card schemes are displayed. The template must support this function like for example the "Cards_v1". Example: PayTypes=VISA|MasterCard | ||||||||
| "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 | ||||||||
| "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": { "priorAuthenticationInfo": JSON }} | JSON | O | Prior Transaction Authentication Information contains optional information about a 3DS cardholder authentication that occurred prior to the current transaction | |||||||||
| "accountInfo": JSON | JSON | O | The account information contains optional information about the customer account with the merchant | |||||||||
| "billing": JSON | JSON | C | The customer that is getting billed for the goods and / or services. Required for EMV 3DS 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 different from billToCustomer. | |||||||||
| "billing": {"addressInfo": JSON} | JSON | C | Billing address. Required for EMV 3DS (if available) unless market or regional mandate restricts sending this information. | |||||||||
| "shipping": {"addressInfo": JSON} | JSON | C | Shipping address. If different from billingAddress, required for EMV 3DS (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. If no | |||||||||
| subMerchantPF | "subMerchantPaymentFacilitator": JSON | JSON | O | Object specifying SubMerchant (Payment Facilitator) details.
| ||||||||
| URLSuccess | "urls": {"success": "..."} | ans..256 | M | Complete URL which calls up Paygate if payment has been successful. The URL may be called up only via port 443. This URL may not contain parameters: In order to exchange values between Paygate and shop, please use the parameter UserData.
| ||||||||
| URLFailure | "urls": {"failure": "..."} | ans..256 | M | Complete URL which calls up Paygate if payment has been unsuccessful. The URL may be called up only via port 443. This URL may not contain parameters: In order to exchange values between Paygate and shop, please use the parameter UserData.
| ||||||||
| URLBack | "urls": {"cancel": "..."} | ans..256 | O | Complete URL which Paygate calls in case that Cancel is clicked by the customer. The parameter "URLBack" can be sent
In order to exchange values between Paygate and shop you may use something like this:
When user cancels payment this URL is called exactly like this and you may use URL Decode to extract parameter and values. | ||||||||
| Response | not used | a7 | O | Status response sent by Paygate to URLSuccess and URLFailure, should be encrypted. For this purpose, transmit Response=encrypt parameter. | ||||||||
| URLNotify | "urls": {"notify": "..."} | ans..256 | M | 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.
| ||||||||
| UserData | ans..1024 | O | If specified at request, Paygate forwards the parameter with the payment result to the shop. | |||||||||
| Custom | "metadata": "..." | ans..1024 | O | "Custom"-parameter is added to the request data before encryption and is part of encrypted "Data" in Computop Paygate request. By this they are protected against manipulation by a consumer. The Custom-value is added to the Computop Paygate response in plain text and the "|" is replaced by a "&". By this you can put a single value into Custom-parameter and get multiple key-value-pairs back in response for your own purpose. Please find a samples here: Custom | ||||||||
| Plain | "metadata[plain]": "..." | ans..50 | O | A single value to be set by the merchant to return some information unencrypted in response/notify, e.g. the MID. "Plain"-parameter is part of encrypted "Data" in Computop Paygate and therefore protected against manipulation. | ||||||||
| expirationTime | "expirationTime": "..." | ans..19 | O | timestamp for the end time of the transaction processing, specified in UTC. Format: YYYY-MM-ddTHH:mm:ss |
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. Details are available here: Corporate PayPage and templates
The credit card form can be highly customized by using your own template.
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. "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
Key | Format | CND | Description | ||||
|---|---|---|---|---|---|---|---|
ans..30 | M | MerchantID, assigned by Computop | |||||
| msgver | ans..5 | M | Computop Paygate Message version. Valid values:
| ||||
| PayID | 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 | an32 | M | ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate | ||||
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment | ||||
| 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. | ||||
| refnr | 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 | 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 | n8 | M | Error code according to Paygate Response Codes (A4 Error codes) | ||||
JSON | M | Card data | |||||
JSON | O | Object containing IP information | |||||
JSON | M | Authentication data | |||||
JSON | C | In case the authentication process included a cardholder challenge additional information about the challenge result will be provided. | |||||
| externalPaymentData | JSON | O | Optional additional data from acquirer/issuer/3rd party for authorization. | ||||
| TimeStamp | Date/Time | O | Timestamp of this action if activated by Computop Helpdesk, e.g. 30.05.2023 08:47:57 or 30.05.2023 10:03:01.633 | ||||
| CardHolder | ans..50 | O | Card holder name if activated by Computop Helpdesk, e.g. John Doe | ||||
| bin | n..6 | O | BIN of credit card if activated by Computop Helpdesk, e.g. 40001 | ||||
| maskedpan | an..19 | O | Masked number of credit card if activated by Computop Helpdesk, e.g. 400001XXXXXX8323 | ||||
| cardinfo | JSON | O | JSON containing data of credit card type and issuer if activated by Computop Helpdesk, e.g. {"BIN":"400001","Brand":"VISA","Product":"","Source":"CREDIT","Type":"","Country":{"A3":"USA","N3":"840"},"Issuer":""} | ||||
| CCBrand | an..20 | O | Brand / card scheme of credit card, e.g. VISA | ||||
| PCNr | n16 | O | Pseudo Card Number: Random number generated by Computop Paygate which represents a genuine credit card number. The pseudo card number (PCN) starts with 0 and the last 3 digits correspond to those of the real card number. The PCN can be used like a genuine card number for authorisation, capture and credits. PCNr is a response value from Computop Paygate and is sent as CCNr in Request or part of card-JSON | ||||
| CCExpiry | n6 | OC | Optional in combination with PCNr: Expiry date of the credit card in the format YYYYMM (202207). | ||||
| Plain | ans..50 | O | A single value to be set by the merchant to return some information unencrypted in response/notify, e.g. the MID. "Plain"-parameter is part of encrypted "Data" in Computop Paygate and therefore protected against manipulation. | ||||
| Custom | ans..1024 | O | "Custom"-parameter is added to the request data before encryption and is part of encrypted "Data" in Computop Paygate request. By this they are protected against manipulation by a consumer. The Custom-value is added to the Computop Paygate response in plain text and the "|" is replaced by a "&". By this you can put a single value into Custom-parameter and get multiple key-value-pairs back in response for your own purpose. Please find a samples here: Custom | ||||
| UserData | ans..1024 | O | If specified at request, Paygate forwards the parameter with the payment result to the shop. | ||||
an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: |
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:
Key | REST | Format | CND | Description |
|---|---|---|---|---|
TxType | ans..20 | M | Submit “Order” to initialize a payment which later will be authorised via interface authorize.aspx. Please note that in combination with the used 3-D Secure method a separate setting is necessary. Please contact directly Computop Helpdesk. |
Additional parameters for credit card payments with separate authorisation
In order to authorise a previously with TxType=Order initiated SSL credit card payment, please visit 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:
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. | |||||||||
| 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. | ||||||||
| TransID | "transactionId": "..." | ans..64 | M | TransactionID provided by you which should be unique for each payment | ||||||||
| 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 | ||||||||
OrderDesc | "order": {"description": "..."} | ans..768 | O | Description of purchased goods, unit prices etc. | ||||||||
| not used | an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: | |||||||||
| Capture | an..6 | OM | Determines the type and time of capture.
|
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. 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 |
| Code | "code": ... | n8 | M | Error code according to Paygate Response Codes (A4 Error codes) |
| 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! |
| TransID | "transactionId": "..." | ans..64 | M | TransactionID provided by you which should be unique for each payment |
Status | a..50 | M | AUTHORIZED or FAILED | |
| 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, ...). |
Extended Sequence Diagram
