Creating a transaction (PCI and 3D Secure)

If you are PCI-DSS certified, you have the right to collect sensitive information related to the payment method on your website. You can create a new transaction using the Charge/CreatePayment Web Service by transmitting the sensitive information related to the payment method.

The example of integration explains how to create a payment with strong authentication, such as 3D Secure or SafeKey.

Process of payment with 3D Secure authentication

A transaction with strong authentication implies several exchanges:

Buyer's browser

Merchant server

Payment gateway server

Description of the steps:

Step	Description
1	The Buyer transmits the details of the payment method to the merchant server.
2	Call to Charge/CreatePayment to create a new transaction.
3	If 3D Secure authentication is necessary, the Web Service returns a response of V4/Charge/RedirectRequest type.
4	The Merchant redirects the Buyer to the 3D Secure page of his or her bank.
5	Once the buyer has been authenticated, the browser is redirected to the payment gateway.
6	The payment gateway will create the transaction and call the URL that was defined in the merchantPostUrlSuccess parameter during the first call.
7	The Merchant verifies the transaction status and redirects the Buyer to the purchase confirmation page.

The return URLs can be defined with the help of two parameters during step 1:

merchantPostUrlSuccess: if the transaction is authorized.
merchantPostUrlRefused: if the transaction is rejected.

If merchantPostUrlRefused is not defined in case of a rejected transaction, the Buyer is redirected to merchantPostUrlSuccess.

Preparing your environment

If you use PHP with our SDK, we recommend to store your keys in a configuration file.

Example with test keys:

https://github.com/lyra/rest-php-examples/blob/master/www/keys.PCI.php

<?php
/**
 * Get the client
 */
require_once __DIR__ . '/vendor/autoload.php';

/**
 * Define configuration
 */

/* Username, password and endpoint used for server to server web-service calls */
Lyra\Client::setDefaultUsername("69876357");
Lyra\Client::setDefaultPassword("testpassword_DEMOPRIVATEKEY23G4475zXZQ2UA5x7M");
Lyra\Client::setDefaultEndpoint("https://api.payzen.eu");

Make sure you replace them with your personal keys.

For more information, see Server SDKs and Prerequisites.

Initiating the transaction

In order to create a new transaction using a new payment method, one must use the Charge/CreatePayment Web Service:

/doc/en-EN/rest/V4.0/api/kb/authentication.html

https://github.com/lyra/rest-php-examples/blob/master/www/PCI.3DS.php#L9-L50

https://api.systempay.fr/api-payment/V4/Charge/CreatePayment

{
    "amount": 990,
    "currency": "EUR",
    "merchantPostUrlSuccess": "http://mockbin.com/request",
    "merchantPostUrlRefused": "http://mockbin.com/request",
    "paymentForms": [
        {
          "paymentMethodType": "CARD",
          "pan": "4970100000000055",
          "expiryMonth": "11",
          "expiryYear": "21",
          "securityCode": "123"
        }
      ]
    }
}

/**
 * I initialize the PHP SDK
 */
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/keys.PCI.php';
require_once __DIR__ . '/helpers.php';

/** 
 * Initialize the SDK 
 * see keys.php
 */
$client = new Lyra\Client();

/**
 * Define the card to use (we use a 3DS enabled card)
 */
$card = array(
  "paymentMethodType" => "CARD",
  "pan" => "4970100000000022",
  "expiryMonth" => "11",
  "expiryYear" => "21",
  "securityCode" => "123"
);

/**
 * starting to create a transaction
 */
$store = array(
  "amount" => 250, 
  "currency" => "EUR",
  "paymentForms" => array($card),
  "merchantPostUrlSuccess" => "http://mockbin.com/request",
  "merchantPostUrlRefused" => "http://mockbin.com/request",
  "customer" => array(
    "email" => "sample@example.com",
    "orderId" => uniqid("MyOrderId")
));

/**
 * do the web-service call
 */
$response = $client->post("V4/Charge/CreatePayment", $store);

The response will be:

{
    "webService": "Charge/CreatePayment",
    "version": "V4",
    "applicationVersion": "4.6.1",
    "status": "SUCCESS",
    "answer": {
        "redirectUrl": "https://authentication-server-url/buyer-bank",
        "width": 390,
        "height": 434,
        "template": "3dsecure",
        "postData": {
            "MD": "JSESSIONID=f9a1CBA1beF8AbAfFE89bD35.vadpayment01tls;+_CqX06BsfWgStNNUg7VgJ",
            "PaReq": "eJxVUttu2zAM/RXD74skp/EloFW0CYp1QINuSW9+GVSJcYwlcmLJS9yvn+Q6a6sX8VDE4eGh4PK02wZ/sTFVrfOQjWgYoJa1qnSZhw+rm29pGBgrtBLbWmMedmjCSw6rTYM4X6JsG+Rwh8aIEoNK5eHv2eGZxtdm/VQu7WLxUCaP5Y+Qw/3VLzxwGFpx12kUATlDR9HIjdCWg5CH69sFv8iSmFIgA4QdNrdzTvuTAXmHoMUO+bIOUJgusHVg0VggfRZk3WrbdDyaOJozgLbZ8o21+ykhx+NxtBfdG+oRtkD8C5APIfetj4xjOlWK/xzfvNzNi5mMiueCLejqz+SxeFNPBa1zIL4ClLDII8oyGtE0oNk0SqeTBEifB7HzEniW+aHeY9j7FlefHj4nwJnbuGV0PEtSN8EZAZ72bheuwhn4PwaFRjr9w/UhfvbdeyqtsyuR48l6jAJjjC7WGKWxShhbx6+vinmn+yJPX3nbGGM9vwdAPA0ZlkiGhbvoy0f4B/cLwxM=",
            "TermUrl": "https://payment-service-provider-return-url"
        },
        "allowIFrame": true,
        "hideAtStartup": false,
        "hideTimeout": 15,
        "_type": "V4/Charge/RedirectRequest"
    },
    "ticket": null,
    "serverDate": "2019-02-08T09:28:57+00:00",
    "applicationProvider": "NPS",
    "metadata": null,
    "_type": "V4/WebService/Response"
}

If the type of the returned object is not V4/Charge/RedirectRequest but V4/Payment, 3D Secure is not required, and the response contains the transaction details ( Transaction object). For more information, see Creating a transaction (PCI).

More information on the Web Service: PCI/Charge/CreatePayment.

Authentication (3DS)

The Merchant must redirect the Buyer to the authentication page. For this, one must create a form that will be automatically submitted with the following characteristics:

Target URL (action) defined in the redirectUrl parameter.
Invisible fields (hidden input) containing data specified in postData.
The method is always POST.

Example of a redirection form:

https://github.com/lyra/rest-php-examples/blob/master/www/PCI.3DS.php#L74-L83

<form id="goTo3DS" action="https://authentication-server-url/buyer-bank" method="POST">
    <input type='hidden' name='MD' value='JSESSIONID=3f1c1eD7716a696FB1F74d21.vadpayment02tls;+_Z5NVQRqn73uWdF7SOLhL'>
    <input type='hidden' name='PaReq' value='eJxVUttSwjAQ/ZVO3yXpzVJmG8cbozMiKgjqixOTVepACk0q1K83KfWWl(...)'>
    <input type='hidden' name='TermUrl' value='https://payment-service-provider-return-url'>
</form>
<script type="text/javascript">
    document.getElementById('goTo3DS').submit();
</script>

<form id="goTo3DS" action="<?php echo $redirectRequest['redirectUrl'] ?>" method="POST">
<?php
    foreach ($redirectRequest['postData'] as $key => $value) {
        echo "<input type='hidden' name='".htmlentities($key)."' value='".htmlentities($value)."'>\n";
    }
?>
</form>
<script type="text/javascript">
    document.getElementById('goTo3DS').submit();
</script>

Retrieving transaction details

Once your Buyer is authenticated, the transaction is created by the payment gateway. The transaction details are transmitted to the URL defined in merchantPostUrlSuccess or merchantPostUrlRefused, depending on the payment result.

Consultez Analyse du résultat du paiement via le retour navigateur pour plus de détails.