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 à la boutique pour plus de détails.