ComNpay

PSP

Introduction

The payment form solution (PSP) allows anyone to access the power of ComNpay in their merchant website. You just need to use one of the libraries present in documentation to implement a configurable and powerful payment solution quickly and easily.

./static/psp.png

Principal

There are 3 steps to installing a PSP on your website:

  • Register for an account at the ComNpay. website (or apply for an account on our registration platform).
  • Retrieve the library corresponding to the language of your website. (Optional) (Do you use a CMS ?)
  • Creation of a page which redirects browsers to the payment form (PSP). This will be made up of a simple HTML FORM with specific fields. (e.g. ComNpay in 30 seconds)

Utilisation

We try to provide libraries which simplify the use of PSP whatever language your website is in, if you can't find the right language for your website please contact us. These libraries are obviously optional, but we would strongly advise you to use them to accelerate the integration time for our solution.

They allow you to call the PSP easily and to confirm the response from the same

To use the PSP you first have to retrieve the connection information from your protected space on the AfonePaiement website. This is available from the ComNpay section under the configuration menu.

Caution, the identifiers (and the secret key) are strictly personal. They should never be disclosed to others.

ComNpay in 30 seconds

The following example shows you how to use ComNpay on your website.

Example PHP but valid in any language:

<?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>

IPN? Detailed examples? Over here

Manual payment form integration

If you want to integrate one of our libraries to use the ComNpay solution, you will need to create an HTML form with the following fields:

Paramètre Description Exemple
montant Transaction amount 10.00
idTPE ComBNpay TPE id DEMO
idTransaction Transaction unique id 123456-DEMO-A456456
idCommande Command reference usable in unsuccessful transaction order_1_123456-DEMO-A456456
devise Money EUR
lang Page page language fr
nom_produit Product's name Mon Produit
urlRetourOK Redirection page after accepted payment http://votresite/landingOK.html
urlRetourNOK Redirection page after refused payment http://votresite/landingNOK.html
urlIPN Learn more about the IPN http://votresite/ipn
data Value not processed by ComNpay, simply returned via the IPN  
typeTr Transaction type D : Debit, PA : Preauthorization, P3F : Payment in 3 installments
sec Value calculated by your server SEC field
titrePreauto Used to customize the title "Pre-authorization information"  
messagePreauto Used to customize the message in the pre-authorization information bubble  
titreAls Used to customize the “Card identification" title  
messageAls to customize the information bubble message when the card is identified  
messageUserFields Allows to customize the message inviting the user to indicate personal information complementary to the translation  
porteur Enables you to send cardholder informations, that you will find on your AfonePaiement backoffice

{

"nom": "Janvier",

"prenom": "Thomas",

"email": "tjanvier@comnpay.com",

"telephone": "+33606060606",

"adresse": "5 Place Albert Durand",

"codePostal": "49100",

"ville": "Angers",

"pays": "France",

"refPorteur: numberRef001"

} JSON to encode in base_64

We advise you to enter the telephone number in international format. This will be useful especially for payment by SEPA direct debit. The phone number will be already pre-filled

abonnement

Allows the setting up of a subscription (full recurring payment) based on multiple parameters

See a full example

{

"dateProchaineEcheance":"20200130000000" (YYYYMMDDHHMMSS)

"periodeEcheances": S, for week (J for day, M for month)

"frequenceEcheances": 3, every 3 weeks (every X day, every x month)

"jourEcheances": 5, every Friday (If S: every Monday, Tuesday, ..., if M : every X of the month)

"dateFinEcheancier":"20200630000000" (YYYYMMDDHHMMSS)

} JSON to encode in base_64

codeTemplate Template code of your payment page (enables you to customize several payment pages for a single account). If blank, default template is used  

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 typeTr field can accept 3 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

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 refPorteur 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. refPorteur will have to add in this bearer form (JSON format then encoded in base_64)

Bearer form example :

{ "nom": "Dupont", "prenom": "Thomas", "email": "t.dupont@comnpay.com", "telephone": "0606060606", "adresse": "5 Place Albert Durand", "codePostal": "49100", "ville": "Angers", "pays": "France", "refPorteur": "numRef001" } JSON to encode in base_64

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:

  • Expiry period: daily, weekly, or monthly
  • Expiry frequency (1, 2, 3, 4, ...) for example every 2 days, every 3 weeks, every 4 months, ...
  • Expiry 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:


The subscription will be: Every 3 Friday from 03/27/218 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 porteur 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 idCommande. You will find these two parameters in the details of the payment form.

Methods available in the libraries

Constructor

Parameter Details
vad_number Serial number of the EPT, information present in the configuration section of your Afone Paiement account
secret_key Private key of your transactions. Caution, NEVER divulge this value to others. The information is present in your Afone Paiement account
urlRetourOK Return URL after a successful payment. (Must be accessible to the user)
urlRetourNOK Return URL after payment failure. (Must be accessible to the user)
urlIPN URL IPN, this URL will be called from our services at the end of the payment process.
typeTr Transaction type, D for Debit, PA for Pre-authorisation, ALS for alias creation (D by default)
<?php
function __construct($vad_number = "",
                     $secret_key = "",
                     $urlRetourOK = "",
                     $urlRetourNOK = "",
                     $urlIPN = "",
                     $typeTr = "D")
?>

buildSecretHTML

Parameter Details
produit Name of the product. Information displayed to the customer on the PSP
montant Amount of the transaction. Cents separator: '.'
idTransaction Optional, UNIQUE transaction identifier. If not specified, an identifier is generated
<?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.

Parametre Détail
values Les valeurs reçu en POST (variables envoyées par notre système)
secret_key Votre clé secrète d'appel à notre systeme.
<?php
function validSec($values,
                  $secret_key)
?>

PHP library

Example of use

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

Download the library

DOWNLOAD

Quick example

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

Call page

<?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>

Return page

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

The possible return values are:

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.

Demonstration

No changes in regards to a call without IPN, except for the additional parameter (in our case: http://localhost/ipn) which represents the page to be called after confirmation of the customer's bank payment.

<?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>

To use this example you should create an ipn.php file (file configured in the example). This will be called automatically after the bank transaction. It will return the following information:

  • idTpe
  • idTransaction
  • montant
  • result (OK / NOK)
  • data
  • sec

The URL of the IPN is called in all cases, whether the payment is successful or not, you should always check the ‘result’ value and the ‘sec’ value before continuing with processing.

Page de reception IPN

<?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