Cardholder

With 3D Secure V2, it is strongly advised to fill in as many fields as possible. The form is considered to be one of the most important. The scoring of the transaction will therefore be much better, and will avoid strong authentication, while guaranteeing payment by the cardholder's bank.

{
    "lastName": "Janvier",
    "firstName": "Thomas",
    "email": "tjanvier@comnpay.com",
    "phone": "+33606060606",
    "personalPhone": "+33241565858",
    "professionalPhone": "+33707070707",
    "road": "5 Place Albert Durand",
    "road2": "Building B",
    "road3": "flat B315",
    "zipCode": "49100",
    "city": "Angers",
    "country": "France",
    "shipRoad": "11 boulevard Maréchal Foch",
    "shipRoad2": "",
    "shipRoad3": "",
    "shipZipCode": "49100",
    "shipCity": "Angers",
    "shipCountry": "France",
    "customerRef": "numRef001"
}

• This form must be sent in JSON format, then encoded in base 64.
• customerRef is only used for one-click payment
• We advise you to fill in the telephone numbers in international format. This will be particularly useful for SEPA direct debit payments. The telephone number will then already be pre-filled in.

Cardholder Account

With the implementation of 3D Secure V2, it is advised to fill in as many fields as possible.

{
    "chAccDate": "20200130",
    "chAccChange": "20200215",
    "chAccPwChange": "20201001",
    "shipAddressUsage": "20200216",
    "txnActivityDay": 0,
    "txnActivityYear": 12,
    "provisionAttemptsDay": 1,
    "nbPurchaseAccount": 4,
    "suspiciousAccActivity": "01",
    "shipNameIndicator": "01",
}

• This form must be sent in JSON format, then encoded in base 64.
• txnActivityDay : Number of transactions (successful and abandoned) on that cardholder's account in the previous 24 hours
• txnActivityYear : Number of transactions (successful and abandoned) for this cardholder's account in the past year
• provisionAttemptsDay : Attempts to add cards to this cardholder's account
• nbPurchaseAccount : Number of purchases (successful transactions) in the last 6 months

• suspiciousAccActivity :

  • "01" : No suspicious activity
  • "02" : Suspicious activity was observed

• shipNameIndicator :

  • "01" : The account name is similar to the delivery name
  • "02" : The account name is different from the delivery name

Caddy

With the implementation of 3D Secure V2, it is advised to fill in as many fields as possible.

{
    "shipIndicator": "01",
    "deliveryTimeframe": "01",
    "deliveryEmailAddress": "tjanvier@comnpay.com",
    "reorderItemsInd": "01",
    "preOrderPurchaseInd": "01",
    "preOrderDate": "20220520",
    "giftCardAmount": 12,
    "nbGiftCard": 1,
}

• This form must be sent in JSON format, then encoded in base 64.

• shipIndicator : Shipping method chosen for the transaction

  • "01" : Send to the cardholder's billing address
  • "02" : Send to another address verified by the merchant
  • "03" : Send to an address different from the cardholder's billing address
  • "04" : "Clic and collect" : Collection from a local shop
  • "05" : Digital goods (includes online services, electronic gift cards, ...)
  • "06" : Travel and event tickets, undispatched
  • "07" : Other (e.g. games, undelivered digital services, electronic media subscriptions, etc.).

• deliveryTimeframe : Delivery time

  • "01" : Electronic delivery
  • "02" : Same day shipping
  • "03" : Overnight shipping
  • "04" : Shipping in two or more days

• reorderItemsInd : Recommend indicator

  • "01" : First order
  • "02" : Recommend from the same basket

• preOrderPurchaseInd : Pre-order indicator

  • "01" : Merchandise available
  • "02" : Coming soon

• giftCardAmount : For a purchase of prepaid card(s) or gift card(s), the total amount of the purchase of the prepaid card(s) or gift card(s) without the cents (e.g. €12.45 is 12)
• nbGiftCard : For the purchase of prepaid cards or gift cards, the total number of prepaid cards or gift cards/codes purchased. The field is limited to 2 characters

Function of the sec field

The sec value is the result of an algorithm which certifies that the values received by our information system have been correctly authenticated and have not been changed by a third party. The operation is relatively simple:

<?php
  /* Variable containing all fields of your form. (Obviously the secret key is not included.) */
  $array_tpe

   /* Adds the secret key to the values. We only use the secret key to sign the list of values. */
  $array_tpe['key'] = "SECRETE KEY"

  /* Converts the parameter table into a character string. */
  $strWithKey = base64_encode(implode("|", $array_tpe))

  /* Removes the secret key */
  unset($array_tpe['key'])

  /* Calculates an SHA512 hash for the character string representing the values of your table. This hash is the unique signature for your HTML form, if someone else changes the HTML values on your form without recalculating the SEC key, our system will refuse the transaction.
    */
  $array_tpe['sec'] = hash("sha512",$strWithKey)
?>

The secret key must NEVER be present in the HTML form, it is this key which guarantees that no one has modified the values, if you're not sure whether your key has been sent or not, please contact us immediately.

Types of transactions

The transactionType field can accept the following values:

• D : immediate debit on a customer card
• PA : Pre-authorization, payment is only debited from the customer card after confirmation by you (using the API or the Afone Paiement interface)
• P3F : Payment in 3 installments. A PNF folder is created for the customer and the payment schedule is displayed on the payment page
• ALS : Creation of an alias. A card alias is created without debiting the holder. NB: An authorization request for €1 will be made to validate the card information (not remotely collected).
• SUBD : Credit card subscription. This type of transaction allows a fully configurable subscription (See subscription tab).
• SUBS : Direct debit subscription. This type of transaction allows a fully configurable subscription(See subscription tab).
• SDD : SEPA Direct Debit, with one off mandate
• SDDR : SEPA Direct Debit, with recurring mandate
• PISCT : Credit Transfer initiation
• PISICT : Instant Credit Transfer initiation

One-click payment

Once your client is finishing their purchase at your e-shop, you can offer an option to save their card details for the future use.

During an initial payment, the customer enters all required card details and can be asked to perform 3DS authentication. Next time your customer wants to buy something from your shop, their card details will already be pre-filled. For the customer, the buying process will become quicker and much more convenient instead of re-entering the card details every single time.

Here is a real example of use:

During a first payment, the customer is asked to register his card for future payments:

Once the client has given the approval to save their card details, it is our system that actually saves and securely holds the card details and in return, generates a token that will be used to refer back to the given card.

An option for the customer would be saving within the system more than one card; in this case he can choose which card he would like to use to pay:

It’s quick and Easy to be set up, configure it now.

Add the parameter customerRef to the bearer form. Note that this parameter must be unique for each of your customers.

As a reminder, the bearer form provides customer information (name, surname, email, address, ...) that can be useful during a transaction search. customerRef will have to add in this bearer form (JSON format then encoded in base_64)

Bearer form example :

{
    "lastName": "Janvier",
    "firstName": "Thomas",
    "email": "tjanvier@comnpay.com",
    "phone": "+33606060606",
    "personalPhone": "+33241565858",
    "professionalPhone": "+33707070707",
    "road": "5 Place Albert Durand",
    "road2": "Building B",
    "road3": "flat B315",
    "zipCode": "49100",
    "city": "Angers",
    "country": "France",
    "shipRoad": "11 boulevard Maréchal Foch",
    "shipRoad2": "",
    "shipRoad3": "",
    "shipZipCode": "49100",
    "shipCity": "Angers",
    "shipCountry": "France",
    "customerRef": "numRef001"
}

Subscription payment

The subscription payment also called recurring payment makes it possible to collect payments settled by credit card or by iban on a periodic basis. It is essentially offered for subscribing to a good or a service such as internet hosting, the telephone subscription or the subscription to a gym.

This method of payment will limit the risk of unpaid and late payments but also to will retain your customers. Thus, you increase your profitability and facilitate the customer experience, which will no longer have to worry about payment, everything is automatic!

Easily set the recurrence of a payment and define the payment methods according to your needs:

• Deadline period: daily, weekly, or monthly
• Deadline frequency (1, 2, 3, 4, ...) for example every 2 days, every 3 weeks, every 4 months, ...
• Deadline day (if it's week choose Monday, Tuesday, Wednesday, ...) (if it's by month, choose the first of the month, the 2nd of the month, ... )
• Subscription end date: : with possibility of choosing an end date (optional)

Example of subscription configuration:

{
    "nextDeadlineDate": "201803270000000",
    "deadlinePeriod": "S",
    "deadlineFrequency": 3,
    "deadlineDay": 5,
    "subscriptionEndDate": "20180623000000"
}

The subscription will be: Every 3 Friday from 03/27/2018 until 06/23/2018

This new option is offered in email payment, link generation, and is configurable for redirection of the payment page.

Please note that for the use of the payment page, we have created 2 new transaction types: SUBD and SUBS See the different types of transactions

Declined transaction retrieval

This option allows you to invite a customer to retry the payment, when their initial attempt has failed. With this option, which can be activated on your AfonePaiement interface, your customer receives a reminder email (customizable) containing a payment link. Then, you increase your conversion rate

From technical point of view, you need first to fill in an email address to send the reminder. For this, you must enter the email parameter in the customer parameter. Then, you will need to add a command reference (arbitrarily chosen by you) to tell us the command concerned by the raise. This parameter is commandId. You will find these two parameters in the details of the payment form.

Constructor

<?php
function __construct($vad_number = "",
                     $secret_key = "",
                     $urlRetourOK = "",
                     $urlRetourNOK = "",
                     $urlIPN = "",
                     $typeTr = "D")
?>

buildSecretHTML

<?php
function buildSecretHTML($produit="Product",
                         $montant="0.00",
                         $idTransaction="")
?>

Once the secret fields have been generated you will be given the transaction identifier generated in the attributes "idTransaction" (Example : $a->idTransaction;).

validSec

This function validates the authenticity of the message received on your IPN page.

<?php
function validSec($values,
                  $secret_key)
?>

Example of use

A quick example of its use is available in the general documentation.

Download the library

Quick example

Below you will find an example of the use of PSP on your website (call + receipt of the results of the transaction).

<?php
  include("libs/payment.php");
  $a = new Payment("VAD-XXX-XXX",
                    "secret-key",
                    "http://localhost/retour_ok",
                    "http://localhost/retour_nok",
                    "http://localhost/ipn.php",
                    "D"
                   );
?>
<!doctype html>
<html>
<head>
  <title>Exemple</title>
</head>
<body>
  <form method="post" action="https://secure.comnpay.com">
   <?php echo $a->buildSecretHTML("Product",10);?>
   <input type="submit" value="Pay!" />
  </form>
</body>
</html>

<?php
  echo "<pre>";
    print_r($_POST);
  echo "</pre>";
?>

IPN

Implementation of the IPN option implies that you have inserted a new page in your code to validate the transaction based on the data received.

IPN is not an obligatory option, however, if you want to track your transactions effectively (and automatically). We strongly recommend you activate it.

IPN data have a security key ‘sec’ which ensures that your system is the origin of the request you have just received.

<?php
  include("libs/payment.php");
  $a = new Payment("VAD-XXX-XXX",
                    "secret-key",
                    "http://localhost/retour_ok.php",
                    "http://localhost/retour_nok.php"
                    "http://localhost/ipn.php",
                    "D"
                   );
?>
<!doctype html>
<html>
<head>
  <title>Exemple</title>
</head>
<body>
  <form method="post" action="https://secure.comnpay.com">
   <?php echo $a->buildSecretHTML("Product",10);?>
   <input type="submit" value="Pay!" />
  </form>
</body>
</html>

<?php
  include("libs/payment.php");
  if(!validSec($_POST,"secret-key")){
    header('HTTP/1.0 400 Bad Request', true, 400);
    die("ERROR");
  }

  // Displays the values received in POST of the IPN
  echo "<pre>";
    print_r($_POST);
  echo "</pre>";

  // Insert your processes here, order confirmation etc...
?>

The Laravel framework

Laravel is an open-source web framework written in PHP respecting the model-view-controller principle and entirely developed in object-oriented programming.

ComNpay has created an example enabling you to quickly and easily implement the PSP solution for your framework Laravel.

A technical documentation is available for the implementation of ComNpay on Laravel 5: See the documentation

You can download an example of the ComNpay module:

DOWNLOAD