The European Banking Authority (EBA) mandated that all payer who access their payment account online and initiate electronic payment transactions through a remote channel must be strongly authenticated (aka Strong Customer Authentication (SCA)) commencing September 14, 2019. The card organizations seized this opportunity to overhaul the established 3D-Secure protocol for cardholder authentication and to address several issues that curbed adoption in the market.

1.1.2 3DS 2.0

Previously, internet merchants had the choice to either present a cardholder challenge (e.g. TAN / password) or to give 3DS a pass entirely. Some adopted a dynamic approach based on PSP or own risk assessment, but many merchants valued a frictionless checkout and high conversion rates more than the potential benefits of a liability shift. The card organization’s overall strategy for 3DS 2.0 is to reduce friction through an improved cardholder experience (device awareness) and to leverage exemptions from SCA based on robust transaction risk analysis (TRA) with the ultimate goal of delivering optimal authorization performance and conversion rates. Thus, TRA is key to delivering frictionless payment experiences for low-risk remote transactions. Therefore the 3DS 2.0 protocol introduced a plethora of additional data points that can be transferred to the issuer to aid transaction risk analysis and to apply excemptions from SCA.

SCA will be required when:

The transaction is not out of scope of the PSD2 RTS
No PSD2 SCA exemption applies for a payment transaction
Adding a card to a Merchant’s file (card-on-file)
Starting a recurring payment arrangement for fixed and variable amounts, including setting the initial mandate for Merchant-Initiated Transactions
Changing a recurring payment agreement for a higher amount (premium offering for example)
Setup of white-listing (or viewing/amending white-lists)
Binding a device to a Cardholder

1.1.3 Liability Shift

As a rule of thumb, when cardholder authentication was performed through 3-D Secure, merchants are typically protected against e-commerce fraud-related disputes and liabiliaty shifts from the merchant / acquirer to the issuer. There are exceptions to merchant dispute protection though. In the context of 3DS 2.0 merchants are regularily not protected if granted excemptions according to PSD2 RTS were actively requested by merchant / acquirer.

The following diagram depicts options and liabilities under PSD2 RTS requirements according to MasterCard.

1.1.4 3D Secure 2.0 and GDPR Compliance

Cardholders must be provided with detailed information about how their data is collected, used and processed. This can be ensured via a Privacy Notice including at a minimum the types of data being processed, the purposes of their processing, data uses, etc. Card organizations and Issuers will not use EMV 3DS data for other purposes than fraud prevention and authentication. It excludes the usage of personal data for other purposes, such as sales, marketing and data mining (other than fraud prevention as purpose) activities.

1.1.5 PSD2 SCA Exemptions and Exclusions

There are some important excemptions to SCA according to the regulatory technical standards (RTS) that may apply in various conditions which are depicted in the following digram.

1.2 The 1cs Online Payment System

1.2.1 Authentication Options

An acquirer may be allowed to not apply SCA due to to low fraud rates and TRA. For these excemptions there are various processing options available as depecited in the diagram below.

As a standard, First Cash Solution will submit (where supported) applicable excemptions through the EMV 3DS authentication flow to the issuer to achieve best possible authorization approval rates.

EBA-Op-2018-04, Paragraph 47 – Clarification on PSP (Acquirer Fraud Rates)

The fraud rate as defined in Annex A of the RTS is calculated for all credit transfer transactions and all card payment transactions and cannot be defined per individual payee (e.g. merchant) or per channel (whether app or web interface). The fraud rate that determines whether or not a PSP qualifies for the SCA exemption cannot be calculated for specific merchants only, i.e. where the payer wants to make a payment to a specific merchant and this specific merchant has a fraud risk that is below the threshold. While the payee’s PSP (acquirer) may contractually agree to ‘outsource’ its transaction risk analysis monitoring to a given merchant, or allow only certain predefined merchants to benefit from that PSP’s exemption (based on a contractually agreed low fraud rate), the fraud rate making a given PSP eligible for an exemption under Article 18 would still need to be calculated on the basis of the payee PSP’s executed or acquired transactions, rather than on the merchant’s transactions.

1.2.2 Message Version 2

To handle the amount of additional non-payment data and to maintain downward compatibility as much as possible First Cash Solution decided to version its the 1cs Online Payment System card interface via the additional data element MsgVer. The upgraded API is still based on key-value pairs but relies heavly on Base64 encoded JSON objects to aid readibility and client-side scripting.

Merchants will still be able to use our classic interface for requests even with 3DS 2.0 but there are some limitations:

Many additional data points for issuer risk analysis are not available and thus, the frictionless ratio might be lower
API responses and notifications do include new JSON objects to cater for 3DS 2.0 protocol specifications and require modification of existing merchant integrations

For these reasons it is highly recomended to upgrade to version 2.

1.2.3 Soft decline handling

In case a transaction is missing SCA, issuers might respond with so-called soft declines. This means that the transaction authorization request is declined by the issuer, however, the same transaction can be initiated again. The main reason for soft declines emerging in the context of 3D Secure is that issuers are not accepting SCA exemptions requested by the merchant when such is sent directly to authorization or when the merchant requests payment without authentication being carried out beforehand. The best practice is to restart the payment including 3DS. With Automated Soft Decline Handling feature, configuration based, the 1cs Online Payment System (1cs OPS) will react to the soft decline response by automatically restarting the payment forcing SCA. The 1cs OPS will then automatically create a new payment on behalf of the merchant and include 3DS flow.

IMPORTANT:

From a user’s point of view, customers will not notice any difference and will not need to re-enter their credit card data. The whole process is managed by the First Cash Solution GmbH.
Please note that this solution is not available for server-to-server integrations, as 1cs OPS does not have the client (browser) in control to start the 3-D Secure flow. For server-to-server integration, the merchant is responsible to re-trigger the payment with 3-D Secure flow and most important forcing the SCA challenge through the available parameter JSON threeDSPolicy (challengePreference = mandateChallenge).

1.2.3.1 Whitelisting of trusted beneficiaries

A cardholder might opt to add a merchant to a list of trusted benficiaries maintained at the issuer to excempt this particular merchant from SCA with future payments. This will usually occur during a cardholder challenge but cardholder’s might also be able to manage a list of trusted beneficiaries through their banking app for instance.

Merchants may benefit from a whitelist excemption if requested and if a cardholder challenge is not required otherwise.

Please note that whitelisting is available with 3DS version 2.2 and higher. Currently issuer most support 3DS 2.1.

Notice: Please note that whitelisting is available with 3-D Secure version 2.2 and higher. Currently issuer most support 3-D Secure 2.1.

1.2.3.2 Recurring transactions

Recurring transactions are a series of transactions processed following an agreement between a cardholder and a merchant where the cardholder purchases goods or services over a period of time and through a number of separate transactions with the same amount. The initial transaction must be authenticated (i.e. cardholder initiated transaction (CIT)). Subsequent recurring payments are out of scope of RTS SCA since they are regularily merchant initiated (i.e. without customer beeing in session).

1.2.3.3 Low-value transactions

Issuers may exempt transactions from SCA provided that the following conditions are met:

the payment amount does not exceed EUR 30,
the cumulative amount of previous payment transactions without SCA does not exceed EUR 100,
the number of previous payment transactions without SCA does not exceed five consecutive payment transactions.

Please note that low-vale exemptions must be requested to be considered for a frictionless authentication flow.

1.2.3.4 Transaction risk analysis

Acquirers and issuers are allowed not to apply SCA provided the overall fraud rate is not higher than the reference fraud rate for the exemption threshold value (ETV) specified in the table below and where the risk-based assesment of each individual transaction can be considered as low risk.

ETV	Card-based payments
EUR 500	1 bps
EUR 250	6 bps
EUR 100	13 bps

1.2.3.5 One-leg out transactions

One-leg out transactions are such transactions where either the payer’s payment service provider or the payee’s payment service provider are located outside the European Union.

Payment service provider in the context of a card based transaction and in the spirit of the PSD2 are regularily acquirer and issuer.

Thus, neither the nationality of the cardholder nor the merchant’s business location are relevant for the assessment wether a transaction is out of scope due to the ‘one-leg out’ rule.

2 Integration Methods

2.1 Card processing – Credit Card Form

When requesting card payments via First Cash Solution 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 additial information and different solution approaches.

When requesting card payments via 1cs OPS hosted forms the complexity of 3-D Secure is completely removed from the merchant implementation.

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

2.1.2 Payment Request

To retrieve a First Cash Solution 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, 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:

Key	Format	Condition	Description
MerchantID	ans..30	M	Merchant identifier assigned by First Cash Solution. Additionally this parameter has to be passed in plain language too.
MsgVer	ans..5	M	Message version. Values accepted · 2.0 · With 3-D Secure 2.x a lot of additional data were required (e.g. browser-information, billing/shipping-address, account-info, …) to improve authentication processing. To handle these information the JSON-objects have been put in place to handle such data. To indicate that these data are used the MsgVer has been implemented.
ReqID	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,1cs Online Payment System 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 1cs Online Payment System 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 the 1cs Online Payment System 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 1cs Online Payment System.
TransID	ans..64	M	Transaction identifier supplied by the merchant. Shall be unique for each payment.
RefNr		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. Details on supported format can be found below in payment specific section. Only ASCII characters allowed, special characters (“Umlaute”, diacritics) are not allowed and must be replaced by their ASCII-representation (e.g. ü → ue, é → e, …).
MAC	an64	M	Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify)
Amount	n..10	M	Amount in the smallest currency unit (e.g. EUR Cent). Please contact the 1cs Online Payment System support, if you want to capture amounts <100 (smallest currency unit).
Currency	a3	M	ISO 4217 three-letter currency code, e.g. EUR, USD, GBP. Please find an overview here: Currency tabl e
Capture	ans..6	O	Determines the type and time of capture. Values accepted: · AUTO = completion immediately after authorisation (default value) · MANUAL = Capturing made by the merchant. Capture is normally initiated at time of delivery. · NUMBER = Delay in hours until the capture (whole number; 1 to 696).
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
billingDescriptor	ans..22	O	A descriptor to be printed on a cardholder’s statement. Please also refer to the additional comments made elswhere for more information about rules and regulations.
OrderDesc	ans..768	O	Order description.
AccVerify	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 · Yes
threeDSPolicy	JSON	O	Object specifying authentication policies and excemption handling strategies.
priorAuthenticationInfo	JSON	O	Prior Transaction Authentication Information contains optional information about a 3DS cardholder authentication that occurred prior to the current transaction.
accountInfo	JSON	O	The account information contains optional information about the customer account with the merchant.
billToCustomer	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.
shipToCustomer	JSON	C	The customer that the goods and / or services are sent to. Required if different from billToCustomer.
billingAddress	JSON	C	Billing address. Required for EMV 3DS (if available) unless market or regional mandate restricts sending this information.
shippingAddress	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	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.
merchantRiskIndicator	JSON	O	The Merchant Risk Indicator contains optional information about the specific purchase by the customer. If no shippingAddress is present it is strongly recommended to populate the shippingAddressIndicator property with an appropriate value such as shipToBillingAddress, digitalGoods or noShipment.
subMerchantPF	JSON	O	Object specifying SubMerchant (Payment Facilitator) details. Only supported by SafeCharge
URLSuccess	ans..256	M	Complete URL which calls up 1cs Online payment system 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 1cs OPS and shop, please use the parameter UserData. Common notes: We recommend to use parameter “response=encrypt” to get an encrypted response by 1cs Online Payment System However, fraudster may just copy the encrypted DATA-element which are sent to URLFailure and send the DATA to URLSuccess. Therefore ensure to check the “code”-value which indicates success/failure of the action. Only a result of “code=00000000” should be considered successful.
URLFailure	ans..256	M	Complete URL which calls up 1cs Online payment system 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 1cs OPS and shop, please use the parameter UserData. Common notes: We recommend to use parameter “response=encrypt” to get an encrypted response by 1cs Online Payment System However, fraudster may just copy the encrypted DATA-element which are sent to URLFailure and send the DATA to URLSuccess/URLFailure. Therefore ensure to check the “code”-value which indicates success/failure of the action. Only a result of “code=00000000” should be considered successful.
URLBack	ans..256	M	Complete URL which 1cs OPS calls in case that Cancel is clicked by the customer. The parameter “URLBack” can be sent either as plain parameter (unencrypted) (compatibility mode) or be part of encrypted payment request parameters (preferred mode) In order to exchange values between 1cs OPS and shop you may use something like this: URLBack=https://your.shop.com/back.php?param1%3Dvalue1%26param2%3Dvalue3%26status%3Dcancelled When user cancels payment this URL is called exactly like this and you may use URL Decode to extract parameter and values.
Response	a7	O	Status response sent by the 1cs OPS to URLSuccess and URLFailure, should be encrypted. For this purpose, transmit Response=encrypt parameter.
URLNotify	ans..256	M	Complete URL which 1cs Online Payment system 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. Common notes: We recommend to use parameter “response=encrypt” to get an encrypted response by 1cs OPS However, fraudster may just copy the encrypted DATA-element which are sent to URLFailure and send the DATA to URLSuccess/URLNotify. Therefore ensure to check the “code”-value which indicates success/failure of the action. Only a result of “code=00000000” should be considered successful.
userData	ans..1024	O	If specified at request, 1cs Online Payment System forwards the parameter with the payment result to the shop.
Custom	ans..1024	O	“Custom”-parameter is added to the request data before encryption and is part of encrypted “Data” in 1cs Online Payment System request. By this they are protected against manipulation by a consumer. The Custom-value is added to the 1cs Online Payment System 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	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 1cs Online Payment System and therefore protected against manipulation.
Expiration Time	ans..19	O	timestamp for the end time of the transaction processing, specified in UTC. Format: YYYY-MM-ddTHH:mm:ss

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 cardholder to.

Cardholder authentication and payment authorization will take place once 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 the 1cs Online Payment System 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 resepctively 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 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.

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

Key	Format	Condition	Description
MID	ans..30	M	Merchant identifier assigned by First Cash Solution.
MsgVer	ans..5	M	Message version. Accepted values: · 2.0 · With 3-D Secure 2.x a lot of additional data were required (e.g. browser-information, billing/shipping-address, account-info, …) to improve authentication processing. To handle these information the JSON-objects have been put in place to handle such data. To indicate that these data are used the MsgVer has been implemented.
PayID	ans32	M	ID assigned by First Cash Solution for the payment, e.g. for referencing in batch files as well as for capture or credit request.
XID	ans64	M	ID for all single transactions (authorisation, capture, credit note) for one payment assigned by 1cs Online Payment System
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 First Cash Solution merchants can continue to use the SchemeReferenceIDs for subscription plans that were created while using another PSP environment / 1cs OPS MerchantID / Acquirer ContractID / Acquirer.
RefNr.		O	Reference number taken from request
Status	a..20	M	Staus of the transaction. Values accepted: · Authorized · OK (Sale) · FAILED In case of Authentication-only the Status will be either OK or FAILED.
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 the 1cs Online Payment System response code.
card	JSON	M	Card data.
ipInfo	JSON	O	Object containing IP information.
threeDSData	JSON	M	Authentication data.
resultsResponse	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.
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 1cs Online Payment System 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 1cs Online Payment System request. By this they are protected against manipulation by a consumer. The Custom-value is added to the 1cs Online Payment System 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.
userData	ans..1024	O	If specified at request, the 1cs Online Payment System forwards the parameter with the payment result to the shop.
MAC	an64	M	Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify)

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

Key	Format	CND	Description
MerchantID	ans..30	M	MerchantID, assigned by the 1cs Online Payment System. Additionally this parameter has to be passed in plain language too.
PayID	an32	M	ID assigned by the 1cs Online Payment System for the payment, e.g. for referencing in batch files as well as for capture or credit request.
TransID	ans..64	M	TransactionID provided by you which should be unique for each payment
Amount	n..10	M	Amount in the smallest currency unit (e.g. EUR Cent). Please contact the 1cs Online Payment System Helpdesk, if you want to capture amounts <100 (smallest currency unit).
Currency	a3	M	Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: Currency table
OrderDesc	ans..768	O	Description of purchased goods, unit prices etc.
MAC	an64	M	Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify)
Capture	an..6	OM	Determines the type and time of capture. Capture Mode: AUTO: Capturing immediately after authorisatoin (default value) MANUAL: Capturing made by the merchant. Capture is normally initiated at time of delivery. <Number>: Delay in hours until the capture (whole number; 1 to 696).

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

Key	Format	CND	Description
MID	ans..30	M	MerchantID, assigned by the 1cs Online Payment System
PayID	an32	M	ID assigned by the 1cs Online Payment System 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 1cs Online Payment System
Code	n8	M	Error code according to 1cs OPS Response Codes (A4 Error codes)
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	ans..64	M	TransactionID provided by you which should be unique for each payment
Status	a..50	M	AUTHORIZED or FAILED
RefNr		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 1cs OPS settlement file (CTSF) we cannot add the additional payment data. Details on supported format can be found below in payment specific section. Only ASCII characters allowed, special characters (“Umlaute”, diacritics) are not allowed and must be replaced by their ASCII-representation (e.g. ü → ue, é → e, …).

2.1.5 Extended Sequence Diagram

2.2 Server-2-Server Integration EN

2.2.1 Card processing – Server-2-Server integration

A 3DS 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 3DS 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 carholder if mandated
Authorization
- Authorize the authenticated transaction with the acquirer

2.2.2 Server-2-Server Diagram

Notice: Please note that 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.

2.2.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.

2.2.4 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, 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.

Key	Format	Condition	Description
MerchantID	ans..30	M	Merchant identifier assigned by First Cash Solution. Additionally this parameter has to be passed in plain language too.
MsgVer	ans..5	M	1cs Online Payment System Message version. Valid values: Values accepted: · Value: 2.0 · Description: With 3-D Secure 2.x a lot of additional data were required (e.g. browser-information, billing/shipping-address, account-info, …) to improve authentication processing. To handle these information the JSON-objects have been put in place to handle such data. To indicate that these data are used the MsgVer has been implemented.
TransID	ans..64	M	TransactionID provided by you which should be unique for each payment
ReqID	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, 1cs Online Payment System 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 1cs Online Payment System 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 1cs Online Payment System 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 1cs Online Payment System.
RefNr		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 1cs Online Payment System settlement file (CTSF) we cannot add the additional payment data. Details on supported format can be found below in payment specific section. Only ASCII characters allowed, special characters (“Umlaute”, diacritics) are not allowed and must be replaced by their ASCII-representation (e.g. ü → ue, é → e, …).
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 1cs OPS merchants can continue to use the SchemeReferenceIDs for subscription plans that were created while using another PSP environment / 1cs OPS MerchantID / Acquirer ContractID / Acquirer.
industrySpecificTxType	ans..20	C	This parameter is required whenever an industry specific transaction is processed according to the card brands MIT (Merchant Initiated Transactions) Framework. Only supported with Omnipay and GICC. Supported with CB2A for Reauthorization, only. Values accepted: – Resubmission: A merchant performs a re-submission in cases where it requested an authorization, but received a decline due to insufficient funds; however, the goods or services were already delivered to the cardholder. Merchants in such scenarios can resubmit the request to recover outstanding debt from cardholders. – Reauthorization: A merchant initiates a re-authorization when the completion or fulfillment of the original order or service extends beyond the authorization validity limit set by Visa. There are two common re-authorization scenarios: • *Split or delayed shipments* at eCommerce retailers. A split shipment occurs when not all the goods ordered are available for shipment at the time of purchase. If the fulfillment of the goods takes place after the authorization validity limit set by Visa, eCommerce merchants perform a separate authorization to ensure that consumer funds are available. • Extended stay hotels, car rentals, and cruise lines. A re-authorization is used for stays, voyages, and/or rentals that extend beyond the authorization validity period set by Visa. – DelayedCharges: Delayed charges are performed to process a supplemental account charge after original services have been rendered and respective payment has been processed. – NoShow: Cardholders can use their Visa cards to make a guaranteed reservation with certain merchant segments. A guaranteed reservation ensures that the reservation will be honored and allows a merchant to perform a No Show transaction to charge the cardholder a penalty according to the merchant’s cancellation policy. Note: For merchants that accept token-based payment credentials to guarantee a reservation, it is necessary to perform a CIT (Account Verification Service) at the time of reservation to be able perform a No Show transaction later. Note: It is always submitted in conjunction with the “schemeReferenceID” parameter. Please contact support@1cs.de for the supported Acquirer and card brands.
Amount	n..10	M	Amount in the smallest currency unit (e.g. EUR Cent). Please contact then support@1cs.de, if you want to capture amounts <100 (smallest currency unit).
Currency	a3	M	Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: A1 Currency table EN
card	JSON	M	Card data.
Capture	ans..6	OM	Determines the type and time of capture. Values accepted: · AUTO = Capturing immediately after authorisation (default value). · MANUAL = Capturing made by the merchant. Capture is normally initiated at time of delivery. · <NUMBER> = Delay in hours until the capture (whole number; 1 to 696).
billingDescriptor	ans..22	O	A descriptor to be printed on a cardholder’s statement. Please also refer to the additional comments made elswhere for more information about rules and regulations.
OrderDesc	ans..768	O	Order description.
AccVerify	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: · Yes
threeDSPolicy	JSON	O	Object specifying authentication policies and excemption handling strategies.
threeDSData	JSON	C	Object detailing authentication data in case authentication was performed through a third party or by the merchant.
priorAuthenticationInfo	JSON	O	Prior Transaction Authentication Information contains optional information about a 3DS cardholder authentication that occurred prior to the current transaction.
browserInfo	JSON	C	Accurate browser information are needed to deliver an optimized user experience. Required for 3-D Secure 2.0 transactions.
accountInfo	JSON	O	The account information contains optional information about the customer account with the merchant. Optional for 3-D Secure 2.0 transactions.
billToCustomer	JSON	C	The customer that is getting billed for the goods and / or services. Required unless market or regional mandate restricts sending this information.
shipToCustomer	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.
billingAddress	JSON	C	Billing address. Required for 3-D Secure 2.0 (if available) unless market or regional mandate restricts sending this information.
shippingAddress	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	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.
merchantRiskIndicator	JSON	O	The Merchant Risk Indicator contains optional information about the specific purchase by the customer.
subMerchantPF	JSON	O	Object specifying SubMerchant (Payment Facilitator) details Only supported by SafeCharge
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	an..256	C	Complete URL which the 1cs Online Payment System 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. Common notes: We recommend to use parameter “response=encrypt” to get an encrypted response by 1cs OPS However, fraudster may just copy the encrypted DATA-element which are sent to URLFailure and send the DATA to URLSuccess/URLNotify. Therefore ensure to check the “code”-value which indicates success/failure of the action. Only a result of “code=00000000” should be considered successful.
userData	ans..1024	O	If specified at request, the 1cs Online Payment System forwards the parameter with the payment result to the shop.
MAC	an64	M	Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify)

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)

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

Key	Format	Condition	Description
MID	ans..30	M	Merchant identifier assigned by First Cash Solution.
PayID	ans32	M	ID assigned by 1cs Online Payment System for the payment, e.g. for referencing in batch files as well as for capture or credit request.
XID	ans32	M	ID for all single transactions (authorisation, capture, credit note) for one payment assigned by 1cs Online Payment.
TransID	ans..64	M	TransactionID provided by you which should be unique for each payment.
RefNr		O	Reference number as given in request
Code	n8	M	The 1cs Online Payment System response code.
Status	a..20	M	Status of the transaction. Values accepted: · AUTHENTICATION_REQUEST · PENDING · FAILED
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!
versioningData	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 3DS Method if supported by the ACS and the DS Start and End Protocol Versions which support the card range.
threeDSLegacy	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.
UserData	ans..1024	C	If specified at request, the 1cs Online Payment System forwards the parameter with the payment result to the shop.
Card	JSON	M	Card data

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": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly93d3cuY29tcHV0b3AtcG F5Z2F0ZS5jb20vY2JUaHJlZURTLmFzcHg_YWN0aW9uPW10aGROdGZuIiwidGhyZWVEU1Nlcn ZlclRyYW5zSUQiOiIxNGRkODQ0Yy1iMGZjLTRkZmUtODYzNS0zNjZmYmY0MzQ2 OGMifQ==", "threeDSMethodData": { "threeDSMethodNotificationURL": "https://www.computop-paygate.com/cbThreeDS.aspx?action=mthdNtfn", "threeDSServerTransID": "14dd844c-b0fc-4dfe-8635-366fbf43468c" } }

2.2.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 3DS 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 3DS 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 not that the threeDSMethodURL will be populated by the 1cs Online Payment System if the issuer does not support the 3DS Method. The 3DS 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-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="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNhYzdjYWE3LWFhNDItMjY2My03OTFiLTJhYzA1YTU0MmM0YSIsI nRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIn0">

</form>

The ACS will intercat 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 nca3DSWebSDKin 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.

Once the 3DS 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 3DS 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>

Notice: 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 Online Payment System.

2.2.6 Authentication

If 3-D Secure Method is supported by the issuer ACS and was invoked by the merchant, the 1cs Online Payment System will automatically continue with the authentication request once the 3-D Secure Method has completed (i.e. 3DS 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 mandated 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 Online Payment System will automatically continue and respond to the cardholder browser once the authorization completed.

Cardholder Challenge: Browser Response

Browser Challenge Response

Data Elements

Key	Format	Condition	Description
acsChallengeMandated	boolean	M	Indication of whether a challenge is required for the transaction to be authorised due to local/regional mandates or other variable: true → Challenge is mandated by local/regional regulations false → Challenge is not mandated by local/regional regulations, but is deemed necessary by the ACS
challengeRequest	object	M	Challenge request object.
base64EncodedChallengeRequest	string	M	Base64-encoded Challenge Request object.
acsURL	string	M	Fully qualified URL of the ACS to be used to post the Challenge Request.

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": true,

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

Key	Format	Condition	Description
MID	ans..30	M	Merchant identifier assigned by First Cash Solution.
PayID	an32	M	ID assigned by the 1cs Online Payment System for the payment, e.g. for referencing in batch files as well as for capture or credit request.
TransID	ans..64	M	TransactionID provided by you which should be unique for each payment
Code	n8	M	The 1cs Online Payment System response code.
MAC	an64	M	Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify)
authenticationResponse	JSON	M	Response object in return of the authentication request with the ACS

Browser Challenge

If a challenge is mandated (see acsChallengeMandated) 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">

</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 3DS Challenge Request - Example</title> </head> <body>  <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.

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

2.2.7 Authorization

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

In both cases the 1cs Online Payment System will deliver a final notification to the merchant specified URLNotify with the data elements as listed in the table below.

Payment Notification

Key	Format	Condition	Description
MID	ans..30	M	Merchant identifier assigned by First Cash Solution.
MsgVer	ans..5	M	1cs Online Payment System Message version. Valid values: 2.0: With 3-D Secure 2.x a lot of additional data were required (e.g. browser-information, billing/shipping-address, account-info, …) to improve authentication processing. To handle these information the JSON-objects have been put in place to handle such data. To indicate that these data are used the MsgVer has been implemented.
PayID	ans32	M	ID assigned by the 1cs Online Payment System 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 the 1cs Online Payment System
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 resubmssions. 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 / 1cs OPS MerchantID / Acquirer ContractID / Acquirer.
TrxTime	an21	M	Transaction time stamp in format DD.MM.YYYY HH:mm:ssff.
Status	a..20	M	Status of the transaction. Values accepted: · Authorized · OK (Sale) · PENDING · FAILED In case of Authentication-only the Status will be either OK or FAILED.
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	the 1cs Online Payment System response code.
MAC	an64	M	Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify)
card	JSON	M	Card data.
ipInfo	JSON	O	Object containing IP information.
threeDSData	JSON	M	Authentication data.
resultsResponse	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.
PCNr	n16	O	Pseudo Card Number: Random number generated by the 1cs Online Payment System 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 the 1cs OPS and is sent as CCNr in Request or part of card-JSON PCNr is a response value from the 1cs OPS and is sent as CCNr in Request or part of card-JSON

Browser Payment Response

Additionally the JSON formated data elements as listed below are trasferred 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

Key	Format	Condition	Description
MID	string	M	Merchant identifier assigned by First Cash Solution.
Len	integer	M	Length of the unencrypted Data string.
Data	string	M	Blowfish encrypted string containg a JSON object with MID, PayID and TransID.

{ "$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

Key	Format	Condition	Description
MID	ans..30	M	Merchant identifier assigned by First Cash Solution.
PayID	ans32	M	ID assigned by the 1cs Online Payment System for the payment, e.g. for referencing in batch files as well as for capture or credit request.
TransID	ans..64	M	TransactionID provided by you which should be unique for each payment

Sample of the decrypted data:

MID=YourMID&PayID=PayIDassignedby1csOPS&TransID=YourTransID

2.3 3DS 1.0 Fallback

In case the Access Control Server (ACS) of the cardholder’s bank does not support any EMV 3DS protocol version (i.e. 2.0 or higher, see acsStartProtocolVersion) the threeDSMethodDataForm element of the versioningData object in the payment response will be Null.

Sequence Diagram

2.3.1 3DS 1.0 Authentication

In order to a 3DS 1.0 authentication request through the cardholder browser it is required to construct a form with the data elements provided in threeDSLegacy and to post it to the acsURL.

The form fields that are sent to the ACS are listed in the table below:

Form Element	Description
PAReq	A constructed, Base64 encoded and compressed field carrying the Payer Authentication Request Message Fields. The compression algorithm used is a combination of LZ77 and Huffman coding as specified in RFC 1951.
TermURL	The merchant URL the ACS will redirect the cardholder to after the authentication has concluded. Note that the 1cs Online Payment System adds the fields PayID, TransID and MID in the query string to the base URL. Please do not alter the TermURL!
MD	The MD (i.e. Merchant Data) field can carry whatever data the merchant needs to continue the session. Please note that this field must be present in the form even though it is not used.

Sample: PAReq form passed through the Cardholder to the ACS URL

<html>

<head>

<script language=\"javascript\">

<!--

function sendpareq()

{

document.pareq_form.submit(); } // --> </script> </head> <body onload="javascript:sendpareq();"> <form action="https://pit.3dsecure.net/VbVTestSuiteService/pit1/acsService/paReq?summary=ZTIwOWMwYmEtNTVhOC00NDExLThkZDktYzllODk1NmZlNDQ0" method="POST" name="pareq_form"> <input type="hidden" name="PaReq" value="eJxVUst22jAQ/RUfL7rpMZKFiQ0dK4dXgAVOTmuSpjvVGsApfkSWA+TrK/Fo0t29M6M7M3cEt4di57yhavKqjF2/Q10Hy6ySebmJ3VV650Wu02hRSrGrSozdIzbuLYd0qxAnPzBrFXJYYtOIDTq5jN1aCIEioyzywkhILwh7gddnFD1JMVyv 15HfYz2Xw8PwO75yuPTmpnWHAblSo6myrSg1B5G9jhYJD266jHWBXCgUqBYTPk4fR4+M+jdAzgEoRYG8zrXGRn+dFb/nz hdR1N+ccQXklIOsakutjpyF5tWVQKt2fKt1PSBkv993sqqoW13VHYlAbA7Ix0gPrUWN0Trkkv+aLVnyvjkuZ6tD8vS8Ty a7l/unBXt+n8ZAbAVIoZGbMSPaY4HjB4MuHQR9IKc4iMIOwX1KzXpnDLVtMfyU+BwA47sydzryfhiZHa4M8FCbM5kKY+U/DBKbjKfGD9PQQiAfC4zn1uFMG+vm+V06bad/Zi+rn6rrJ20xWt4P49h6fiqw8rnxyo/8s74lQKwEuZyTXP6CQf/9kb8b1MvQ"> <input type="hidden" name="TermUrl" value="http://localhost:40405/test/3DTermURL.aspx?PayID=dc67820e15f049c9b6c1f0420729da8a&TransID=20180524-162741-084&MID=gustav"> <input type="hidden" name="MD" value="Optional merchant session data"> </form> </body> </html>

Once the authentication has been completed or the cancelled by the cardholder the ACS will redirect the cardholder through the cardholder’s browser to the TermURL as specified in the initail payment request.

Notice: The Payer Authentication Response (PaRes) will be transferred via HTTP POST method while MID, PayID and TransID are sent in the HTTP query string (i.e. HTTP GET).

Data Elements transferred to the TermURL

Key	Format	Condition	Description
MID	ans..30	M	MerchantID, assigned by First Cash Solution.
PayID	ans32	M	ID assigned by the 1cs Online Payment System for the payment, e.g. for referencing in batch files as well as for capture or credit request.
TransID	ans..64	M	TransactionID provided by you which should be unique for each payment
PARes	—	M	The PARes (Payer Authentication Response) message sent by the ACS in response to the PAReq regardless of whether authentication is successful.

2.3.2 Authorization

In order to authorize an 3DS 1.0 authenticated payment you must POST the parameter as listed in the table below unencrypted to https://www.computop-paygate.com/direct3d.aspx. The response always is encrypted (Len + Data).

Request Elements

Key	Format	Condition	Description
MerchantID	ans..30	M	MerchantID, assigned by First Cash Solution. Additionally this parameter has to be passed in plain language too.
PayID	ans32	M	ID assigned by the 1cs Online Payment System for the payment, e.g. for referencing in batch files as well as for capture or credit request.
TransID	ans..64	M	TransactionID provided by you which should be unique for each payment
PAResponse	—	M	The PARes (Payer Authentication Response) message sent by the ACS.

Response Elements

Key	Format	Condition	Description
MID	ans..30	M	MerchantID assigned by First Cash Solution.
PayID	an32	M	ID assigned by the 1cs Online Payment System 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 the 1cs Online Payment System
TransID	ans..64	M	TransactionID provided by you which should be unique for each payment
Status	a..20	M	Staus of the transaction. Values accepted: Authorized OK (Sale) FAILED
Description	ans..1024	M	Textual description of the code
Code	n8	M	the 1cs Online Payment System response code
card	JSON	C	Card data
ipInfo	JSON	O	Object containing IP information
threeDSData	JSON	M	Authentication data

2.3.2.1 Payer Authentication Request Message Fields

The Payer Authentication Request (PAReq) message field is a data element constructed by First Cash Solution’s Merchant Server Plug-in (MPI).

The MPI builds the XML PAReq, in canonical format according to the DTD. It passes the XML stream to an RFC1951-compliant compressor, which produces an RFC1950-compliant output stream which turn is Base64 encoded.

For eductaional purposes the PAReq data elements are listed in the table below.

PAReq

Data Eelement	CND	Description
Message Version Number	M	Message Version Number as received in the Verify Enrollment Response (VERes). Values accepted: 1.0.1 1.0.2
Acquirer Bank Identification Number (BIN)	M	This field must match the acquirer BIN used in the Verify Enrollment Request.
Merchant Identifier (ID) Number	M	This field must match the Merchant ID used in the Verify Enrollment Request. This field also must match the Merchant ID used by the acquirer with the card networks for authorizations and clearing.
Merchant Name	M	This field must contain the name of the online merchant at which cardholder is making the purchase. The maximum length is 25 characters. The merchant name must match the name submitted for authorization and clearing.
Merchant Country Code	M	This field must contain the ISO 3166 three digit country code value.
Merchant URL	M	This field must contain the fully qualified URL of the merchant site.
Transaction Identifier	M	Unique transaction identifier determined by merchant. Contains a 20 byte statistically unique value that has been Base64 encoded, giving a 28 byte result.
Purchase Date & Time	M	Date and time of purchase expressed in GMT in the following format: YYYYMMDD HH:MM:SS.
Purchase Amount	M	This field must contain the value of the purchase being made by the cardholder. It is a value up to 12 digits with punctuation removed.
Purchase Currency	M	The appropriate ISO 4217 three-digit currency code for the transaction currency between the cardholder and merchant must be used.
Currency Exponent	M	The minor units of currency as defined in ISO 4217.
Order Description	O	Brief description of items purchased, determined by the merchant. Maximum size is 125 characters, but merchant should consider the characteristics of the cardholder’s device when creating the field.
Recurring Payment Data	C	A Recur element must be included if the merchant and cardholder have agreed to recurring payments.
Installment Payment Data	C	An integer greater than one indicating the maximum number of permitted authorizations for installment payments. Must be included if the merchant and cardholder have agreed to installment payments.
Account Identifier	M	The content of this field is a data string useful to the ACS; it must not reveal the PAN and must be generated using an algorithm that is likely to generate unique values, even if the same PAN is being presented.
Card Expiry Date	M	Expiration Date supplied to merchant by cardholder (YYMM).
Message Extension	O	Any data necessary to support the requirements that are not otherwise defined in the PAReq message must be carried in an instance of Message Extension.
Recurring Payment Data
Recurring Frequency	M	An integer indicating the minimum number of days between authorizations.
Recurring Expiry	M	The date after which no further authorizations should be performed. (YYYYMMDD format).

2.4 Silent Order Post (PayNow)

2.4.1 Overview

A Silent Order Post or Direct Post is a transmission method where form data from a merchant website are getting directly posted to a third-party server. This is commonly achieved through the formaction attribute that specifies the URL the data are sent to.

Notice: Sensitive data such as card details can be captured within a merchant’s website without being processed by the merchant server as the POST is submitted silently. The URL endpoint in the 1cs Online Payment System to receive Silent Order Post requests is referred to as PayNow.

This approach is very similar to First Cash Solution hosted payment forms and leaves the merchant in full control of the checkout experience as all website elements are delivered from the merchant’s server.

PCI-DSS Considerations: Merchants processing card transactions using the Silent Post model must submit the PCI DSS Self-Assessment Questionnaire (SAQ) A-EP. This SAQ is more comprehensive and thus might require more time and resources in comparison to SAQ A applicable to merchants that use hosted payment pages. However, merchants should always consult with their acquirer to evaluate the level of compliance required and refer to the PCI DSS guidelines. This does not affect the use of pseudo card numbers which is possible without submitting the SAQ questionaire.

Notice about Cookie-/Session Handling: about Cookie-/Session Handling: Please note that some browsers might block necessary cookies when returning to Your shop. Here you will find additial information and different solution approaches.

Sequence Diagram

2.4.2 Payment Request

Please POST the form data as outlined in table below to https://www.computop-paygate.com/payNow.aspx .

Form elements

Data Element	Legacy Element	Description
MerchantID	—	Merchant identifier assigned by First Cash Solution.
Len	—	The length of the original encrypted with Blowfish.
Data	—	Blowfish encrypted data.
number	CCNr	Card number.
securityCode	CCCVC	Card security value.
expiryDate	CCExpiry	Card expiry in format YYYYMM.
brand	CCBrand	Card network.
cardholder	CreditCardHolder	Name of the cardholder as printed on the card. Notice: Alphanumeric special characters, listed in EMV Book 4, “Appendix B”. Special characters have been added with EMV 3DS Version 2.3, but not all participants (banks) already support that standard.

(- First Cash Solution will continue to support the legacy form data fields that are currently in use. -)

Data

Key	Format	Condition	Description
MerchantID	ans..30	M	MerchantID assigned by First Cash Solution. Additionally this parameter has to be passed in plain language too.
TransID	ans..64	M	TransactionID provided by you which should be unique for each payment
MsgVer	ans..5	M	Message version. Accepted values: 2.0
RefNr		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. Details on supported format can be found below in payment specific section. Only ASCII characters allowed, special characters (“Umlaute”, diacritics) are not allowed and must be replaced by their ASCII-representation (e.g. ü → ue, é → e, …).
Amount	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	a3	M	Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: A1 Currency table EN
Capture	ans..6	OM	Determines the type and time of capture. AUTO = Capturing immediately after authorisation (default value). MANUAL = Capturing made by the merchant. Capture is normally initiated at time of delivery. <Number> = Delay in hours until the capture (whole number; 1 to 696).
billingDescriptor	ans..22	O	A descriptor to be printed on a cardholder’s statement. Please also refer to the additional comments made elswhere for more information about rules and regulations.
OrderDesc	ans..768	O	Order description.
AccVerify	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: Yes
threeDSPolicy	JSON	O	Object specifying authentication policies and excemption handling strategies.
priorAuthenticationInfo	JSON	O	Prior Transaction Authentication Information contains optional information about a 3DS cardholder authentication that occurred prior to the current transaction.
browserInfo	JSON	M	Accurate browser information are needed to deliver an optimized user experience. Required for 3DS 2.0 transactions.
accountInfo	JSON	O	The account information contains optional information about the customer account with the merchant.
billToCustomer	JSON	C	The customer that is getting billed for the goods and / or services. Required unless market or regional mandate restricts sending this information.
shipToCustomer	JSON	C	The customer that the goods and / or services are sent to. Required if different from billToCustomer.
billingAddress	JSON	C	Billing address. Required (if available) unless market or regional mandate restricts sending this information.
shippingAddress	JSON	C	Shipping address. If different from billingAddress, required (if available) unless market or regional mandate restricts sending this information.
credentialOnFile	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.
merchantRiskIndicator	JSON	O	The Merchant Risk Indicator contains optional information about the specific purchase by the customer. If no shippingAddress is present it is strongly recommended to populate the shippingAddressIndicator property with an appropriate value such as shipToBillingAddress, digitalGoods or noShipment.
URLSuccess	an..256	M	Complete URL which calls up 1cs Online Payment System 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 the 1cs OPS and shop, please use the parameter UserData. Common notes: We recommend to use parameter “response=encrypted” to get an encrypted response by 1cs Online Payment System However, fraudster may just copy the encrypted DATA-element which are sent to URLFailure and send the DATA to URLSuccess. Therefore ensure to check the “code”-value which indicates success/failure of the action. Only a result of “code=00000000” should be considered successful.
URLFailure	an..256	M	Complete URL which calls up 1cs Online Payment System 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 1cs OPS and shop, please use the parameter UserData. Common notes: We recommend to use parameter “response=encrypted” to get an encrypted response by 1cs Online Payment System However, fraudster may just copy the encrypted DATA-element which are sent to URLFailure and send the DATA to URLSuccess/URLNotify. Therefore ensure to check the “code”-value which indicates success/failure of the action. Only a result of “code=00000000” should be considered successful.
URLNotify	ans..256	M	Complete URL which 1cs Online Payment System 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. Common notes: We recommend to use parameter “response=encrypted” to get an encrypted response by 1cs Online Payment System However, fraudster may just copy the encrypted DATA-element which are sent to URLFailure and send the DATA to URLSuccess/URLNotify. Therefore ensure to check the “code”-value which indicates success/failure of the action. Only a result of “code=00000000” should be considered successful.
MAC	an64	M	Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify)
UserData	ans..1024	O	If specified at request, 1cs Online Payment System forwards the parameter with the payment result to the shop.

Sample HTML form:

BASEURL= https://www.computop-paygate.com/

<!DOCTYPE html>

<html>

<head>

<title>Merchant Checkout</title>

</head>

<body>

<form name="card form" action="https://www.computop-paygate.com/payNow.aspx" method="post">

<input type="hidden" name="MerchantID" value="MerchantID">

<input type="hidden" name="Len" value="Length of the Blowfish encrypted data">

<input type="hidden" name="Data" value="Blowfish encrypted data">

Cardholder:

<input type="text" name="cardholder"><br>

Card number:

<input type="text" name="number"><br>

Expiry date:

<input type="text" name="expiryDate"><br>

CVV2:

<input type="text" name="securityCode"><br>

Card brand:

<input type="text" name="brand"><br>

<input type="submit" value="Submit">

</form>

</body>

</html>

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 receiver parameters both via GET and via POST.

2.4.3 HTTP POST to URLSuccess / URLFailure / URLNotify

Key	Format	Condition	Description
MID	ans..30	M	Merchant identifier assigned by First Cash Solution.
MsgVer	ans..5	M	1cs Online Payment System Message version. Valid values: 2.0: With 3-D Secure 2.x a lot of additional data were required (e.g. browser-information, billing/shipping-address, account-info, …) to improve authentication processing. To handle these information the JSON-objects have been put in place to handle such data. To indicate that these data are used the MsgVer has been implemented.
PayID	an32	M	ID assigned by the 1cs Online Payment System 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 the 1cs Online Payment System
TransID	ans..64	M	TransactionID provided by you which should be unique for each payment
refnr		O	Reference number taken from request
schemeReferenceID	ans..64	C	Card scheme specific transaction ID required for subsequent credential-on-file payments, delayed authorizations and resubmssions. 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 / 1cs Online Payment System MerchantID / Acquirer ContractID / Acquirer.
Status	a..20	M	Staus of the transaction. Values accepted: · Authorized · OK (Sale) · FAILED In case of Authentication-only the Status will be either OK or FAILED.
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	the 1cs Online Payment System response code.
card	JSON	M	Card response data.
ipInfo	JSON	C	Object containing IP information. Presence depends on the configuration for the merchant.
threeDSData	JSON	M	Authentication data.
resultsResponse	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.
UserData	ans..1024	C	If specified at request, 1cs Online Payment System forwards the parameter with the payment result to the shop.
MAC	an64	M	Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify)

3 JSON objects

Notice: Please note that the data within all JSON objects is encoded using UTF-8 and then must be also Base64 encoded. This applies in particular to special characters such as “Umlaute” and diactrics.

1cs Online Payment System validates JSON objects on all requests which contain parameter “MsgVer=2.0”. This is independently of the fact whether 3DSecure2 is activated for your MerchantID.

Please make sure no empty parameters or objects are submitted. Under such circumstandes 1cs Online Payment System assumes an error and rejects the transaction.

4 Important notes

4.1 3DS authentication hosting

Payment platform also supports scenarios where merchants wish to use BNP’s 3DS Server (3DS 2.0) respectively 3DS MPI (3DS 1.0) as a hosted solution and subsequently authorize the transaction via an integration to a third-party.

Notice: Please contact the First Cash Solution Support Team to request neccessary configuration changes at your Merchant ID.

Authentication hosting only is supported for

Hosted Forms (paySSL) and
Server-2-Server

integrations.

All messages, sequences and data elements exchanged between the merchant environment and the 1cs Online Payment System remain the same as for regular payments except that the 1cs Online Payment System does not authorize the transaction with an acquirer. Authentication data (e.g. authenticationValue and eci) necessary for subsequent authorization transactions are provided via threeDSData and resultsResponse (challenge flows only).

Please see below a sample payment notification for a succesful authentication only transaction:

MID=ACME& PayID=9e944d5d56f3461da39380a666d346d1& TransID=V3DSTestSuite_001& XID=334ce1701a5b444db4e2296a680ae330& Code=00000000& Status=OK& Description=Authentication completed correctly& card= { "number": "400001XXXXXX8323", "brand": "VISA", "country": { "countryName": "United Kingdom of Great Britain and Northern Ireland", "countryA2": "GB", "countryA3": "GBR", "countryNumber": "826" } }& threedsdata= { "authenticationStatus":true, "acsProtocolVersion":"2.1.0", "authenticationValue":"JAmi21makAifmwqo2120cjq1AAA=", "eci":"05", "threeDSServerTransID":"9e944d5d-56f3-461d-a393-80a666d346d1" }& resultsResponse= { "threeDSServerTransID":"9e944d5d-56f3-461d-a393-80a666d346d1", "acsTransID":"1e43b52f-3623-4e5d-8917-41c5c15b7218", "acsRenderingType":{ "acsInterface":"native", "acsUiTemplate":"text" }, "authenticationType":"02", "authenticationValue":"JAmi21makAifmwqo2120cjq1AAA=", "challengeCancel":"", "dsTransID":"c626e8a0-f2ba-42b3-aa6d-620658421f3a", "eci":"05", "interactionCounter":"01", "messageCategory":"01", "messageExtension":"", "messageVersion":"2.1.0", "sdkTransID":"", "transStatus":"Y", "transStatusReason":"" }& MAC=AE6E011454EB54858006007D73D766B7A0306AB8FD925D08C3BF222D4A366123

4.2 Account Verification

An account verification also known as a zero value authorization is a request to check whether a card account is in good standing (i.e. the card is not stolen and the card account can be used for payments).

3DS and Account Verification

Please note that if an account verification (i.e. AccVerify=Yes) in combination with 3DS is requested the authorization will be always performed with a zero-value. The authentication however will be carried out with the amount correspondent to the value submitted in the Amount field. If the transferred Amount is a zero-value the related liability shift will be also for a zero amount.

Credential on File

Please note that non-payment transactions that establish a credentialOnFile (aka Card Add) require an account verification.

Standalone Account Verification

If you request an account verification without adding a card on file the data element browserInfo becomes optional for Server-2-Server and Silent Order Post integrations. Other conditional data elements might also be not applicable.

4.3 Amazon Payments MFA

Overview

In order to be compliant with the PSD2, Amazon Pay introduced SCA for their transactions.

The SCA Upgrade introduces a “Confirmation Flow” to handle Multi-Factor Authentication (MFA) when it is required.

When MFA is required, the Confirmation Flow shows the credit card issuer’s MFA challenge to the buyer. After the buyer interacts with the Confirmation Flow (for example, completes the MFA challenge), the buyer is returned to the merchant’s site (for example, order confirmation page).

Please update the AmazonPay checkout workflow after a buyer initiates their order completion and before you call the Authorize Operation.

Changes

New JavaScript function confirmationFlow()

Due to MFA, it is necessary after a succesful confirmation of an order to start a new call, the ConfirmationFlow.

To start the workflow, please

execute a Confirm on the order on the 1cs Online Payment System, after you receive a result
start the confirmationFlow in case of success with “confirmationFlow.success()”
in case of failure “confirmationFlow.error()” aborts the process.

Implementation of the new Javascript call is shown below. This has been optimized for our First Cash Solution merchants.

Notice: This action should be triggered by clicking on the “Buy Now” button!

function confirmationFlow() { // Get resultCode from First Cash Solution call AmazonAPA.aspx, EventToken: COD var resultCode_First Cash Solution = the 1cs Online Payment System call to get the ResultCode from the Confirm, AP call COD or SCO. // Your AmoazonSellerID / AmazonMerchantID var amazonSellerId = 'Your_SellerID'; // Amazon order reference generated by Address Widget var orderReferenceId = 'Your_Order_Reference'; //Initiate confirmation flow OffAmazonPayments.initConfirmationFlow(amazonSellerId, orderReferenceId, function (confirmationFlow) { if(resultCode_First Cash Solution = '00000000') { confirmationFlow.success(); } else { confirmationFlow.error(); } } ); }

Please also refer to https://developer.amazon.com/de/docs/eu/amazon-pay-onetime/sca-upgrade.html for additional guidance.

Merchant should be able to handle First Cash Solution’s redirection (URLSuccess / URLFailure) with the result of the MFA Challenge.

URLSuccess / URLFailure for ConfirmOrderDetails (COD) and SetOrderDetails and ConfirmOrder (SCO) call

Key	Format	Condition	Description
URLSuccess	ans..256	M	The buyer is redirected to this URL if the MFA is successful.
URLFailure	ans..256	O	The buyer is redirected to this URL if the MFA is unsuccessful.
AuthorizationAmount	n..12	O	The amount to authenticate during MFA completion. Use this parameter if you want to set a payment amount that is different than the OrderTotal provided in the SetOrderReferenceDetails operation call. If this parameter is not set, the amount authenticated during MFA will be equal to the OrderTotal provided in the SetOrderReferenceDetails operation call.

On “Order Now” the merchant has to send the URLSuccess and URLFailure in the calls (EventToken=SCO | COD), because the redirect is executed after the MFA challenge.

After “Order Now” the Confirm (EventToken=SCO | COD) is executed on the payment and then the redirect to the challenge takes place using the JavaScript code shown above.

AmazonAPA.aspx

The following event calls at the 1cs Online Payment System are affected by the changes. Please make sure to include the new parameters.

EventToken	Action	Description
SOD	SetOrderDetails	Transfer of amount payable and further information – controls also the pay-ment methods selectable for an order at Amazon
GOD	GetOrderDetails	Request of order information, e.g. to get information about a newly selected delivery address. After a call with Eventtoken COD or SCO, GOD returns also the billing address of the customer When Scope enters “payments:shipping_address” and “payments:billing_address” you receive the full delivery and shipping address after the display of the Address widget. Please transfer the OrderReferenceId on call up.
SCO	SetOrderDetailsAndCon-firmOrder	Order confirmation again with transfer of amount payable and further infor-mation – with this Eventtoken the order is finalized. After successfully confir-mation authorizations can be submitted to Amazon immediately.
COD	ConfirmOrderDetails	Optional, if amount payable and further information should not transferred once more for order confirmation (First Cash Solution recommends using the Eventtoken SCO for order confirmation.)
COR	CloseOrderReference	Closing an Amazon order. Captures related to open authorizations as well as credits are possible furthermore

User Flow and Sequences

Flow

1. Clicks on AmazonPay button to sign-in

2. Chooses an address from the widget

3. Chooses payment method from the widget

4. Confirms the order

Option 1: SCO

This is the recommended option.

Option 2: SOD and COD

1. The first call is to be made to ConfirmationFlow – with this, AmazonPay can handle the MFA if required. Here is confirmationFlow error/success to be set. Reference to the Amazon Pay Widgets.js file already used for the other widgets.

2. Call SetOrderDetails (SOD) including OrderTotal

3. Call ConfirmOrderDetails (COD) set URLSuccess/URLFailure parameter with a returnURL value

Notice: As shown above, we recommend the SCO call that is a single step to set the order details and also to confirm the order Details.

Option 3: MFA Failure

Notice: We recommend our merchants to only work with the the 1cs Online Payment System status or the 1cs Online Payment System response code in these cases.

Status =>Abandoned:

Status =>Failure:

1. If the customer fails or abandons the challenge, the customer is redirected to the URLFailure.

2. Logout the user.

3. Cancel the order by calling “Reverse.aspx”

Cancel Order by Calling “Reverse.aspx“

In order to reverse a complete order with Amazon Pay with the function „CancelOrderReference“, please request to https://www.computop-paygate.com/reverse.aspx

More and detailed information is found in the official First Cash Solution documentation here: Amazon Pay Manual

Status

If the MFA is successful, the redirection is done to URLSuccess, if not the redirection is done to URLFailure.

Authentication Status Value	Description	Recommended Action
Success	Successful / not necessary	No action needed
Failure	Failed	Redirection FailureURL or forwarding to page in order to use a payment method other than Amazon
Abandoned	Failed	Redirection FailureURL or to page to replace the order sing Amazon Pay and complete the MFA challenge

Notice: The Amazon Authentication Response is given back to the shop via the the 1cs Online Payment System in the, Response Parameter = amazonstatus.
Example: amazonstatus=Abandoned

Notice: In the Amazon SCA manual point 3 (Amount consistency)
The AuthorizationAmount value (in the Authorize operation) must always match the CaptureAmount value (in the Capture operation).
If not the Capture operation call response will be handled asynchronously; the Capture object State value is set to Pending and may not be processed in real time, even if it is requested within seven days of the Authorize operation call!

4.4 Dynamic billing descriptors

General Requirements

The billingDescriptor element is used to override the merchant name that is sent to a cardholder’s bank where applicable.

The merchant name is the most important factor in cardholder recognition of a transaction record typically printed on a cardholder statement. It should reflect the operating name of a company (i.e. ‘Doing Business As’ (DBA) name), as opposed to the legal name, by which a cardholder would recognize the merchant to avoid any confusion and to minimize copy requests.

As a standard, acquirers usually forward the merchant name they got on file with the merchant’s account. Please note that the card organizations established strict rules around merchant names on cardholder statements.

However, there are a number of specific exceptions where supplementary data can be added to the DBA name depending on the use case and industry (e.g. airlines, railway services, car rental, fuel stations etc.).

Formatting the merchant name

The authorization and clearing systems of the card organizations provide varying sizes for merchant names. The smallest common denominator is 22 characters. Thus, merchant names longer than 22 characters will not fit into the merchant name field and must be abbreviated in a way that it is still recognizable to the cardholder.

Purchase of Goods or Services

For regular purchases of goods and services additional information may be included after the merchant name and an asterisk (*) to indicate an order number, reference number, or other information to identify a transaction.

01	02	03	04	05	06	07	08	09	10	11	12	13	14	15	16	17	18	19	20	21	22
G	R	E	A	T		B	R	A	N	D		L	T	D	*	0	8	1	5	3	7

No-Show Transactions

May also include the words “NO SHOW” after the merchant name.

01	02	03	04	05	06	07	08	09	10	11	12	13	14	15	16	17	18	19	20	21	22
H	.	C	A	L	I	F	O	R	N	I	A		N	O		S	H	O	W

Purchase of an airline Ticket (or passenger railway tickets in the US Region)

Must contain all of the following:

An abbreviated airline (or US railway) name in the first 11 or 12 positions
A blank in position 12 if applicable
Airline (or US railway) ticket identifier beginning position 13

01	02	03	04	05	06	07	08	09	10	11	12	13	14	15	16	17	18	19	20	21	22
F	L	Y		L	O	W		P	L	C		1	2	3	4	5	6	7	8	9	0

4.5 Mandatory and Conditional Required Data Elements for EMV 3DS

Please note that some data elements in EMV 3DS that are marked as conditional required are further specified as:

Required unless market or regional mandate restricts sending this information.

This applies for instance to data elements such email, phone number or billing address.

Considering the legal landscape and depending on the issuer (or more precisely on the vendor of the issuer Access Control Server (ACS)) this specification might be interpreted as strictly required within the European Economic Area (EEA).

Contrary to the EMV 3DS protocol specification:

A.1 Missing Required Fields

. . .

Unless explicitly noted, if a required field is missing, the receiving component returns an Error Message . . . This applies whether the field is always Required or Conditionally required.

The card schemes mandated that issuers must not decline EMV 3DS messages when one or more of conditional fields are absent. But the card schemes also stipulate that merchants must send conditional fields in EMV 3DS messages in accordance with the applicable data protection law.

The following elements are considered key and it is strongly advised to provide these data points:

Cardholder Information
- Name
- Email address
- Home phone number
- Mobile phone number
- Billing address
- Shipping address
Browser Information (depending on the integration type)
- IP Address

Notice: As a general rule it is strongly recommended to always send conditional required data elements to avoid unnecessary friction and declines.

4.6 Multi-party e-commerce / agent model

In some scenarios cardholder data are captured and processed (e.g. authentication and authorization) through third-party websites on behalf of one or multiple merchants. The third-party website operartor is usually reffered to as an Agent. Because the cardholder is interacting with the Agent’s environment it is the Agent’s obligation to perform payment authentication.

The requirements for Agent processing models are described in the following paragraphs.

VISA

Travel and Hospitality Merchants

Scenario 1: Authentication performed by a Travel Agent on behalf of one single merchant

When the Travel Agent is facilitating authentication on behalf of a single merchant at the time of booking the process is as follows:

The Travel Agent discloses to the cardholder appropriate T&Cs and follows other requirements associated with the potential future MIT type the merchant may have to process.
The Travel Agent authenticates the transaction for the total booking amount (Merchant descriptor name = “Travel Agent Name * name of merchant ” )
The Travel Agent may optionally perform an account verification to check validity of the card before passing the card details to the merchant (If an account verification is performed, it must not include the CAVV as this is required by the end merchant )
The Travel Agent passes the authentication data to the merchant.
The Merchant submits a normal authorization request to the 1cs Online Payment System including the required data in the threeDSData [Request] JSON object.

In case the merchant wants to perform the payment at a later time than he should:

1. Perform an Account Verification(i.e. AccVerify=Yes)with the authentication data received from the Agent within 24 hours.

2. Subsequently when the amount is due send an authorization flagged as MIT including the schemeReferenceID from the previous account verification transaction.

Scenario 2: Authentication performed by a Travel Agent on behalf of several other merchants.

This scenario covers the case when a customer makes a travel reservation online via a Travel Agent which includes the delivery of services by multiple merchants.

The Travel Agent discloses to the cardholder appropriate T&Cs and follows other requirements associated with the potential future MIT type the merchant may have to process
The Travel Agent then authenticatesthe transaction for the total booking amount ( Merchant descriptor name = “Travel Agent Name” )
An additional 3DS 3RI authentication requestis required to provide CAVVs for each further merchant who will perform an authorization.
The Travel Agent submits authentication data to the merchant.
The Merchant submits a regular authorization request to the 1cs Online Payment System including the required data in the threeDSData [Request]JSON object.

In case the merchant wants to perform the payment at a later time than he should:

1. Perform a zero-value account verification with the authentication values received from the Agent
within 24 hours.

2. Subsequently when the amount is due send an authorization flagged as MIT including the schemeReferenceID from the previous account verification transaction.

Other Merchants

Scenario 3: Authenticated CIT from the Agent and subsequent MIT transaction from the merchant

This is the case when the Agent performs the authentication and subsequently uses the VISA CAVV for its own authorization payload. In such a case as the Agent already used the CAVV and he may not be able to use the 3DS/3RI feature (for having a new CVV for the merchant) than he can provide to the merchant only the schemeReferenceID of the initial CIT together with the payload so that the merchant may initiate his authorizations flagged as an subsequent MIT (i.e UCOF, Delayed Auth)

As a difference worthy to be highlighted between VISA and MC is such use cases is that:

a) Authentication Value (CAVV/AAV)

In case of VISA, the Agent who is performing authentication on behalf of several merchants needs through the 3DS/3RI request (only possible with EMV 3DS 2.2 version) to provide separate CAVV’s values for each merchant separately.
MasterCard on the other hand is stating that for the Agent Model where a single authentication is linked to multiple authorizations the same authentication code/ AVV could be used for multiple transactions.

b) schemeReferenceID

Under the third scenario the Agent can provide to the merchant together with the payload only the ‘schemeReferenceID’ from the initial CIT with no Authentication data in such a way that the merchant is able to initiate subsequent MIT transactions referring to the initial establishment.
For VISA the “schemeRefernceID” (transactionID) is usually provided as a single response parameter while for Mastercard the “schemeReferenceID” is a concatenation of fields like: *(SettlementDate+FinancialNetworkCode& BanknetReference).

-SettlementDate -> n..4
-FinancialNetworkCode -> an..3
-BanknetReference -> an..9

* Agents using this type of scenario (with CIT/MIT) are recommended to provide their merchants with the required MasterCard reference data where the merchant can subsequently submit it to the 1cs Online Payment System “schemeReferenceID” during MIT transactions.

Please also be advised that the above approach for handling each of these scenarios serves only as recommendation, therefore, merchants and Acquirers can choose alternative options that complement their business model, as long as they remain compliant with the key principles of the PSD2 SCA.

4.7 Non-payment authentications for Card Add

Please use AccVerify to request an Account Verification when adding a card to COF without a payment.

Non-payment authentications for Card Add transactions always require step-up authentication (i.e. challenge).

Provisioning, such as Card Add is generally considered as an

action through a remote channel which may imply a risk of payment fraud or other abuses

pursuant to article 97(1)(C) PSD2. There are no exemptions provided for these actions.

When a card is added to COF and a payment is requested at the same time, only one SCA is needed.

Use Case	Flags
Add COF without a payment	AccVerify credentialOnFile
Add COF as part of a payment	credentialOnFile

4.8 Stored Credentials

Whenever card credentials (i.e. cardholder name, card number/token and/or expiry date) are stored for future use a prior consent by the cardholder is required.

During the establishment of such a mandate the cardholder should be informed about the exact reason for storage of the credentials with the merchant. That means an authorization request that establishes a mandate for stored credentials also must indicate the kind of potential subsequent transactions.

These subsequent transactions with a stored payment credential that the cardholder has consented to are broadly categorized into Customer Initiated Transactions (CITs) and Merchant Initiated Transactions (MITs).

Notice: The decisive difference between CITs and MITs is that the latter are out of scope of the RTS for SCA. This is because the Cardholder regularily is off-session and thus, practically not available for an authentication.

There are various use cases for MITs that can be generally categorized into transactions following a certain Industry Practice and Standing Instructions.

In the 1cs Online Payment System CITs and MITs for Standing Instructions are flagged via the JSON object credentialOnFile.

Notice: Please note that all unscheduled MIT transactions are not supported in 3DS 2.0 and thus, will be directly sent for authorization without entering the the 1cs Online Payment System 3DS sequence.

MIT Recurring transactions however will be sent through the 3DS 2.0 protocol to the issuer in order to garantuee best possible acceptance rates.

Please note that with each initial CIT that establishes a mandate for subsequent MITs you will receive a schemeReferenceID that must be included in follow-up transactions in order to link the sequence.

Once SCA becomes mandatory on September 14, 2019 existing MITs covered by cardholder agreements can continue to be processed without a schemeReferenceID if the mandates were setup before that date (i.e. grandfathering). Please do not submit any dummy values. the 1cs Online Payment System will automatically apply appropriate values in the authorization protocol to indicate so called grandfathering.

4.8.1 Real-time service via mobile app with payment after service completion

In many scenarios within the sharing economy such as car sharing or bike sharing a customer’s mobile device is an essential part in the service delivery and payment system. Card credentials are often getting stored with the cardholder’s account at the service provider for optimal user experience.

The sequence of actions to be performed are outlined in the diagrams below.

Card Add as part of a none payment transaction (NPA)

Notice: If the Card Add is NOT part of a payment transaction it is mandatory to perform an account verification (see AccVerify).

Card Add as part of a payment transaction

Service Provisioning

Notice: Unscheduled Credential-on-File (UCOF) MITs are not applicable in scenarios where the cardholder is on-session at the time of service completion and thus, is available for authentication. This is regularily the case for car sharing or ride hailing apps for example.

Notice: If the estimated amount is lower than the final amount it is recommended to perform a full reversal on the originally authorized amount and to submit a new authorization for the final amount.

Amount

Card Add

A zero amount or any estimated amount. Please note that the amount is usually displayed to the cardholder during an authentication challenge and thus, should be within the customer’s reasonable expectation.

Service Provisioning

The amount in the authorization request should be an estimated for the service provision according to resonable customer expectations. Once the service has been completed incremental authorizations may be used before the final amount is captured.

credentialOnFile

Card Add

The UCOF flag is submitted to establish a mandate for storing the credentials and to obtain an initial schemeReferenceID. The card issuer is obliged to perform a step-up during authentication.

{ "type": { "unscheduled": "CIT" }, "initialPayment": true }

Service Provisioning

The CIT flag is submitted in order to enable UCOF transactions without card security value.

{

"type": {

"unscheduled": "CIT"

},

"initialPayment": false

}

AccVerify

All Card Adds that are not performed as part of a payment transaction require and account verification.

5 Test cards

Card numbers

Visa	MasterCard	Maestro	Amex	Test Scenario
4000012892688323	5232125125401459	6759649826438453	371449635398431	Browser challenge
4000016435940133	5232122189301469		378282246310005	Browser challenge
4000012699048523	5232127264637786			Browser frictionless; missing DS Transaction ID
4000011744135012	5232122741507017			Not authenticated browser frictionless
4000019966199434	5232122422543299	6799990100000000019	375000000000007	Authenticated browser frictionless
4000015573198637	5232128083944791			Browser challenge missing ACS URL
4000017873485953	5232122596907270			Authentication protocol error
4000014730366880	5232124106987982			Browser challenge; authenticated transaction; missing authentication value

One-time Passwords (OTPs)

Notice: Please confirm the One-Time-Password in case of a challenge with mouseclick instead of Enter key, because otherwise the “Cancel”-button is selected and the authenfication is terminated.

otpValue	transStatus	transStatusReason	ECI	authenticationValue
3333	U	01	01
6666	Y	01	01
7777	A		01	JAmi21makAifmwqo2120cjq1AAA=
8888	N	10
9999	N	08
0001	N	01
0002	N	02
0003	N	03
0004	N	04
0005	N	05
0006	N	06
0007	N	07
0009	N	09
0010	N	10
0011	N	11

transStatus

transStatus	Description
Y	Authentication Verification Successful.
N	Not Authenticated /Account Not Verified; Transaction denied.
U	Authentication/ Account Verification Could Not Be Performed; Technical or other problem, as indicated in ARes or RReq.
A	Attempts Processing Performed; Not Authenticated/Verified, but a proof of attempted authentication/verification is provided.
C	Challenge Required; Additional authentication is required using the CReq/CRes.
D	Challenge Required; Decoupled Authentication confirmed.
R	Authentication/ Account Verification Rejected; Issuer is rejecting authentication/verification and request that authorisation not be attempted.
I	Informational Only; 3DS Requestor challenge preference acknowledged.

transStatusReason

Code	Scheme	Description
01	All	Card authentication failed
02	All	Unknown Device
03	All	Unsupported Device
04	All	Exceeds authentication frequency limit
05	All	Expired card
06	All	Invalid card number
07	All	Invalid transaction
08	All	No Card record
09	All	Security failure
10	All	Stolen card
11	All	Suspected fraud
12	All	Transaction not permitted to cardholder
13	All	Cardholder not enrolled in service
14	All	Transaction timed out at the ACS
15	All	Low confidence
16	All	Medium confidence
17	All	High confidence
18	All	Very High confidence
19	All	Exceeds ACS maximum challenges
20	All	Non-Payment transaction not supported
21	All	3RI transaction not supported
22	All	ACS technical issue
23	All	Decoupled Authentication required by ACS but not requested by 3DS Requestor
24	All	3DS Requestor Decoupled Max Expiry Time exceeded
25	All	Decoupled Authentication was provided insufficient time to authenticate cardholder. ACS will not make attempt
26	All	Authentication attempted but not performed by the cardholder
80	Visa	Error connecting to ACS
80	Mastercard	Returned on all Data Only authentications
80	American Express	Safekey is not available for this type of card
81	Visa	ACS timed out
81	Mastercard	Challenge exemption accepted
82	Visa	Invalid response from ACS
82	Mastercard	Challenge Mandate requested but could not be performed
83	Visa	System Error response from ACS
83	Mastercard	DS dropped reason code received from DS
84	Visa	Internal Error While Generating CAVV
84	Mastercard	ChallengeCancel populated therefore did not route to Smart Authentication Stand-In (Makes authentication decision when ACS is not available).
85	Visa	VMID not eligible for requested program
86	Visa	Protocol version not supported by ACS
87	Visa	Transaction is excluded from Attempts Processing (includes non- reloadable pre-paid cards and non-payments (NPA))
88	Visa	Requested program not supported by ACS

6 Terms and Definitions

Mandatory and conditional data elements

Conditions in 3DS 2.0 are often described as ‘Required unless market or regional mandate restricts sending this information.’

This applies for example to the email address of the cardholder. Please note that some vendors of ACS software and some issuer might consider these data elements technically as mandatory within the EEA since there are currently no known restrictions. Thus, it is highly recommended to submit these data elements if possible.

Condition Codes

Code	Condition
M	Mandatory. Signifies that the data element shall be included in that message.
O	Optional. The data element may or may not be present in a message.
C	Conditional. The data element shall be included (i.e. mandatory) when specified conditions are met.

Definitions

Term	Definition
Authorization	An authorization is an approval or guarantee of funds given by the card issuer to the acquirer.
Authorization Advice	The acquirer advises the card issuer of authorization already given (e.g. Authorization by Voice).
Capture	Capture is the process of combining the approval amount and authorization code of a transaction and turn it into a billable transaction record. It is essentially the instruction to deduct the funds from the debtor’s account. The acquirer usually submits a capture file to the card network (dual messaging system). In Host Capture Systems the merchant usually sends a Capture Advice message to the acquiring host. For Terminal Capture Systems the card acceptor (e.g. merchant) either submits a capture file (most common) to the acquirer or performs a batch upload. The capture records submitted by the card acceptor are usually validated at the acquiring host and then added to the acquirer’s capture file for the corresponding card network.
Sale	A Sale is an instruction from the merchant to the acquirer to request an authorization and a capture of the transaction completed at the Point of Sale within a single message. That means a successful authorization will be added to the acquirer’s capture file automatically without the need for further instructions or completion messages. However, some terminal capture systems may require Sale transactions to be included in the capture file or in the batch upload.
Terminal Capture	Terminal Capture means that the terminal submits Authorizations, Sales, and Reversals to the host throughout the day. The terminal stores all of these transactions as well as any transactions performed locally (offline), so that the terminal can perform a batch submission at the end of the merchant’s processing day. Terminal capture processing offers the merchant the ability to perform offline transactions that are included only in the batch. Offline transactions include for instance returns, prior sales and tip adjustments.
Host Capture	In Host Capture processing, transaction batches are managed by the acquiring host. Merchants transmit transactions to the host as they occur at the point of sale and the host records the transactions in a batch. In ISO 8583 based message protocols this is often referred to as capture advice. The batch is then closed either by request from the merchant’s system (manual batch release) or at a schedule time each day (host auto-close). The auto-close option is the most common mode.
Recurring	Recurring Transactions are a series of transactions processed following agreement between a Cardholder and a Merchant where the Cardholder purchases goods or services over a period of time through a number of separate transactions.
Installment	Installment Transactions represent a single purchase of goods or services billed to a Cardholder’s account in multiple segments, over a period of time that has been agreed between the Cardholder and a Merchant.

7 Response codes

Common notes on 1cs Online Payment System error codes

The 1cs Online Payment System response codes are 8 digits and are coded (i.e.: they consist of digits 0..9 and characters A..Z) in this format: AN8, (NNNNAAAA), e.g. 22060203 or 2206014H.

The structure of the error codes is always:

Position	Meaning	Sample
Digit 1	Indicates status code / error code	2
Digit 2 ..4	Indicates affected module	206
Position 5 .. 8	Indicates affected parameter causing the error	0203 or 014H

Digits 1: Status code or error code

Digit 1	Meaning	Description
0	Ok	Transaction successful, other digits may indicate further information
2	Error	Transaction failed, other digits may indicate further information.
4	Fatal Error	Transaction failed, other digits may indicate further information, e.g. mandatory parameter is missing
6	Continue / Transient	Transaction pending. Final status will be sent asynchronously when available
7	EMV 3DS Info	Intermediate states in the EMV 3DS sequence

Category 2 .. 4: Common modules

Detail	Description
001	1cs OPS cryptography (encrypting, decrypting)
010	Parameter is missing
011	Parameter error in format
012	Parameter is invalid
013	Parameter is too short
014	Parameter is too long
015	Parameter value is missing
016	Parameter value unknown or not allowed
017	Parameter is already present
018	Parameter is expired or not valid any more
019	Parameter is not allowed for current message version
020-0FF	1cs OPS internal
100-FFF	Affected module

Category (2-4)

Please note that some modules may be deprecated or still under development.

Detail (5-8)

Status	category	detail before 7.33/2022-06-23	details after 7.33/2022-06-23	Beschreibung
2	xxx	0101	4101	Message received invalid
2	xxx	0102	4102	Message version number not supported
2	xxx	0103	4103	Sent messages limit exceeded. Only used for PReq
2	xxx	0201	4201	Required element missing
2	xxx	0202	4202	Critical message extension not recognized
2	xxx	0203	4203	Format on one or more elements is invalid according to the specs
2	xxx	0204	4204	Duplicate data element
2	xxx	0301	4301	Transaction ID is not recognized
2	xxx	0302	4302	Data decryption failure
2	xxx	0303	4303	Access denied, invalid endpoint
2	xxx	0304	4304	ISO code is not valid
2	xxx	0305	4305	Transaction data is not valid
2	xxx	0306	4306	Merchant category code is not valid for payment system
2	xxx	0307	4307	Serial number is not valid
2	xxx	0402	4402	Transaction timed out
2	xxx	0403	4403	Transient system failure
2	xxx	0404	4404	Permanent system failure
2	xxx	0405	4405	System connection failure
2	xxx	0911	4911	UnionPay specific error code. Present when Data fields relevance check failed (ECI value and AV appearance are inconsistent with transaction status).
2	xxx	0912	4912	UnionPay specific error code. Present when duplicated transaction ID (Transaction ID should be unique for each AReq request).
2	xxx	0985	4985	3DS 2.0 is not supported by this card. The merchant has to follow the fallbacl process.
2	xxx	3001	3001	Invalid parameter card
2	xxx	3002	3002	Invalid parameter browserInfo
2	xxx	3003	3003	Invalid parameter accountInfo
2	xxx	3004	3004	Invalid parameter billToCustomer
2	xxx	3005	3005	Invalid parameter billToCustomer
2	xxx	3006	3006	Invalid parameter billingAddress
2	xxx	3007	3007	Invalid parameter shippingAddress
2	xxx	3008	3008	Invalid parameter credentialOnFile
2	xxx	3009	3009	Invalid parameter merchantRiskIndicator
2	xxx	3010	3010	Invalid parameter threeDSPolicy
2	xxx	3011	3011	Invalid parameter threeDSData
7	000	0000	0000	3DS 2.0 versioning successful
7	000	0001	0001	Authentication response –> challenge mandated

8 ECI Codes EN

The ECI value is provided by the issuer ACS. It indicates the level of authentication that was performed on the transaction. The ECI value received from authentication is forwarded in the authorization request and also determines whether a transaction recieves liability protection.

Visa, American Express, Discover/Diners, JCB, Cartes Bancaires (VISA), UPI

ECI	Description	3DS Version(s)	Merchant Liability Shift
05	Cardholder authentication successful (this includes successful authentication using risk-based authentication and/or a dynamic password)	3DS 1.0 EMV 3DS (2.0)	Yes
06	Merchant attempted to authenticate the cardholder · For 3DS 1.0.2, the ECI 06 value may be utilized as an authentication response from the Issuer ACS, at the issuer’s discretion. For example, issuers that use risk-based authentication may provide an ECI = 06 for a transaction that does not require step-up, also known as frictionless authentication. These issuers may reserve an ECI = 05 for transactions that were successfully stepped-up. · For 3DS 2.0, the ECI 06 value can only be used to indicate that a “Merchant attempted to authenticate the cardholder”.	3DS 1.0 EMV 3DS (2.0)	Yes
07	Non-authenticated e-commerce transaction technical errors improper configuration card and Issuing Bank are not secured by 3DS	3DS 1.0 EMV 3DS (2.0)	No

MasterCard, Cartes Bancaires (Mastercard)

ECI	Description	3DS Version(s)	Merchant Liability Shift
00	Non-authenticated e-commerce transaction technical errors improper configuration card and Issuing Bank are not secured by 3DS	3DS 1.0 EMV 3DS (2.0)	No
01	Merchant attempted to authenticate the cardholder and received authentication value (Accountholder Authentication Value (AVV))	3DS 1.0 EMV 3DS (2.0)	Yes
02	Cardholder authentication successful (this includes successful authentication using risk-based authentication and/or a dynamic password)	3DS 1.0 EMV 3DS (2.0)	Yes
04	Data share only: non-authenticated e-commerce transaction but merchants have chosen to share data via the 3DS flow with the issuer to improve authorization approval rates	EMV 3DS (2.0)	No
06	Acquirer exemption	EMV 3DS (2.0)	No
07	Recurring payments might be applicable for initial or subsequent transaction) · If this value is received on initial recurring paqyments merchant will have liability shift · Subsequent transactions are considered as MIT and liability remains with the merchant	EMV 3DS (2.0)	Yes

9 3DS 2.0 Merchant Use-Cases & Testing of 3D-Secure 2.0

What can you expect in this area?
Due to various scenarios that can arise with 3-D Secure 2.X, we will subdivide the following into three thematic areas:

General technical adjustments (relevant for all merchants)
Use cases for transaction flagging (different handling depending on merchant scenario)
Test 3-D Secure 2.X via Computop

General technical adjustments

Which request types does 3D-Secure 2.0/SCA affect?

Affected request types are: Authorisation and Sale
Capture (booking) and credit notes are excluded from changes

How will data transfer look like with 3-D Secure 2.x?

REQUEST: During the implementation of 3-D Secure 2.0 and the necessary delivery of larger amounts of data, we recommend you to call our forms via Form-POST Method. Please note that the option iFrame is still available. Background are possible browser restrictions, which can lead to the fact that the sent data string is cut off.
Example:

RESPONSE:
Please also note a change to the final redirect to the URLSuccess | URLFailure.
This will be excecuted as a body POST in the case of a 3D Secure 2.0 transactions. Therefore, you should be able to receive both a GET and a POST response on the URLSuccess | URLFailure.

How can I choose between 3-D Secure 1.0 or 2.0?

IMPORTANT: To be able to use and test 3-D Secure 1.0 or 3-D Secure 2.0, we have to configure 3D Secure on our the 1cs Online Payment System on your behalf. Please contact support@1cs.de if you have not yet started this process.
By default, each payment is made following the 3D Secure 1.0 process.
If you want to follow the 3D Secure procedure 2.0, please use the request parameter MsgVer=2.0. This applies to tests as well as in production at a later stage.
- Parameter: MsgVer
  Value: 2.0

Use of JSON objects becomes mandatory

Please note that a mandatory extension of existing parameters comes with the implementation of 3D Secure 2.0 . For this reason, the 1cs Online Payment System expects and returns relevant additional data as JSON Object.
The JSON Object must be Base64 encoded and regularly transmitted with all other parameters in the encrypted Blowfish data to the 1cs Online Payment System.

Please pass JSON Objects with values only. Empty or zero-filled objects/parameters lead to a rejection.

JSON Example request – encrypted data

BASEURL=https://www.computop-paygate.com/

{{BASEURL}}payssl.aspx?MerchantID=Generic3DSTest&len=1800&
data=CDC44E5A9D2C8A559CEDF1CCA97C9FBD3D90E046BFBF96F06ADA9A00FB0BC3494317E8D924FF44729671B93348B477F880541AC
FF12C8E3A868CD55FEA95219C245CF7F4716FCF3462167A8B63D11424FA7BD30891504F8465C56805975115EB71C0A04E5D7466D77149
5035749FFF94D3087529F578DEF518003EA1422F6DE7B7DFD78A0DD695550623A42BF41A422EC219012318FE26D2B757F12BDFE046EA4
CB8D35079ABAB6859691FEE1B03483471495035749FFF94D3087529F578DEF518003EA1422F6DE7D4E20259A484D23A9EFC7F4ADB209D
D67D8EDE5BD2AC0CB2682D7CF26A6624A54BCF4E93219ADD89ABA6214820D4BAA5A9A184DD7F8AF3E2BE98C5B63113276B023B92DA5
AADCCD7387B71B6651A0E7E4E42F8790122386AA9A184DD7F8AF3E23CFEC0086B59B6A9D98EB96DFDA496D97D85706A4A810056FE48
AB878EFC1E976DB7504D402F4B96778B45ADE1DF3E217EFFBA566359677AB73F514F1E75F11DBE3E15983BA530E7D5B13A87D1A2ED19
A9A184DD7F8AF3E21D32D652A71B2A49A58F3A30256097DA11388C26E7CBEB12E65B31C485C94DE8179CEACDE9237EF4C426A05E594
E28069E10B19AE173D25A93A546845C5D78C44112031D6D5DE9B4ABA6214820D4BAA5A9A184DD7F8AF3E260C35EC59CD2FAA2435CD
631BFC801AA7C72A1BAE39879C0BF733EDC45DD99F3A9A184DD7F8AF3E2DDA25A6458507ACE3B3CAAC3A4B293A9C6177F7F00EBFB6
924050D9DF661DE8EC204863D819ABF9564498E9F2D72BEFF2E040214C4961D8737821BA1F638BE05FB01E1B382733FC42D6B04AB80D
66218C75E691B9475C5F6CF13AD357057BC6B5864EE113DF2272EF6572101D5E45CB634F3E941FA7B3EA7E636EAEF751C67C82F8E8D9
B618E69826221B2A42D7F694D9E10B19AE173D25A6EB48BD63BFFE0FAFC78722BD9FFA39623B5D40494B96D2A9E10B19AE173D25A188
DA61C8E3401850C400A3144C3547808A0C82C7B8E9863D017852B02FBFE6D62983EBC372B1A8108D832C13F92E88535C213D0FDA1B1A
5C426A05E594E28069E10B19AE173D25A92AD74641E23F21D1D66F1B352AFCCD408B1727FACC2405AA9A184DD7F8AF3E29B3106F31EE
7D473A854D99576FDD5620141A96DEF638FCE4362F90866AED8044E42F8790122386AA9A184DD7F8AF3E20F6BF2E070199426696A900F
EEBC7848B6F72D445F2CB9F0ED160CC32B1A3C40C426A05E594E28069E10B19AE173D25A201E55FC81E8F7CD78FFD98E342897C11AB2B
E505B3E8421C63E936DCCF29058C31D72A3697DA2C89EFC7F4ADB209DD67D8EDE5BD2AC0CB2682D7CF26A6624A54BCF4E93219ADD89
ABA6214820D4BAA5A9A184DD7F8AF3E2BE98C5B63113276B023B92DA5AADCCD7387B71B6651A0E7E4E42F8790122386AA9A184DD7F8
AF3E23CFEC0086B59B6A9D98EB96DFDA496D93F669AB8A34E11706F7B3F762241F749A9A184DD7F8AF3E286587E20CD9A354709F67B1
501183CFC5D6FD3FD6E23B0D4FA9746B8925D4A4FA9A184DD7F8AF3E21D32D652A71B2A49A58F3A30256097DA11388C26E7CBEB1207
58D07B77A47DB34E359C7AE383D69BC426A05E594E28069E10B19AE173D25A93A546845C5D78C44112031D6D5DE9B4ABA6214820D4B
AA5A9A184DD7F8AF3E260C35EC59CD2FAA2435CD631BFC801AA7C72A1BAE39879C0BF733EDC45DD99F3A9A184DD7F8AF3E2DDA25A
6458507ACE3B3CAAC3A4B293A9C6177F7F00EBFB6924050D9DF661DE8EC204863D819ABF9564498E9F2D72BEFF2E040214C4961D873
7821BA1F638BE05FB01E1B382733FC46AA58C2847221D78069144B06DE3755A6C88EADD3B3FCCD6F6572101D5E45CB634F3E941FA7B
3EA7B08783F57D9AD1BAB2071FAB9B93B3C13FF102AD44B6A493B5C341FB37BF525B0A0E4F490BE1D46A4C5B8F691A2020868119A0A
EB9E9BCD4F9D783FEA316723E17976FBB4909040AE279D66AF13B8441582CB00BB30835AB6401E5CDDF295F533AEE31D2677314D288
F2C15BFB16837EF4A779C1E39E4AA1CEE13FABDB2B89D9A7A89ED81EC005BCD416330CFCE5CF716A316FDF29A9CFF3F25490656C80
0BCA582CB00BB30835ABABD19D247E68289A52F1387D978126C967F9BBB890618AF5A0E5136C7DC2892D2460687217D2779B5836D3F
1FFAE8F3B582CB00BB30835ABEE02C59E0AAF8C913339B61F9DDFB7DAC4FF2460869E4876C5DFD5D39E79330D427654226D9E37E72D
7A4C332F59563DF70B3A840877E2B1BF739A2347A73347F7DA9F100EEBC189ADE92F98BE65BCBE29FE1A3DFE89E44EEEBF9C902BBAA
7C2F68CBC48C724B889A53EA148988B56CC52D52743C045F57844F6607DDEA75FE613EAC80E2C02BCEA89B71E52E64D7538DC9B82E
B2740B82C698F43B6A62D770935233D5F10E593D0519511BAAD615B0035D7524B097C29BA39EBEBEDB93425EB7824B9CCDB1397E716
993ED326500615B4B1853A59F760A0E06373BDFE1CC6695A93B15851F56428&template=ct_responsive_ch&language=en

JSON Example request – request parameter before encryption

MerchantID=Generic3DSTest

&MsgVer=2.0

&TransID=1234567890

&RefNr=20200124

&Amount=100

&Currency=EUR

&URLNotify=https://www.computop.com

&URLSuccess=https://www.computop.com

&URLFailure=https://www.computop.com

&billToCustomer=ew0KICAgICJjb25zdW1lciI6IHsNCiAgICAgICAgInNhbHV0YXRpb24iOiAiTXIiLA0KICAgICAgICAiZmlyc3ROYW1lIjogIk5hcG9sZW9uIiwNCiAgICAgICAgImxhc3ROYW1lIjogIkJvbmFwYXJ0ZSIsDQogICAgICAgICJiaXJ0aERhdGUiOiAiMTc2OS0wOC0xNSINCiAgICB9LA0KICAgICJtb2JpbGVQaG9uZSI6IHsNCiAgICAgICAgImNvdW50cnlDb2RlIjogIjMzIiwNCiAgICAgICAgInN1YnNjcmliZXJOdW1iZXIiIDogIjEyMzQ1Njc4OTEwIg0KICAgIH0sDQogICAgImVtYWlsIjogIm5hcG9sZW9uLmJvbmFwYXJ0ZUBmcmFuY2UuY29tIg0KfQ==

&billingAddress=ew0KICAgICJjaXR5IjogIkFqYWNjaW8iLA0KICAgICJjb3VudHJ5Ijogew0KICAgICAgICAiY291bnRyeUEzIjogIkZSQSINCiAgICB9LA0KICAgICJhZGRyZXNzTGluZTEiOiB7DQogICAgICAgICJzdHJlZXQiOiAiRXhpbGVzdHJlZXQiLA0KICAgICAgICAic3RyZWV0TnVtYmVyIjogIjI3MCINCiAgICB9LA0KICAgICJwb3N0YWxDb2RlIjogIjIwMTY3Ig0KfQ==

&shipToCustomer=ew0KICAgICJjb25zdW1lciI6IHsNCiAgICAgICAgInNhbHV0YXRpb24iOiAiTXIiLA0KICAgICAgICAiZmlyc3ROYW1lIjogIkx1ZHdpZyIsDQogICAgICAgICJsYXN0TmFtZSI6ICJYVklJSSIsDQogICAgICAgICJiaXJ0aERhdGUiOiAiMTc1NS0xMS0xNyINCiAgICB9LA0KICAgICJtb2JpbGVQaG9uZSI6IHsNCiAgICAgICAgImNvdW50cnlDb2RlIjogIjMzIiwNCiAgICAgICAgInN1YnNjcmliZXJOdW1iZXIiIDogIjEyMzQ1Njc4OTEwIg0KICAgIH0sDQogICAgImVtYWlsIjogIkx1ZHdpZ0Byb3lhbC5mcmFuY2UuY29tIg0KfQ==

&shippingAddress=ew0KICAgICJjaXR5IjogIlBhcmlzIiwNCiAgICAiY291bnRyeSI6IHsNCiAgICAgICAgImNvdW50cnlBMyI6ICJGUkEiDQogICAgfSwNCiAgICAiYWRkcmVzc0xpbmUxIjogew0KICAgICAgICAic3RyZWV0IjogIlBsYWNlIGRlIGxhIENvbmNvcmRlIiwNCiAgICAgICAgInN0cmVldE51bWJlciI6ICIxIg0KICAgIH0sDQogICAgInBvc3RhbENvZGUiOiAiNzUwMDEiDQp9

&credentialOnFile=ew0KICAgICJ0eXBlIjogew0KICAgICAgICAidW5zY2hlZHVsZWQiOiAiQ0lUIg0KICAgIH0sDQogICAgImluaXRpYWxQYXltZW50IjogdHJ1ZQ0KfQ==

&OrderDesc=Test:0000

——

where:

billToCustomer=ew0KICAgICJjb25zdW1lciI6IHsNCiAgICAgICAgInNhbHV0YXRpb24iOiAiTXIiLA0KICAgICAgICAiZmlyc3ROYW1lIjogIk5hcG9sZW9uIiwNCiAgICAgICAgImxhc3ROYW1lIjogIkJvbmFwYXJ0ZSIsDQogICAgICAgICJiaXJ0aERhdGUiOiAiMTc2OS0wOC0xNSINCiAgICB9LA0KICAgICJtb2JpbGVQaG9uZSI6IHsNCiAgICAgICAgImNvdW50cnlDb2RlIjogIjMzIiwNCiAgICAgICAgInN1YnNjcmliZXJOdW1iZXIiIDogIjEyMzQ1Njc4OTEwIg0KICAgIH0sDQogICAgImVtYWlsIjogIm5hcG9sZW9uLmJvbmFwYXJ0ZUBmcmFuY2UuY29tIg0KfQ==

is base64-encoding of

{

“consumer”:

{ “salutation”: “Mr”, “firstName”: “Napoleon”, “lastName”: “Bonaparte”, “birthDate”: “1769-08-15” },

“mobilePhone”: { “countryCode”: “33”, “subscriberNumber” : “12345678910” },

“email”: “napoleon.bonaparte@france.com”

}

billingAddress=ew0KICAgICJjaXR5IjogIkFqYWNjaW8iLA0KICAgICJjb3VudHJ5Ijogew0KICAgICAgICAiY291bnRyeUEzIjogIkZSQSINCiAgICB9LA0KICAgICJhZGRyZXNzTGluZTEiOiB7DQogICAgICAgICJzdHJlZXQiOiAiRXhpbGVzdHJlZXQiLA0KICAgICAgICAic3RyZWV0TnVtYmVyIjogIjI3MCINCiAgICB9LA0KICAgICJwb3N0YWxDb2RlIjogIjIwMTY3Ig0KfQ==

is base64-encoding of

{

“city”: “Ajaccio”,

“country”: { “countryA3”: “FRA” },

“addressLine1”: { “street”: “Exilestreet”, “streetNumber”: “270” },

“postalCode”: “20167”

}

shipToCustomer=ew0KICAgICJjb25zdW1lciI6IHsNCiAgICAgICAgInNhbHV0YXRpb24iOiAiTXIiLA0KICAgICAgICAiZmlyc3ROYW1lIjogIkx1ZHdpZyIsDQogICAgICAgICJsYXN0TmFtZSI6ICJYVklJSSIsDQogICAgICAgICJiaXJ0aERhdGUiOiAiMTc1NS0xMS0xNyINCiAgICB9LA0KICAgICJtb2JpbGVQaG9uZSI6IHsNCiAgICAgICAgImNvdW50cnlDb2RlIjogIjMzIiwNCiAgICAgICAgInN1YnNjcmliZXJOdW1iZXIiIDogIjEyMzQ1Njc4OTEwIg0KICAgIH0sDQogICAgImVtYWlsIjogIkx1ZHdpZ0Byb3lhbC5mcmFuY2UuY29tIg0KfQ==

is base64-encoding of

{

“consumer”: { “salutation”: “Mr”, “firstName”: “Ludwig”, “lastName”: “XVIII”, “birthDate”: “1755-11-17” },

“mobilePhone”: { “countryCode”: “33”, “subscriberNumber” : “12345678910” },

“email”: “Ludwig@royal.france.com”

}

shippingAddress=ew0KICAgICJjaXR5IjogIlBhcmlzIiwNCiAgICAiY291bnRyeSI6IHsNCiAgICAgICAgImNvdW50cnlBMyI6ICJGUkEiDQogICAgfSwNCiAgICAiYWRkcmVzc0xpbmUxIjogew0KICAgICAgICAic3RyZWV0IjogIlBsYWNlIGRlIGxhIENvbmNvcmRlIiwNCiAgICAgICAgInN0cmVldE51bWJlciI6ICIxIg0KICAgIH0sDQogICAgInBvc3RhbENvZGUiOiAiNzUwMDEiDQp9

is base64-encoding of

{

“city”: “Paris”,

“country”: { “countryA3”: “FRA” },

“addressLine1”: { “street”: “Place de la Concorde”, “streetNumber”: “1” },

“postalCode”: “75001”

}

credentialOnFile=ew0KICAgICJ0eXBlIjogew0KICAgICAgICAidW5zY2hlZHVsZWQiOiAiQ0lUIg0KICAgIH0sDQogICAgImluaXRpYWxQYXltZW50IjogdHJ1ZQ0KfQ==

is base64-encoding of

{

“type”: { “unscheduled”: “CIT” },

“initialPayment”: true

}

Key Parameter / Object

If you do not use your own template, we a new template for the first tests for you. Alll you have to do is add “Template=ct_responsive_ch” to the encrypted data and the cardholderName entered by the customer will automatically be adopted by First Cash Solution for the 3D 2.0 process. For the planned / upcoming 3DS-2.0 rollout, First Cash Solution will adapt the standard templates accordingly and make them available to you.
If you use your own merchant template and the cardholder query is not yet integrated in it, you need to integrate the cardholderName yourself.
Example XSL file:

 <div class="row ccholder"> <span class="label"> <xsl:value-of select="paygate/language/strCCHolder"/> </span> <div class="input"> <input type="text" value="" id="creditCardHolder" name="creditCardHolder"> <xsl:attribute name="value"><xsl:value-of select="paygate/creditCardHolder"/></xsl:attribute> </input> </div> </div>

Example XML file:

For each language used:

<strCCHolder>Cardholdername</strCCHolder>

For PaySSL.aspx | PayNow.aspx, the cardholderName is a key value pair.
For Direct.aspx, the cardholderName is a JSON Parameter of the JSON-Objects “Card“.

JSON Object – browserInfo

For PaySSL.aspx | Paynow.aspx, First Cash Solution captures the browser data on your behalf and there is no need for you to take any action.
For a server-to-server connection via Direct.aspx, the individual additional queries must be implemented in the shop.

JSON Object – accountInfo

The more data you transfer to us, the higher the probability that smooth payment processing (frictionless mode) will take effect.
You should therefore check which data you already have and evaluate internally which data you would like to transfer.

JSON Object – customerInfo (billToCustomer | shipToCustomer)

Please note that the transfer of address data is mandatory for 3D Secure 2.0.
IMPORTANT: If the delivery address is not identical to the billing address, both addresses must be transferred! In the case of digital goods, the billing address is sufficient.

JSON Object – merchantRiskIndicator

We strongly recommend to pass the merchantRiskIndicator (shipping method).
The shipping type is transferred in the JSON object merchantRiskIndicator in the JSON parameter shippingAddressIndicator.
This can have a positive effect on smooth payment processing (frictionless mode).

Use cases for transaction flagging

Scenario 01 – Credit Card One-Time Payment

You offer your customers payment by credit card
Each payment is a one-time payment, and therefore always a newly initiated payment
You do not use a pseudo card number to store and reuse the card data

Credentials on File (CoF)

You must use 3-D Secure
No further adjustments are necessary

Scenario 02 – Credit Card Subscriptions

You offer your customers payment by credit card
Customers enter into a subscription with you that ALWAYS maintains the same amount and payment interval
You use the pseudo card number to store and reuse the card data
IMPORTANT: The following initial payment is subject to the liability shift for you as a merchant. In the case of the subsequent payment, however, this expires, so that there is no liability shift.

Credentials on File (CoF) – Initial Subscription Payment

Applies to PaySSL.aspx + PayNow.aspx
3-D Secure is mandatory
Necessary adjustments:
- Example:
  - JSON object credentialOnFile with JSON parameter recurring (3 keys included)
  - JSON object credentialOnFile with JSON parameter initialPayment and the value “true”
  - Example Initial Subscription Payment:

{

“type”: {

“recurring”: {

“recurringFrequency”: 30,

“recurringStartDate”: “2019-09-14”,

“recurringExpiryDate”: “2020-09-14”

}

“initialPayment”: true

}

CB2A – flexible Subscription

{

“type”: {

“recurring”: {

“recurringFrequency”: 30,

“recurringStartDate”: “2019-09-14”,

“recurringExpiryDate”: “2020-09-14”

}

“initialPayment”: true,

“useCase”: “flexibleAmount”

}

Credentials on File (CoF) – Subsequent Subscription Payment

Applies to Direct.aspx
3D Secure is NOT mandatory
Necessary adjustments:
- Example:
  - Please always send the schemereferenceID from the initial payment so that the downstream systems can link the two transactions accordingly.
  - JSON object credentialOnFile with JSON parameter recurring (3 keys included)
  - JSON object credentialOnFile with JSON parameter initialPayment and value “false”
  - Example Subsequent Subscription Payment:

{

“type”: {

“recurring”: {

“recurringFrequency”: 30,

“recurringStartDate”: “2019-09-14”,

“recurringExpiryDate”: “2020-09-14”

}

“initialPayment”: false

}

CB2A – flexible Subscription

{

“type”: {

“recurring”: {

“recurringFrequency”: 30,

“recurringStartDate”: “2019-09-14”,

“recurringExpiryDate”: “2020-09-14”

}

“initialPayment”: false,

“useCase”: “flexibleAmount”

}

Scenario 03 – Credit Card Recurring Payment / Down Payment / Final Payment

You offer your customers payment by credit card
Customers shop repeatedly in your shop using the same credit card data
You use the pseudo card number to store and reuse the card data
IMPORTANT: The following initial payment is subject to the liability shift for you as a merchant. In the case of the subsequent payment, however, this expires, so that there is no liability shift.

Credentials on File (CoF) – Initial Recurring Payment

Applies to PaySSL.aspx + PayNow.aspx
3D Secure is mandatory
Necessary adjustments:
- Example:
  - JSON object credentialOnFile with JSON parameter unscheduled and the value “CIT”
  - JSON object credentialOnFile with JSON parameter initialPayment and the value “true”
  - Example Initial Recurring Payment:

{

“type”: {

“unscheduled”: “CIT”

“initialPayment”: true

}

Credentials on File (CoF) – Subsequent Recurring Payment

Applies to Direct.aspx
3D Secure is NOT mandatory
Necessary adjustments:
- Example:
  - Please always send the schemereferenceID from the initial payment so that the downstream systems can link the two transactions accordingly
  - JSON object credentialOnFile with JSON parameter unscheduled and the value “MIT”
  - JSON object credentialOnFile with JSON parameter initialPayment and value “false”
  - Example Subsequent Recurring Payment:

{

“type”: {

“unscheduled”: “MIT”

“initialPayment”: false

}

Scenario 04 – Credit Card Account Verification

You offer your customers payment by credit card
In this scenario, you only want to validate the customer’s credit card
You use the pseudo card number to store and reuse the card data
IMPORTANT: Currently and in the future, schemes/card brands want to prevent merchants from carrying out card data validations with a minimum amount (e.g. 1 cent authorization). Therefore, the 1cs Online Payment System offers you the corresponding “ZeroValueAuthentication”. This is controlled by passing the additional parameter “AccVerify” in the encrypted data – see the example below for details.
Please make sure that your credit card acquirer supports this function for you.

Credentials on File (CoF) – Validation Request

Applies to PaySSL.aspx + PayNow.aspx
3D Secure is mandatory
Necessary adjustments:
- Example:
  - Please send the parameter AccVerify=Yes in the encrypted data (for further details please refer to our programming manual)
  - JSON object credentialOnFile with JSON parameter unscheduled and the value “CIT”
  - JSON object credentialOnFile with JSON parameter initialPayment and the value “true”
  - Example Account Verification:

{

“type”: {

“unscheduled”: “CIT”

“initialPayment”: true

}

Scenario 05 – Credit Card Token Storage / Form Prefill – PayNow interface

The processes described below are subject to the liability shift for you as a merchant.

You offer your customers payment by credit card
Customers buy in your shop and you store the credit card data in the form of the pseudo card number

A: When the customer returns, you prefill the credit card form with the saved data. In the case of CIT with initial=false, flagging is used if the merchant prefills the pseudo card number to the customer using a template prefill option.

B: When the customer returns, you prefill the credit card form with the saved data. If the customer deletes the existing card number and stores a new one or, if necessary, adds another card, then the flagging for CIT must be used again (initial=true), if the customer also wants this card to be preassigned.

Credentials on File (CoF) – Initial Payment for Token Storage

Applies to PayNow.aspx
3-D Secure is mandatory
Necessary adjustments:
- Example:
  - JSON object credentialOnFile with JSON parameter unscheduled and the value “CIT”.
  - JSON object credentialOnFile with JSON parameter initialPayment and the value “true”
  - Example Initial Payment for Token Storage:

{

“type”: {

“unscheduled”: “CIT”

“initialPayment”: true

}

Credentials on File (CoF) – Subsequent Payment for Token Storage

Applies to PayNow.aspx
3-D Secure is mandatory
Necessary adjustments:
- Example:
  - JSON object credentialOnFile with JSON parameter unscheduled and the value “CIT”
  - JSON object credentialOnFile with JSON parameter initialPayment and value “false”
  - Please always send the schemereferenceID from the initial payment (COF-CIT-TRUE) so that the downstream systems can link the two transactions accordingly
  - Example subsequent payment für Token Storage:

{

“type”: {

“unscheduled”: “CIT”

“initialPayment”: false

}

Scenario 05 – Credit Card Token Storage / Form Prefill – PaySSL interface (merchant template)

The obligatory control of the initial and recurring payments is managed by 1cs Online Payment System for you. So that we can activate this function for you, please contact the 1cs OPS Helpdesk.

Please note the following requirements in relation to merchant specific or the 1cs Online Payment System standard templates (ct_responsive, Cards_v1).

Applies to PaySSL.aspx
3-D Secure is mandatory
The shift in liability is subject to the liability shift for you as a merchant
Necessary adjustments:
- Please integrate a prefill checkbox using the code snippet provided below
- Please activate (comment in) the code contained in the XSL file for preassigning the pseudo card number
- To preassign the pseudo card number in the template you must transfer unencrypted data, e.g. “PCNrBrand=VISA&Background=VISA&PCNR=xxxxxxxxxxxxx123&PCNrMonth=09&PCNrYear=2025”. For the display to the customer we recommend that only the last three digits match the pseudo card number and thus also the customer’s real card number.
- In order to process the card data at the 1cs OPS you must transfer the valid pseudo card number as request parameter “CCNr” in the encrypted part.
- If the customer decides to save the card data the parameter “prefill=on” is sent to the 1cs Online Payment System. This indicator is reported back to your shop in the response message. You can see whether the customer has agreed to the prefill by the return parameter “prefill=on”.

Java-Script:

// Adds a Change-Event to the checkbox called 'cbPrefill'

$("#cbPrefill").change(function() {

if($("#cbPrefill").is(':checked'))

{ // If the checkbox was activated, the value of hiddenfield with name 'prefill' is set to 'on' $("input[type='hidden'][name='prefill']").val('on'); }

else

{ // If the checkbox was deactivated, the value of hiddenfield with name 'prefill' is deleted again $("input[type='hidden'][name='prefill']").val(''); }

});

// In case of retries (If form gets called a second time due to errors),

// the last status will be set

if($("input[type='hidden'][name='prefill']").val() == 'on') {

$("#cbPrefill").attr('checked', true);

}

XSL

<inputtype="hidden"name="prefill"><xsl:attributename="value"><xsl:value-ofselect="paygate/prefill"/></xsl:attribute></input>

<divid="div_cbPrefill"class="div_cbPrefill">

<inputtype="checkbox"name="cbPrefill"id="cbPrefill"></input>

<span><xsl:value-ofselect="paygate/language/strCCSaveData"disable-output-escaping="yes"/></span>

<divclass="row"></div>

</div>

Scenario 06 – Credit Card Recurring Payment incl. Liability Shift (e.g. Travel business)

IMPORTANT: The following scenario only applies to PCI-certified systems
There are several scenarios for the travel industry that allow recurring payments to also be subject to liability shift
Example:
- Customer books a hotel room via a booking platform, enters his card data and executes 3D Secure 2.0. This is processed via a separate PSP. This transaction only serves to validate the card data -ZeroValueAuthentication-.
- This results in an Authenticate Status = CAVV, which the central booking platform then reports to the hotel operator (and any other service providers such as rental car agencies, insurance agencies, etc.). The hotel operator makes a NON-3DS 2.0 payment via the 1cs Online Payment System, but including the CAVV and any other data. The second transaction also contains the corresponding liability shift.
The basis for this to work and for the liability shift to take place is the passing on of the Authenticate Status (CAVV). This is determined via a so-called “External 3DS Authentication”. Two steps are necessary:

a. The external merchant system that initiated the first payment (AccVerify/ZeroValueAuthentication) stores the authentication status

b. Subsequently, a recurring payment can be made via the 1cs Online Payment System. In this case, the merchant must include the JSON object threeDSData in the JSON data as well as the original card data of the initial authenticate (Card-JSON). The card data must therefore be transferred in its original form from the booking platform to all relevant service providers / agencies in compliance with PCI.
For this purpose a separate section explains the necessary steps.

All necessary technical information can be found in the Multi-party Ecommerce / Agent Model section.

Scenario 07 – Credit Card MoTo (MailOrder / TelephoneOrder) via PaySSL, Direct or PayNow

You offer your customers payment by credit card, which is collected by telephone.
The credit card data is entered in a separate call centre application which triggers a payment via the 1cs Online Payment System using PaySSL.aspx, Direct.aspx or Paynow.aspx.
You use the pseudo card number to store and reuse the card data
IMPORTANT: MoTo payments are not subject to the liability shift as 3D Secure is not possible. (Out of Scope)

Credentials on File (CoF) – Initial MoTo Payment

Applies to PaySSL.aspx, PayNow.aspx und Direct.aspx
3-D Secure is not possible (Out of Scope)
Necessary adjustments:
- Example:
  - JSON object credentialOnFile with JSON parameter unscheduled and the value “MIT”
  - JSON object credentialOnFile with JSON parameter initialPayment and the value “true”
  - Example Initial MoTo Payment:

{

“type”: {

“unscheduled”: “MIT”

“initialPayment”: true

}

Credentials on File (CoF) – Subsequent MoTo Payment

Applies to automated payment initiation via Direct.aspx
3-D Secure is not possible (Out of Scope)
Necessary adjustments:
- Example:
  - Please always send the schemereferenceID from the initial payment so that the downstream systems can link the two transactions accordingly
  - JSON object credentialOnFile with JSON parameter unscheduled and the value “MIT”
  - JSON object credentialOnFile with JSON parameter initialPayment and value “false”
  - Example Subsequent MoTo Payment:

{

“type”: {

“unscheduled”: “MIT”

“initialPayment”: false,

“useCase”: “ucof”

}

Scenario 08 – Credit Card MoTo (MailOrder / TelephoneOrder) via Virtual Terminal

You offer your customers payment by credit card, which is collected by telephone.
The credit card data is entered via Virtual Terminal.
IMPORTANT: MoTo payments are not subject to the liability shift as 3D Secure is not possible. (Out of Scope)

Credentials on File (CoF)

By using the Virtual Terminal no further adjustments are necessary.

Scenario 09 – Batch Processing

The requirement of the card brands to mark recurring transactions correctly is already an older requirement; we provided information on this in January 2019. In the course of the PSD2-SCA implementation, this will become fully mandatory so that recurring transactions can be clearly identified and the downstream systems can recognize why 3D Secure was not processed in these cases. Since in those cases no end customer actively participates in the payment process, as consequence, the implementation is mandatory for all merchants.

Below you will find our descriptions & details, i.e. in the first step the initial payment from the store has to be marked as CredentialOnFile and based on that the recurring batch transactions will follow.

***initial shop transaction or AccountVerification:

On our application page the correct initial flagging (CredentialOnFile) is described for different use cases and the following chapter + scenario will apply to you.

3DS 2.0 Merchant Use-Cases & Testing of 3D-Secure 2.0 EN

Chapter: 2. use cases for transaction identification
Scenario 03 – Credit Card Recurring Payment / Deposit Payment / Final Payment

***Recurring batch submission
Since the schemeReferenceID was generated from the initial store request and reported back, that initial value must be used for all subsequent batch submissions + RTF=M (M=Merchant Initiated Transaction) needs to be included & specified.
Card+processing+EN

Chapter: Batch usage of the interface
affected batch format / action:

CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,<CCExpiry>,<OrderDesc>,<textfeld1>,<textfeld2>,<RTF>,<cardholder>,<transactionID>,<schemeReferenceID>
CC,Authorize,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,<CCExpiry>,<OrderDesc>,<textfeld1>,<textfeld2>,<RTF>,<cardholder>,<transactionID>,<schemeReferenceID>
In the batch request there exists the “transactionID” on the one hand and in addition the “schemeReferenceID” as well and we recommend that you take field schemeReferenceID.

Examples ‒ Batch Versions 1.2 ‒ schemeReferenceID field delivery:

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

The Scheme Identifier must be transferred in batch format by using the TransactionID / schemeReferenceID, i.e. you will receive the schemeReferenceID / TransactionID for the initial 3DS-2.X transaction. This value must then be included in the batch format so that all recurring payments are correctly identified. The field cardHolder must be present but can also be submitted as an empty field and using schemeReferenceID the TransactionID field also empty.

Example:

CC,Sale,999,EUR,987456321,123456789,<VISA>,<0123456789123456>,<052029>,<mein Warenkorb>,,,M,,,<1234567890>

***Token/PCN Mandate – SchemeReferenceID

You can try to submit payments without using a schemeReferenceID, but we cannot prevent card transactions to be declined.
In case of a rejection, we recommend to execute a separate transaction as Card Check (AccVerify=YES) transaction via our …PaySSL.aspx, i.e. the customer receives a payment link which he can use to process an initial 3DS-2.X transaction and the schemeReferenceID is then reported back and can be included in the process of recurring payments again.

Scenario 10 – Extended Transaction Management (ETM)

When using the First Cash Solution ETM, the 1cs Online Payment System takes care of the correct flagging of transactions for you.

Test 3D Secure 2.0 via First Cash Solution

Take the opportunity to test 3D Secure 2.0 now!

While not all downstream systems currently offer 3-D Secure for testing, you can perform a test simulation within the 1cs Online Payment System. This allows you to perform 3-D Secure authentication including different return values.

Please proceed as follows for testing:

Activate 3D Secure 2.0 for your First Cash Solution MerchantID. If you are unsure whether it has already been activated, please contact support@1cs.de
In the encrypted data request, use the default parameter OrderDesc with the value “Test:0000”. This will give you a correspondingly successful authorization after successful authentication.
Perform 3D Secure Authentication
Please ONLY use the available Testcards (expiration date always in the future + CVV/CVC may contain any value)
Depending on the desired scenario (e.g. Browser 3D Secure 2.0 challenge, frictionless browser authentication, etc.), please use the appropriate One-Time Passwords.

10 transStatusReason Codes

Code	Scheme	Description
01	All	card authentication failed
02	All	Unknown device
03	All	Unsupported device
04	All	Exceeds authentication frequency limit
05	All	Expired card
06	All	Invalid card number
07	All	Invalid transaction
08	All	No card record
09	All	Security failure
10	All	Stolen card
11	All	Suspected fraud
12	All	Transaction not permitted for cardholder
13	All	Cardholder not enrolled in service
14	All	Transaction timed out at ACS
15	All	Low confidence
16	All	Medium confidence
17	All	High confidence
18	All	Very high confidence
19	All	Exceeds ACS maximum challenges
20	All	Non-payment transaction not supported
21	All	3RI transaction not supported
22	All	ACS technical issue
23	All	Decoupled Authentication required by ACS but not requested by 3DS Requestor
24	All	3DS Requestor decoupled max expiry time exceeded
25	All	Decoupled Authentication was provided insufficient time to authenticate cardholder. ACS will not make attempt
26	All	Authentication attempted but not performed by the cardholder
80	Visa	Error connecting to ACS
80	Mastercard	Returned on all Data Only authentications
80	American Express	Safekey is not available for this type of card
81	Visa	ACS timed out
81	Mastercard	Challenge exemption accepted
82	Visa	Invalid response from ACS
82	Mastercard	Challenge Mandate requested but could not be performed
83	Visa	System Error response from ACS
83	Mastercard	DS dropped reason code received from DS
84	Visa	Internal Error While Generating CAVV
84	Mastercard	ChallengeCancel populated therefore did not route to Smart Authentication Stand-In (Makes authentication decision when ACS is not available)
85	Visa	VMID not eligible for requested program
86	Visa	Protocol version not supported by ACS
87	Visa	Transaction is excluded from Attempts Processing (includes non- reloadable pre-paid cards and non-payments (NPA))
88	Visa	Requested program not supported by ACS

Name	Anbieter	Zweck	Ablauf
cookie_status	www.firstcashsolution.de	Speichert Ihren Zustimmungsstatus für Cookies auf der aktuellen Domäne.	1 Jahr
pll_language	www.firstcashsolution.de	Speichert Ihre Spracheinstellungen.	1 Jahr
PHPSESSID	www.firstcashsolution.de	In diesem Cookie wird die Session-ID, also eine zufällig generierte Identifikationsnummer für Ihre Sitzung, gespeichert. Dieser Cookie wird – abhängig von Ihrer Browser-Einstellung – beim Schließen eines Tabs oder Fensters, das diesen Cookie gesetzt hat, gelöscht. Dadurch ist es zum Beispiel möglich, zuvor bereits ausgefüllte Felder eines Formulars vom Browser automatisch eintragen zu lassen.	Session
wordpress_test_cookie	www.firstcashsolution.de	Prüft ob Cookies gesetzt werden können	1 Jahr
pum-*	www.firstcashsolution.de	Speichert die Information welches PopUp geschlossen wurde	1 Monat

01	02	03	04	05	06	07	08	09	10	11	12	13	14	15	16	17	18	19	20	21	22
G	R	E	A	T		B	R	A	N	D		L	T	D	*	0	8	1	5	3	7

01	02	03	04	05	06	07	08	09	10	11	12	13	14	15	16	17	18	19	20	21	22
H	.	C	A	L	I	F	O	R	N	I	A		N	O		S	H	O	W

01	02	03	04	05	06	07	08	09	10	11	12	13	14	15	16	17	18	19	20	21	22
F	L	Y		L	O	W		P	L	C		1	2	3	4	5	6	7	8	9	0

01	02	03	04	05	06	07	08	09	10	11	12	13	14	15	16	17	18	19	20	21	22
G	R	E	A	T		B	R	A	N	D		L	T	D	*	0	8	1	5	3	7

01	02	03	04	05	06	07	08	09	10	11	12	13	14	15	16	17	18	19	20	21	22
H	.	C	A	L	I	F	O	R	N	I	A		N	O		S	H	O	W

01	02	03	04	05	06	07	08	09	10	11	12	13	14	15	16	17	18	19	20	21	22
F	L	Y		L	O	W		P	L	C		1	2	3	4	5	6	7	8	9	0

01	02	03	04	05	06	07	08	09	10	11	12	13	14	15	16	17	18	19	20	21	22
G	R	E	A	T		B	R	A	N	D		L	T	D	*	0	8	1	5	3	7

01	02	03	04	05	06	07	08	09	10	11	12	13	14	15	16	17	18	19	20	21	22
H	.	C	A	L	I	F	O	R	N	I	A		N	O		S	H	O	W

01	02	03	04	05	06	07	08	09	10	11	12	13	14	15	16	17	18	19	20	21	22
F	L	Y		L	O	W		P	L	C		1	2	3	4	5	6	7	8	9	0