Softwares 3D Secure Integration Guide Documentation

Softwares 3D Secure Integration Guide Documentation

Integration Guide 3D Secure

From 01.01.2021 on two-factor authentication will be implemented as a mandatory requirement for all ecommerce card payment transactions. In order to comply with this obligation, the
operators of credit card networks will use the so called 3D Secure procedure. For you as a merchant it is mandatory to be able to carry out this procedure for your customers from
01.01.2021. In the following you will find a description of the different ways of integration and how the 3D Secure procedure has to be implemented for them.

Please select the integration method you use

• Are you using the checkout form hCO?
• Are you using the checkout form hPF?
• Do you process payments without using a form provided by the Unzer system?

Please note: It is also important in which way debits or preauthorisations (reservations) are made. Even if you use a payment form from Unzer GmbH for the registration of card data, the 3D Secure process will be carried out without a checkout form when the card data are first debited or authorised for the first time. In this case the third way of integration without a form provided by Unzer applies.

Please note also:
If you use recurring payments (subscription payments), be sure to read the section “3D Secure and Recurring Payment”.

3D Secure procedure when using the hCO checkout form

The hCO checkout form is already designed for the 3D Secure procedure. There is no additional action from your side needed for the implementation of the procedure. However, you
have to make sure that your system can handle the corresponding answers of our payment system in case the 3D Secure process is started. In the asynchronous response from the
payment system to your server, the result of the transaction is transmitted and must be evaluated there before a return URL is transmitted to the payment system.

For this purpose the following parameters must be evaluated.

• PROCESSING.RETURN.CODE = 000.200.000
• PROCESSING.RETURN = Transaction+pending
• PROCESSING.RESULT = ACK

Explanation: The status of the transaction is “pending”, the parameter PROCESSING.RESULT
represents only a preliminary result. As long as the 3D Secure process is carried out, the status
remain pending.

The final result of the transaction is then either

•  PROCESSING.RETURN.CODE = 000.000.000

• PROCESSING.RESULT = ACK
  or

• PROCESSING.RETURN.CODE = irgendein Wert ungleich 000.000.000 oder 000.200.000

• PROCESSING.RESULT = NOK

In the first case the transaction has been successfully completed, in the second case it has failed overall. The latter can have various reasons, including a refusal to authenticate. You will
receive more detailed information in the parameters “PROCESSING.RETURN” and “PROCESSING.RETURN.CODE”.
We recommend that you run a test for both messages. For more information on how to do a test and which credit card details you can use for a test, please see below.

3D Secure procedure when using the hPF checkout form

The hPF checkout form is also designed to use the 3DS procedure already. There is no additional action from your side needed for the implementation of the procedure. As described
for the hCO implementation the response from the payment system takes place in two steps, which is why your system must check the value of the PROCESSING.RETURN.CODE
parameter when processing the response.

For this purpose the following parameters must be evaluated.

• PROCESSING.RETURN.CODE = 000.200.000
• PROCESSING.RETURN = Transaction+pending
• PROCESSING.RESULT = ACK

Explanation: The status of the transaction is “pending”, the parameter PROCESSING.RESULT represents only a preliminary result. As long as the 3D Secure process is carried out, the status
remain pending.

The final result of the transaction is then either

• PROCESSING.RETURN.CODE = 000.000.000

• PROCESSING.RESULT = ACK
  or

• PROCESSING.RETURN.CODE = irgendein Wert ungleich 000.000.000 oder 000.200.000

• PROCESSING.RESULT = NOK

In the first case the transaction has been successfully completed, in the second case it has failed overall. The latter can have various reasons, including a refusal to authenticate. You will
receive more detailed information in the parameters “PROCESSING.RETURN” and “PROCESSING.RETURN.CODE”.
We recommend that you run a test for both messages. For more information on how to do a test and which credit card details you can use for a test, please see below.

3D Secure procedure with direct connection

If you do not use a payment form provided by Unzer (formerly heidelpay) to process credit card payments, or if you simply register a card using one of the forms and process the preauthorisation (reservation) or debit as a reference to the registration as a direct communication with the payment system, you must implement the 3D Secure process.

Asynchronous transaction flow:

This is an asynchronous process in which your server receives a forwarding URL (Redirect URL) from our payment system. Your server must forward the customer to this URL so that he can carry out the authentication via 3D Secure procedure. The result of this 3D Secure authentication is reported directly to Unzer by the card issuing bank.

After successful authentication, the transaction is further processed in the Unzer system in the way you already know by sending your system an overall result at the end, to which you reply
with a redirect URL. The payment system will then redirect the customer back to your system using this redirect URL from your system

Please note: In this workflow your system receives two answers from the

payment system:

– One with the status “pending” (PROCESSING.RETURN.CODE=000.200.000 and PROCESSING.RETURN=Transaction+pending) and the redirect parameters to the card-issuing bank of the customer
– One with the final result of the debit or reservation. There are also two redirect URLs mentioned in this process, one from the payment system to which the customer has to be redirected to authenticate at his card issuing bank und one from your system, when receiving the final result, to redirect the customer back into your system.

The following changes will be made to the regular procedure. Please note that due to the implementation of other asynchronous payment methods, such as Paypal, some of these
processes may already exist in your implementation.

1. Response URL
   In the first call (no.2 in the diagram) to the payment system, a “Response URL” must be passed in the frontend group.

Please note: The IDENTIFICATION.REFERENCEID parameter is only relevant if you refer to a registration or other already existing transaction

2. Processing Redirect URL If authentication is required, a redirect URL and other parameters in the redirect group are transferred in the response from the payment system (No. 5 in the diagram).
   

3. Forwarding of the customer to the redirect URL
   If the redirect group is responding with a redirect URL, the customer’s browser must be redirected to this URL (No. 6 in the diagram) to perform authentication. The additional parameters from the redirect group have to be transferred to the external website as POST parameters.
   Please note: Additional parameters are returned in the “PROCESSING.REDIRECT.xxx” group only with 3D Secure Version 1 (even there the number and naming may vary), whereas with 3D Version 2 only a PROCESSING.REDIRECT.URL as displayed below is returned: https://heidelpay.hpcgw.net/AuthService/v1/auth/public/2258_2863FFA4C5241C12E39F37
   CCF/run This means that regardless of the type and number of parameters, the client browser must redirect to the PROCESSING.REDIRECT.URL.
   Below you will find a simple code example of how such a redirect can be executed. The

4. Asynchronous result check
   The result of the authentication is sent asynchronously to your server. The payment system expects a valid URL as response. (No. 12 & 13 in the diagram). For successful or rejected
   payments, a different URL can be responded here by your system.

5. Return path of the customer
   The payment system redirects the customer to the URL provided by the merchant’s system after the authentication process and the payment transaction have been completed.
   Please note: Steps 4.) and 5.) proceed in exactly the same way as you are already familiar with in existing NONE 3D Secure transactions.

3D Secure and Recurring Payment

From the 1st of January 2021, 3D Secure will be mandatory for all e-commerce card transactions. However, since this is hardly applicable for recurring payments, the banking
systems have a separate workflow for this.

For this purpose, the banks distinguish between

• CIT = customer initialised transactions
• MIT = merchant initialised transactions

The first transaction of a card in your merchant account must be authenticated with 3D Secure from 01.01.2021 onwards. Such a successful authentication is a mandatory requirement in
order to be able to subsequently submit further bookings on the same card without 3D Secure. The customer must therefore be forwarded to his card- issuing bank for the first debit in
accordance with the procedure described above and authenticate himself there as the cardholder. If a debit is not planned at the time of the order, for example due to a trial period, a reservation (pre-authorisation) of at least one euro must be made with 3D Secure in the presence of the customer instead. Capturing of this reservation is not necessary.

For existing customers, however, no 3D Secure authentication needs to be made up. If the first successful debit took place before 01.01.2021, the customer record can also be assumed to
have been successfully authenticated. For new customers as of 01.01.2021, on the other hand, 3D Secure authentication is mandatory for the first debit or reservation (pre-authorisation).

Please note: In this respect, the banking system looks at the card data, not the customer data. So if an existing customer uses a new card after 01.01.2021, for example because the previous
one has expired or because he has changed his card-issuing bank, this is a new recurring cycle from the banks’ point of view and must be authenticated with 3D Secure for the first booking.

Once this initial authentication has been successfully carried out, all further transactions are exempt from the obligation to use 3D Secure The prerequisites for recurring payment without 3D Secure are therefore:

• There is at least one successful debit or reservation (pre-authorisation) which was either carried out with 3D Secure or took place before 01.01.2021.
• it is referenced to an existing registration and debit upon submission

To let the payment system know, that this is a recurring payment, the parameter RECURRENCE.MODE=REPEATED must be sent as well. This signals to the system that a
recurring payment is to be reported to the banking systems.

Please note: If the parameter RECURRENCE.MODE=REPEATED is entered when a new card is loaded for the first time, 3D Secure forwarding will be carried out despite this parameter.

Testing the 3D Secure implementation

You can test the 3D Secure connection at any time via our payment system. To do so, use the “CONNECTOR_TEST” mode for a transaction, as shown in the examples above.
Connection data for this test:

System gateway endpoint is either
SGW gateway:
– https://test-heidelpay.hpcgw.net/sgw/gtw – Latin-15 encoded
– https://test-heidelpay.hpcgw.net/sgw/gtwu – UTF-8 encoded
NGW gateway:
– https://test-heidelpay.hpcgw.net/ngw/post

Credit card data for this test:

secret3
  Visa|   4711100000000000|   123|   future date|   3DS – password: secret!33

Please note: For 3D Secure Version 2, you do not need to enter a password, but simply click  on the link ”Click here to complete authentication.
The only way to simulate an error with 3D Secure Version 2 is to let the page with the link time out (approx. 18 minutes).

Read More About This Manual & Download PDF:

References

• Unzer
• test-heidelpay.hpcgw.net/ngw/post
• test-heidelpay.hpcgw.net/sgw/gtw
• test-heidelpay.hpcgw.net/sgw/gtwu

Read User Manual Online (PDF format)

Read User Manual Online (PDF format)  >>

Download This Manual (PDF format)

Download this manual  >>