1 About card payments

1.1 General information about card payments

First Cash Solution’s the 1cs Online Payment System processes all major cards and currencies worldwide. Card data is protected against unauthorised access by TLS encryption. Additional security functions are integrated fraud prevention and risk management. Our standardized settlement files guarantee a straightforward reconciliation processes in your accounting.

Visa Secure and MasterCard SecureCode secure your payment claim by password validation if a customer disputes the payment later. American Express SafeKey also uses the 3-D Secure technology, which means that the card holder must confirm their identity with a password.

Transaction processing can be made via the 1cs Online Payment System standard form, via customized forms, via server-to-server-connection or via batch transfer. Likewise the 1cs Online Payment System can process transactions from stationary terminals.

Using the card form provides several advantages:

1. Merchants can bypass the costly PCI-security authorisation
2. The programming of 3-D Secure with forms is much easier and quicker than via Server-to-Server connection

1.2 Process of 3-D Secure payments

MasterCard SecureCode (UCAF), Visa Secure, Diners ProtectBuy, JCB J/Secure and American Express SafeKey are authentication methods which verify the identity of the card holder before making the payment. The name 3-D Secure used by technicians describes only the protocol. The correct brand names are Verified by Visa, MasterCard SecureCode, SafeKey, ProtectBuy and J/Secure.

Merchants benefit from authentication with 3-D Secure because the card schemes provide a liability shift: If you are using Visa Secure, MasterCard SecureCode, Diners ProtectBuy, JCB-Card J/Secure or American Express SafeKey, the burdon of proof and thereby generally the liability is shifted from the merchant to the card issuing bank, should the customer dispute the payment. Irrespective of whether the card holder actually uses the authentication you obtain a very high protection against payment defaults / chargebacks in case the customer states they have not authorised the card payment. Your Acquirer will be able to discuss the details of 3-D Secure and the cover that it provides.

From a technical perspective 3-D Secure is not a payment method but an authentication process which precedes the payment: Once the credit card data has been entered, the 1cs Online Payment System checks the identity of the card holder and does not process the payment until after the authentication.

For further steps it is crucial if the credit card connection is made via form interface or via Server-to-Server-connection. In the first case the 1cs Online Payment System form assumes the further authentication process, with Server-to-Server-connection the merchant has to manage the authentication through a separate interface.

Notice: Please make sure to review our EMV 3D Secure Specification to integrate according to the newest standards.

Notice: Please notice that in case of Fallback to 3-D Secure 1.0 the URLSuccess or URLFailure is called with GET. Therefore your systems should be able to receive parameters both via GET and via POST.

1.2.1 Process of a transaction with 3-D Secure via form interface

When requesting card payments via 1cs Online Payment System 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.

Simplified Sequence Diagram

When requesting card payments via the 1cs Online Payment System 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.

The 1cs Online Payment System 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 the 1cs Online Payment System.

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 the 1cs Online Payment System 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.

Notice: Please note that the call of URLSuccess or URLFailure takes place with a GET in case of fallback to 3-D Secure 1.0. Therefore your systems should be able to receive parameters both via GET and via POST.

The credit card form can be highly customized by using your own template. 

Details are available here: Corporate PayPage and templates

If the password is correct the 1cs Online Payment System obtains confirmation in the form of a signature. Only after confirmation does the 1cs Online Payment System start the payment and send the transaction with the signature to the Acquiring Bank.

Details on the integration can be found here: Credit Card Form (paySSL)

1.2.2 Process of a transaction with 3-D Secure via Server-to-Server-connection

A 3-D Secure 2.0 payment sequence may comprise the following distinct activities:

• Versioning: Request ACS and DS Protocol Version(s) that correspond to card account range as well as an optional 3-D Secure Method URL
• 3-D Secure Method: Connect the cardholder browser to the issuer ACS to obtain additional browser data
• Authentication: Submit authentication request to the issuer ACS
• Challenge: Challenge the card holder if mandated
• Authorization: Authorize the authenticated transaction with the acquirer

Please note that the the communication between client and Access Control Server (ACS) is implemented through iframes. Thus, responses arrive in an HTML subdocument and you may establish correspondent event listeners in your root document.

Alternatively you could solely rely on asynchronous notifications delivered to your backend. In those cases you may have to consider methods such as long polling, SSE or websockets to update the client.

The initial request to the 1cs Online Payment System 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.

1.3 Credit card brands

1.3.1 Overview of supported card schemes by payment method

Card processing

The 1cs Online Payment System processes all major cards and currencies worldwide. Transaction processing can be made via the 1cs Online Payment System standard form, via customized forms, via server-to-server-connection or via batch transfer. Likewise the 1cs Online Payment System can process transactions from stationary terminals.

Bancontact

Bancontact is a Belgian payment method for Debit cards with which the merchant obtains a payment guarantee and eliminates the risk of chargebacks. At the Bancontact checkout customers enter their card details and are then directed to their own online bank where they simply need to authorize the payment they have just made.

Be2Bill

Be2bill is specially optimized for the “Cartes Bancaires” credit cards which is widely used in France.

Cofidis

The 4-star card is a private card that combines payment facilities and loyalty benefits. The design of tailor-made products and services has been adapted to customers, expectations and needs. Pay for your purchases in several instalments. The 4-star card is a revolving credit card that offers you the possibility, depending on the amount of your purchases and the brand, to pay in several instalments.

Korea CC

KoreaCC is a payment method which enables Korean merchants (based in South Korea) to offer domestic customers (with Korean credit cards) a credit card payment method.

MasaPay

Shanghai MasaPay Information Technology Co., Ltd. is a third-party transnational e-payment service provider which was established in July 2012. Her headquarter is based in Lujiazui Financial Service District, Shanghai, China.

MasaPay offers an Online Payment Gateway, which supports credit card payment of Visa, MasterCard, JCB, AMEX, Discover, Diners etc. MasaPay makes it possible that the cross-border payments from outside China are acquired in China.

PagBrasil

Payments with the Brazilian credit cards Hipercard, Elo and Aura can be processed via the 1cs Online Payment System. The 1cs Online Payment Systemoffers extensive support for the control optimisation as well as foreign currency conversion.

More than 30% of online payments in Brazil are made using the Boleto Bancário cash-in solution. With a payment form customers can pay in cash in supermarkets, post office branches or at one of over 48,000 bank terminals.

PIX via PagBrasil is now also supported.

PayU India

With the integration of PayU biz India merchants open the door to a rapidly growing e-commerce market. Only 30% of online customers in India have access to internationally accepted payment methods. With the integration of PayU biz via the 1cs OPS merchants can offer 76 local payment methods to serve the majority of customers. This comprises of online transfers, credit and debit cards, eWallets and cash-in payments.

PayU LatAm

Within the extremely heterogeneous e-commerce market of Latin America success depends on offering the requested payment methods. The integration of PayU gives the merchant access to 74 payment methods from Mexico to Argentina. Besides all major online transfers as well as credit and debit cards PayU also offers payments with modern e-wallets and popular cash-in-payments.

2 Card processing – common form

2.1 Card processing – Credit Card Form

When requesting card payments via the 1cs Online Payment System 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.

2.1.1 Simplified Sequence Diagram

When requesting card payments via the 1cs OPS 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.

2.1.2 Payment Request

To retrieve a 1cs OPS 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, the 1cs OPS 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:

The 1cs Online Payment System 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 the 1cs Online Payment System.

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 the 1cs Online Payment Systeme 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.

Notice: Please note that the call of URLSuccess or URLFailure takes place with a GET in case of fallback to 3-D Secure 1.0. Therefore your systems should be able to receive parameters both via GET and via POST.

The credit card form can be highly customized by using your own template. 

Details are available here: Corporate PayPage and templates

2.1.3 HTTP POST to URLSuccess / URLFailure / URLNotify

The following table gives the result parameters which the 1cs Online Payment System 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:

• be prepared to receive additional parameters at any time and do not check the order of parameters

• the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive

2.1.4 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 the 1cs OPS 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:

For Server-to-Server-connection it is the following URL:

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 visit the following URL:

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, the 1cs OPS 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 1cs online payment system responds to your system

• be prepared to receive additional parameters at any time and do not check the order of parameters

• the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive

Ergebnis-Parameter für Kreditkartenzahlungen über authorize.aspx

2.1.5 Erweitertes Sequenz-Diagramm

2.2 Corporate PayPage

The 1cs Online Payment System forms are framed as standard in white and grey. Merchants can customise the layout of the forms with the help of layout parameters. The simplest way to change the layout is to set the parameters for the background colour (BGColor), background image (BGImage) and the font (FFace). You can use XSL-templates to change the layout further:

In the case of credit card payments you can change the parameter Template to create an individual layout for your PaySSL form which exactly matches the shop layout. To this end your graphic designer can design an HTML-template in the shop-design based on XSLT (Extensible Stylesheet Language Transformation). First Cash Solution Support copies this XSLT-template to our the 1cs Online Payment System Server. If you enter the name of your XSLT-file in the Template parameter, the 1cs Online Payment System form will appear in your layout.

For general information about XSLT see www.w3.org.

Please note, that the 1cs OPS is a fee-based additional service. Please ask 1cs OPS Sales thereun.

1cs OPS provides a programming example for creating a responsive credit card form online at https://www.computop.com/de/xslt. The template files to be created – XSL and XML – afterwards are transformed automatically for the various browsers. Please ensure before sending to the 1cs Online Payment System that both files can be loaded into the browser correctly. The complete code must be able to be displayed and no error message are allowed. If an error message occurs the code and used tags have to be revised. Please note that new versions must be available not later then 3:30 pm in order to to be processed on the same day.

The subsequent conventions apply for the use of the Corporate Paypage with XSLT:

2.2.1 File names

A XSL file designed by you defines your individual layout. The associated XML file contains the texts that are to be displayed on the form. Hence, multilingualism is easy. Always use your MerchantID in the names of the files.

XSL template:                   MerchantID_PaySSL.xsl
XML text file:                    MerchantID_PaySSL.xml
Sub-folder for images:   Templates/imagesMerchantID

In order not to receive safety notices, please ensure that external image sources are retrieved via SSL.

In order to call the individual layout, use the ‘template’ parameter with your MerchantID and attach it unencrypted to the call of the First Cash Solution payment page, for example: https://www.computop-paygate.com/payssl.aspx?MerchantID=IhreMID&Len=123&Data=AGSDJ…ASDF&template=IhreMerchantID

2.2.2 Field names of the form

When implementing the text field for the credit card number, use the following values for the parameters ‘name’ and ‘id’:

Year of expiry:                          „cardExpirationYear“
Expiry date month:                 „cardExpirationMonth“
Credit card number:               „cardNumber“
Card verification number:      „cccvc“
Card brand:                            „ccBrand“

A text field for the input of the credit card number is then implemented as follows:

<input type=”text” name=”KKNr” id= “KKNr” value=””></input>

2.2.3 Hidden Fields

The following hidden fields must be implemented so that the values can be passed on when sending the form:

2.2.4 Language selection

The language selection in form PaySSL.aspx is automatically based on the parameterLanguage. Other language areas are filtered out. If you wish to access the field of another language area e.g. with JavaScript, you can do so via the following path: paygate/language/@name.

2.2.5 XML structure

The ‘language’ parameter controls which section of the XML text file is read out. German ‘de’ is always used as standard.

The XML file should have the following basic structure:

<?xml version="1.0" encoding="windows-1252"?>

       </languages>              <language name="de">              </language>              <language name="en">              </language>        </languages>

‘UTF-8’ is also possible for the encoding.

With <xsl:variablename=““ select=“paygate/language/@name”/> you can directly address an XML language section from the XSL file.

For an overview of which parameters are additionally rendered by the PaySSL, please examine the following structure (XSL file is rendered against the following XML string):

strXML = “<?xml version=’1.0′ encoding=’windows-1252′?>” & _

       “<paygate pay=’ssl’>” & _

                    “<merchantID>”…”</merchantID>” & _

                    “<len>”…”</len>” & _

                    “<data>”…”</data>” & _

                    “<Background>”…”</Background>” & _

                    “<BGImage>”…”</BGImage>” & _

                    “<BGColor>”…”</BGColor>” & _

                    “<FFace>”…”</FFace>” & _

                    “<FSize>”…”</FSize>” & _

                    “<FColor>”…”</FColor>” & _

                    “<center>”…”</center>” & _

                    “<CCard>”…”</CCard>” & _

                    “<Year>”…”</Year>” & _

                    “<URLBack>”…”</URLBack>” & _

                    “<twidth>”…”</twidth>” & _

                    “<theight>”…”</theight>” & _

                    “<brands><brand>”…”</brand></brands>” &_

                    “<cvc>”…”</cvc>” &_

                    “<ccexpiryyear>” … “</ccexpiryyear>” & _

                    “<ccbrand>” … “</ccbrand>” & _

                    “<template>”…”</template>” & _

                    “<counter>”… “</counter>” & _

                    “<notify>”… “</notify>” & _

                    “<errorcode>”…”</errorcode>” & _

                    “<PCNr>”…”</PCNr>” & _

                    “<PCNrBrand>”… “</PCNrBrand>” & _

                    “<PCNrMonth>”… “</PCNrMonth>” & _

                    “<PCNrYear>”… “</PCNrYear>” & _

                    “<creditcardholder>” … “</creditcardholder>” & _

                    “<Autostart>”…”</Autostart>” & _

       <language/@name …   (Area for selected language-Node)

       (content of MerchantId_PaySSL.xml in the respective language)>

       “</paygate>”

Since merchants use its own layout for the form, you do not require the layout parameter. However, it is possible after prior consultation with First Cash Solution to use the parameters for the transfer, e.g. the SessionID.

2.2.6 Error mapping

In the case of the error codes listed below First Cash Solution returns the form in order to enable the credit card data to be entered again. You only have to evaluate the ‘error code’ parameter and display the desired text from your XML file.

At this point the ‘error code’ template is called:

<xsl:apply-templates select=“/paygate/errorcode” />

The called-up ‘error code’ template may look like this. It can alternatively be implemented with ‘if’.

<xsl:template match="errorcode">

  <tr>     <td> <xsl:choose> <xsl:when test=".='0015'"> <xsl:value-of select="/paygate/language/ErrorCodeDescription/Description1"/>        <!--The input of the credit card number was not correct--> </xsl:when> ... </xsl:choose> </td> </tr> </xsl:template>

It is also possible to integrate the error messages directly into the (main) template:

<xsl:if test="paygate/errorcode != ''">

       <xsl:choose>              <xsl:when test="paygate/errorcode='0015'">              <xsl:value-of select="/paygate/language/ErrorCodeDescription/Description1"/>              <!--The input of the credit card number was not correct-->              </xsl:when>        </xsl:choose> </xsl:if>

2.2.7 JavaScript

If JavaScript functions are desired, you must implement them in your template.

<script id=“clientEventHandlersJS“ language=“JavaScript“>

if (document.SSLForm.cardNumber.value.length> 19)

{

alert(„<xsl:value-of select=“/paygate/language/strJavaScript1“/>“);

       document.SSLForm.cardNumber.focus();

}

...

</script>

Please do not use any external link to your JavaScript.

2.2.8 Link to Visa Secure and MasterCard Secure Code

Visa and MasterCard regulations require that your pay page displays the Visa Secure and SecureCode logo. Please link the Verified logo to https://www.computop-paygate.com/vbv.aspx and the SecureCode logo to https://brand.mastercard.com/brandcenter/mastercard-brand-mark/downloads.html.

2.2.9 Programming and testing the form

First design a HTML page with the layout for your payment page and initially save it for testing with the file extension .htm or .html. Open this file in the browser. Next, save this as an xsl file.

<?xml version="1.0" encoding="windows-1252"?>

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:output method="html" encoding="UTF-8"/>

<xsl:template match="/">

<html>

       <head>

             <title>PaySSL Template</title>

             <script>Your JavaScript</script>

       </head>

       <body>

       <form action="https://www.computop-paygate.com/payinterim.aspx" method="POST">
       Your form with hidden fields and xsl-tags

       </form>

       </body>

</html>

</xsl:template>

In order to read the texts from the XML file, first of all create your tags in the desired language sections with the texts:

       <language name="de">

             <strCCNumber>credit card number</strCCNumber>

       </language>

Subsequently, replace the text in the HTML by a reference to the respective section in the XML file:

<xsl:value-of select="/paygate/language/strCCNumber"/>

In order to test your template, we request that you integrate the following lines in your XML file only for the test (before sending it to First Cash Solution) and afterwards to call up the XML file in a browser. If no error is displayed you can send your template and the image folder in a Zip file to First Cash Solution’s Support with a request to check and install it.

<?xml version="1.0" encoding="windows-1252"?>

<?xml-stylesheet type="text/xsl" href="templatename.xsl"?>

<paygate>

       <languages>please omit for your layout tests

             <language name="de">

             </language>

             <language name="en">

             </language>

       <languages>please omit for your layout tests

</paygate>

In order to get an overview of the versions, please include the date and version number in the name of your Zip file.

As with the credit card form, it is now also possible to design your own XSLT templates for the SEPA direct debit form. In exactly the same way as with the credit card form, this is controlled via the ‘Template’ parameter. This can be called via the following URL:

The files must use the following naming convention:

XSL template: MerchantID_PaySDD.xsl

XML text file: MerchantID_PaySDD.xml

Sub-folder for images: Templates/imagesMerchantID

Notice: A Corporate Paypage offers you much more extended functions like for example a preconfiguration of card data which are not explained in detail here. For questions about extended functions please consult the 1cs Online Payment System Support.

3 Server-2-Server Sequence Diagramm

3.1 Card processing – Server-2-Server integration

A 3-D Secure 2.0 payment sequence may comprise the following distinct activities:

• Versioning: Request ACS and DS Protocol Version(s) that correspond to card account range as well as an optional 3-D Secure Method URL
• 3-D Secure Method:Connect the cardholder browser to the issuer ACS to obtain additional browser data
• Authentication: Submit authentication request to the issuer ACS
• Challenge: Challenge the card holder if mandated
• Authorization:Authorize the authenticated transaction with the acquirer
   

3.2 Server-2-Server Sequence Diagram

Please note that the the communication between client and Access Control Server (ACS) is implemented through iframes. Thus, responses arrive in an HTML subdocument and you may establish correspondent event listeners in your root document.

Alternatively you could solely rely on asynchronous notifications delivered to your backend. In those cases you may have to consider methods such as long polling, SSE or websockets to update the client.

3.3 Payment Initiation

The initial request to the 1cs Online Payment System 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.

3.4 Call of interface: general parameters

Notice: For credit card payments with 3D 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 TLS credit card payment via a Server-to-Server connection, call the following URL:

3.4.1 Request Elements

Notice: For security reasons, the 1cs Online Payment System 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”

3.4.2 Response Elements (authentication)

The following table describes the result parameters with which the 1cs online payment system responds to your system

be prepared to receive additional parameters at any time and do not check the order of parameters

the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive

3.4.3 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.5 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.5.1 3-D Secure Method: threeDSMethodURL

Please note that the threeDSMethodURL will be populated by the 1cs Online Payment System 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 the 1cs Online Payment System in case of a mandated challenge or a frictionless flow.

3.5.2 3-D Secure Method: No issuer threeDSMethodURL

3.5.3 -D Secure Method Form Post

<form name=”frm” method=”POST” action=”Rendering URL”>

    <input type=”hidden” name=”threeDSMethodData” value=”eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNhYzdjYWE3LWFhNDItMjY2My03OTFiLTJhYzA1YTU0MmM0YSIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIn0″>

</form>

The ACS will interact with the Cardholder browser via the HTML iframe and then store the applicable values with the 3-D Secure Server Transaction ID for use when the subsequent authentication message is received containing the same 3-D Secure Server Transaction ID.

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.

3.5.4 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.5.5 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 the 1cs Online Payment System 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 the 1cs OPS.

3.6 Authentication

If 3-D Secure Method is supported by the issuer ACS and was invoked by the merchant 1cs OPS 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  The 1cs Online Payment system 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,  the 1cs OPS will automatically continue and respond to the cardholder browser once the authorization completed.

3.6.1 Cardholder Challenge: Browser Response

3.6.2 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”

}

3.6.3 Authentication Notification

The data elements of the authentication notification are listed in the table below.

3.6.4 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>

You may use the operations 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>

Once the cardholder challenge is completed, was cancelled or timed out the ACS will instruct the browser to post the results to the notfication URL as specified in the challenge request and to send a Result Request (RReq) via the Directory Server to the 3-D Secure Server.

Please note that the notification URL submited in the challenge request points to the 1cs Online Payment System and must not be changed.

3.7 Authorization

After successful cardholder authentication or proof of attempted authentication/verification is provided the 1cs Online Payment System 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 the 1cs Online Payment System will not continue with an authorization request.

In both cases the 1cs OPS will deliver a notification with the authentication result to the merchant specified URLNotify with the data elements as listed in the table below.

3.7.1 Payment Notification

3.7.2 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

}

Merchants are supposed to forward these data elements to their server for decryption and mapping agianst the payment notification. Based on the payment results the merchant server may deliver an appropriate response to the cardholder browser (e.g. success page).

Decrypted Data

Sample decrypted Data

MID=YourMID&PayID=PayIDassignedbyPlatform&TransID=YourTransID

4 Capture / Credit / Reversal

4.1 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:

Notice: Please observe the reservation / authorisation deadlines of your acquirer (see General Terms and Conditions) so that you, as the merchant, ensure that the debits are submitted to our 1cs OPS within the correct period.

Notice: For security reasons, the 1cs Online Payment System 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 1cs online payment system responds to your system

• be prepared to receive additional parameters at any time and do not check the order of parameters

• the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive

Response parameters for captures of credit card payments

4.2 Credit with reference

Credits (refunds) are possible via a Server-to-Server connection. the 1cs Online Payment System permits credits which relate to a capture previously activated by the 1cs Online Payment System 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:

Notice: For security reasons, the 1cs Online Payment System 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 1cs online payment system responds to your system

be prepared to receive additional parameters at any time and do not check the order of parameters

the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive

Response parameters for credits of credit card payments

4.3 Credit without reference

The 1cs Online Payment System can carry out Credits which do not relate to a previous capture. In this case the credit must be transferred to the 1cs Online Payment System as a completely new payment transaction. Please contact the First Cash Solution Helpdesk for help in using the described additional functions.

Notice: Please note that credits without reference to a previous capture generate higher costs with your Acquiring Bank. If you are frequently unable to make reference to the capture you should agree this with your Acquiring Bank.

To carry out a Credit without a reference transaction via a Server-to-Server connection, please use the following URL:

Notice: For security reasons, the 1cs Online Payment System 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 without reference

The following table describes the result parameters with which the 1cs online payment system responds to your system

be prepared to receive additional parameters at any time and do not check the order of parameters

the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive

Response parameters for credits of credit card payments without reference

4.4 Reversal

A credit card authorization lowers the customer’s credit line. the 1cs Online Payment System can reverse an authorization so that it no longer block the limit any more. Use the following URL:

Notice:Reverse.aspx does not only reverse authorizations, but any LAST TRANSACTION STAGE!! If the last transaction was a capture, Reverse.aspx initiates the reverse, e.g. a credit. Therefore, the utmost caution is urged. Use is at your own risk. We recommend checking the transaction status with Inquire.aspx before using Reverse.aspx.

Notice: For security reasons, the 1cs Online Payment System 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 reversals of credit card payments

The following table describes the 1cs Online Payment System response parameters:

–  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

Response parameters for reversals of credit card payments

4.5 Reversal of an authorisation extension

A credit card authorisation is valid for only 7 to 30 days. In order to maintain your payment claim in the case of longer delivery times, the 1cs Online Payment System enables the automatic renewal of the authorisation. Renewal of the authorisation is also important for instalments or partial deliveries because the outstanding amount is invalid in the case of partial captures.

If you use authorisation renewal, the 1cs Online Payment System renews your authorisations until the payment has been captured fully. Amongst other things the customer’s card limit is reduced by the authorised amount. In order to restore the card limit again, for example because the order cannot be fully delivered, you need to specifically cancel the authorisation renewal with the following URL:

Notice: CancelAuth cancels only the recurrence of the authorisation. If you wish to unblock the customer’s card limit, please reverse the authorisation in accordance with the section above.

Notice: For security reasons, the 1cs Online Payment System 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 reversal of an authorisation extension

The following table describes the result parameters with which the 1cs online payment system responds to your system

• be prepared to receive additional parameters at any time and do not check the order of parameters

• the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive

Result parameters for reversals of an authorisation extension

4.6 Credit card payment via POS terminals

To make a credit card payment via a POS terminal (POS: Point of Sale), send the payment request to the following URL:

Notice: For security reasons, the 1cs Online Payment System 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 POS terminals

The following table describes the result parameters with which the 1cs online payment system responds to your system

• be prepared to receive additional parameters at any time and do not check the order of parameters

• the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive

Response parameters for credit card payments via POS terminals

4.7 Reversal of POS credit card payments

To reverse the capture of a credit card payment via a stationary terminal, please use the following URL:

The following table describes the result parameters with which the 1cs online payment system responds to your system

• be prepared to receive additional parameters at any time and do not check the order of parameters

• the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive

Parameters for reversal of credit card payments via POS terminals

The following table describes the result parameters with which the 1cs online payment system responds to your system

be prepared to receive additional parameters at any time and do not check the order of parameters

the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive

Response parameters for reversal of credit card payments via POS terminals

5 PayNow

5.1 Silent Mode for credit cards with SSL and 3D Secure method

PayNow links the benefits of the 1cs Online Payment System forms and Server-to-Server connections: AS opposed to the the 1cs Online Payment System form, where the form is loaded from the the 1cs Online Payment System server by calling payssl.aspx, the PayNow form has to be provided by the merchant’s system. The form uses the same parameters as described here below.

In contrast to the the 1cs Online Payment System form, the parameters are not forwarded as URL parameters as is the case when calling the payssl.aspx, but as form input parameters. By the way for calling the PayNow.aspx the same parameters can be used as for PaySSL.aspx.

The credit card data must be transmitted to paynow.aspx with the following parameters:

PayNow parameters for 3-D Secure method

After the customer has entered his credit card data, the payment data is forwarded to the PayNow page, where the further payment processing takes place via 3D-Secure. The form details must be directly forwarded to the PayNow page and may not be transmitted to the merchant’s system! Also, no PCI-relevant data may be transmitted to the PayNow page as additional input parameters!

6 Batch processing via the interface

Basic information about using Batch files and about their structure can be found in the Batch Manager manual. Within batch processing not alle functions are available which are usually available for the online interface.

6.1 Batch calls and answers

This section describes the parameters which must be transferred within the data set (Record) for executing a credit card payment and which information can be found within the response file about the payment status.

Notice: Please observe the reservation / authorisation deadlines of your acquirer (see General Terms and Conditions) so that you, as the merchant, ensure that the debits are submitted to our 1cs Online Payment System within the correct period.

Notice: Within Batch process not all functions of online interface are available.

For Batch calls there must be considered batch versions, from which optional parameters depend. All version designations starting with „2.“ pertain calls for a group of enterprises. That means within a batch file for a particular MerchantID can be transferred transactions for other merchants with a separate Sub-MID.

For the connections ECPCC, GMO, Kalixa and SafeCharge the possible actions are limited to Capture, Credit and Reverse.

Following table gives an overview of all batch versions that are possible for a specific action and their specialities:

Description of the possible batch versions

The structure for a credit card payment within a Batch file to be submitted is the following:

HEAD,<MerchantID>,<Date>,<Version>

CC,Authorize,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>, [<CCCVC>,]<CCExpiry>,<OrderDesc>[,<textfeld1>,<textfeld2>,<RTF>,<approvalcode>,<cardholder>,<Zone>,<transactionID>,<schemeReferenceID>]

CC,Capture,<Amount>,<Currency>,<TransID>,(<RefNr>),<PayID>,[<FinishAuth,<textfeld1>,<textfeld2>,<approvalcode>]

CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>, [<CCCVC>,]<CCExpiry>,<OrderDesc>[,<textfeld1>,<textfeld2>,<RTF>,<approvalcode>,<cardholder>,<Zone>,<transactionID>,<schemeReferenceID>]]

CC,Credit,<Amount>,<Currency>,<TransID>,(<RefNr>),<PayID>[,<FinishAuth>,<textfeld1>,<textfeld2>]

CC,CreditEx,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>, [<CCCVC>,]<CCExpiry>,<OrderDesc>[,<textfeld1>,<textfeld2>]

CC,Reverse,<Amount>,<Currency>,<TransID>,(<RefNr>),<PayID>

FOOT,<CountRecords>,<SumAmount>

Example for batch versions:

Version 1.2:

CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,<CCExpiry>,<OrderDesc>

CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,<CCExpiry>,<OrderDesc>,<textfeld1>,<textfeld2>,<RTF>,<cardholder>,<transactionID>,<schemeReferenceID>


Version 1.21:

CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,<CCExpiry>,<OrderDesc>,<textfeld1>,<textfeld2>,<RTF>,<approvalcode>,<cardholder>,<transactionID>,<schemeReferenceID>

Version 1.3:

CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,<CCCVC>,<CCExpiry>,<OrderDesc>,<textfeld1>,<textfeld2>,<transactionID>,<schemeReferenceID>

Version 1.5:

HEAD,[Master]MerchantID,Date,2.x

Type,Action,[Slave]MID,Amount,Currency,TransID,Data (depends on Action)

FOOT,CountRecords,SumAmount

Example for Master MID Funktion:

HEAD,[Master]MerchantID,Date,2.x
Type,Action,[Slave]MID,Amount,Currency,TransID,Data (depends on Action)
FOOT,CountRecords,SumAmount

The following table describes the individual fields and values used within the data set (record) in the batch file:

Description of fields within the record for Batch files

The record area within the response file for Batch transactions looks as follows:

HEAD,<MerchantID>,<Date>,<Version>

CC,Authorize,<Amount>,<Currency>,<TransID>,(<RefNr>),<PayID>,<CCBrand>,<CCNr|PCNr>,[<CCCVC>,]<CCExpiry>,<OrderDesc>[,<textfeld1>,<textfeld2>,<RTF>,<approvalcode>,<cardholder>,<Zone>,<transactionID>,<schemeReferenceID>],<Status>,<Code>

CC,Capture,<Amount>,<Currency>,<TransID>,(<RefNr>),<PayID>[<textfeld1>,<textfeld2>,<approvalcode>],<Status>,<Code>

CC,AuthSplit,<Amount>,<Currency>,<TransID>,(<RefNr>),<PayID>,FAILED,<Code>,<Description>,[<PCNr>]

CC,Renewal,<Amount>,<Currency>,<TransID>,(<RefNr>),<PayID>,FAILED,<Code>,<Description>,[<PCNr>]

CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<PayID>,<CCBrand>,<CCNr|PCNr>,[<CCCVC>,]<CCExpiry>,<OrderDesc>[,<textfeld1>,<textfeld2>,<RTF>,<approvalcode>,<cardholder>,<Zone>,<transactionID>,<schemeReferenceID>],<Status>,<Code>

CC,Credit,<Amount>,<Currency>,<TransID>,(<RefNr>),<PayID>[,<FinishAuth>,<textfeld1>,<textfeld2>],<Status>,<Code>

CC,CreditEx,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,[<CCCVC>,]<CCExpiry>,<OrderDesc>[,<textfeld1>,<textfeld2>],<Status>,<Code>

CC,Reverse,<Amount>,<Currency>,<TransID>,(<RefNr>),<PayID>,<Status>,<Code>

FOOT,<CountRecords>,<SumAmount>

Example for batch versions:

Version 1.2:

CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,<CCExpiry>,<OrderDesc>,<Status>,<Code>

CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,<CCExpiry>,<OrderDesc>,<textfeld1>,<textfeld2>,<RTF>,<cardholder>,<transactionID>,<schemeReferenceID>,<Status>,<Code>

Version 1.21:

CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,<CCExpiry>,<OrderDesc>,<textfeld1>,<textfeld2>,<RTF>,<approvalcode>,<cardholder>,<transactionID>,<schemeReferenceID>,<Status>,<Code>   Version 1.3: CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,<CCCVC>,<CCExpiry>,<OrderDesc>,<textfeld1>,<textfeld2>,<transactionID>,<schemeReferenceID>,<Status>,<Code>   Version 1.5: CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,<CCCVC>,<CCExpiry>,<OrderDesc>,<Zone>,<Status>,<Code>

The following table describes the response parameters which the Batch Manager saves in the Record area for each transaction (standard parameters not explained here, such as <TransID> or <RefNR> and request parameters are returned unchanged and correspond to the call as specified before):

Description of result parameters within the record for Batch files

6.2 Cancel authorisation renewals

With a credit card authorisation you get the right to claim a payment. However an authorisation lasts only 30 days which is a problem if you capture a partial amount, for example as part payment for several partial shipments. In order to reproduce your payment request the 1cs Online Payment System can repeat an expired authorisation automatically.

If an order cannot be delivered or has been cancelled by the customer, it is very important that the automatic authorisations stop. Your customer’s card limit will be otherwise reduced permanently because the the 1cs Online Payment System continues to charge your customer’s card.

Under normal circumstances the the 1cs Online Payment System stops the automatic authorisation renewal when the authorised amount has been captured in full. In Batch version 1.4 you can also stop the authorisation renewal manually by changing the payment status. To perform this you submit a capture in your batch file whose amount is under the admissible limit. Since the 1cs Online Payment System refuses credit card captures below €1.00, the payment status changes to FAILED in the case of lesser amounts. the 1cs Online Payment System therefore renews this authorisation no further. A corresponding capture entry of €0.05 is shown for example as follows:

CC,Capture,5,EUR,BestNr.0815,Rg.Nr.5180,a86dga4310d24453acd6f8a3112a769,y

Since the amount of 5 cents lies below the minimum amount of €1.00, the 1cs Online Payment System refuses the capture with the error message MinValue. The payment status changes to FAILED and the authorisation renewal is stopped.

7 CAPN: American Express

7.1 Introduction

7.1.1 Acquirers and connection

The 1cs Online Payment System supports many different credit card connections to various acquirers / processors with different protocols.

You can find an overview of all different credit card interfaces here: Payments by Credit Card.

Additional features (e.g. AVS (Address Verification Service), refund, 3-D Secure, …) may depend on the specific integration and acquirer.

7.1.2 Integration with the 1cs Online Payment System

In general we offer two different ways of integration:

The documentation below is therefore always devided into two sections:

• integration via payment page (payment form)
  • with common parameters to integrate the 1cs Online Payment System payment form
  • with parameters to customize the payment form
  • with specific parameters for the desired acquirer / processor
• integration via Server-2-Server (direct) integration
  • with common parameters to integrate the 1cs OPS payment form
  • with specific parameters for the desired acquirer / processor

7.1.3 Implementation of 3-D Secure (2.x)

Common notes to 3-D Secure

3-D Secure is a process that authenticates the card holder to ensure that the consumer using the credit card data really is the card holder.

3-D Secure shall provide abuse of credit card data – specially in ecommerce environment.

3-D Secure 1.x has been implemented and asks the card holder typically for a password with each card usage.

3-D Secure 2.x has been implemented to:

• enable strong customer authentication (SCA) by authenticate the card holder with 2 independent factors of these 3 factors:
  • something the card holder knows, e.g. a password
  • something the card holder owns, e.g. a device (like phone to receive a token via SMS or using other OTP, token generator, …)
  • something the card holder is, e.g. biometrics (like finger print, face-id, …)
• enable seemless authentication where the consumer is not authenticated and not asked to authenticate himself.

3-D Secure with the 1cs Online Payment System

Prepare yourself / your integration to be 3-D Secure 2.x ready – here a short overview with some technical details.

7.2 Specific parameters for CAPN: American Express

Besides the general parameters described below for the credit card connection, CAPN requires the following additional parameters. An authorisation with 3-D Secure is possible.

Notice: For security reasons, the 1cs OPS  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 the credit card payments

The following table describes the result parameters with which the 1cs OPS 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. MerchantId, RefNr) should not be checked case-sentive

Additional response parameters for credit card payments