SDK

SDK

Nous fournissons 2 environnements de travail qui vous permettront de faire vos tests en toute sécurité puis de passer votre compte en production :

L'adresse utilisée est définie automatiquement dans le SDK suivant le mode de fonctionnement demandé au SDK (PRODUCTION ou SANDBOX)

Comment utiliser le SDK

  1. Téléchargez le SDK ici :
  2. Reportez votre choix de SDK dans votre espace API infos et personnalisation
  3. Munissez-vous de votre code boutique et votre clé API que vous pouvez retrouver sur votre tableau de bord, dans la rubrique API infos et personnalisation
  4. Suivez les instructions ci-dessous pour faire votre première connexion avec l'API

Connexion à l'API

Importez le SDK dans votre code puis créez une instance de l'objet en lui précisant :

  • le code boutique
  • la clé API
  • l'environnement

Le code boutique et la clé API peuvent être trouvés sur la page API infos et personnalisation de votre compte. Attention, suivant l'environnement dans lequel vous souhaitez travailler, production ou sandbox, la clé API ne sera pas la même.

Précisez également l'environnement en indiquant 'PRODUCTION' ou 'SANDBOX'.

// new Neadly(code_boutique, cle_api, environnement);
$neadly = new \Neadly\Neadly($boutique, $cle_api, 'SANDBOX');

Formater et encoder ses données

Les données envoyées à Neadly doivent être formatées en JSON avant leur encryption puis envoi.

Ces données peuvent être fournies sous forme de tableau au SDK qui se chargera de transformer les données en JSON.

Le tableau envoyé à l'API doit être formaté comme décrit ci-contre.

Se référer à la page Format des données pour trouver la liste complète des champs obligatoires et optionnels.

Si vous fournissez directement le JSON, il faut passer le 2ème paramètre à "false".

 

La fonction encodeData retourne alors les données transformées dans le bon format et encryptées avec votre clé.

Ces données seront à envoyer en POST à Neadly. 

// Données formatée en Array
$data_array = array(
	"CustomerFirstName" => "Nom",
	"CustomerLastName" => "Prénom",
	...
	"Products" => array(
		"Reference"	=> "produit_1",
		"Name"		=> "Produit 1",
		...
	)
);
$data = $neadly->encodeData($data_array);

// Données formatées en Json
$data_json = '{
	"CustomerFirstName":		"Nom",
	"CustomerLastName":		"Prénom",
	...
	"Products": [
		{
			"Reference": 		"produit_1",
			"Name": 			"Produit 1"
			...
		}
	]
}';
$data = $neadly->encodeData($data_json, false);

Récupérer le lien d'envoi des données

Récupérez ensuite l'URL vers laquelle poster les données à Neadly.

Cett URL sera l'action du formulaire d'envoi des données qui se trouvera sur la page de choix du mode de paiement que vous proposez à votre internaute.

$url = $neadly->getApiUrl();

Afficher le bouton de paiement sur la page de paiement de votre site

Une fois les données encryptées et l'URL d'envoi récupérée, vous pouvez poster directement les données en redirigeant votre internaute sur l'URL de paiement de Neadly.

 

Si vous donnez plusieurs choix de paiement à l'internaute, il faudra placer sur la page de choix de paiement un bouton d'envoi des données à Neadly. Vous pouvez utiliser le format proposé ci-contre.

L'internaute sera alors redirigé vers la page de paiement Neadly après son clic sur le bouton du formulaire.

<form action="<?php echo $url; ?>" method="post">
	<input type="hidden" name="data" value="<?php echo $data;?>" />
	<button type="submit">Payer avec Neadly</button>
</form>

Retour vers les pages de succès ou d'échec

Lorsque la phase de paiement est terminée sur l'interface Neadly, l'internaute est alors redirigé vers une page de succès ou d'échec sur le site marchand.

Ces URLs sont configurables dans votre compte Neadly mais peuvent également être personnalisées à chaque appel à l'API Neadly dans les données passées au SDK.

Pour plus de détails, se rendre ici, rubrique "Gestion des URLs".

{
	"ReturnURL":	"https://domaine_marchand.com",
	"SuccesURL":	"https://domaine_marchand.com/success",
	"FailureURL": 	"https://domaine_marchand.com/echec"
}

Récupérer les données de paiement de façon sécurisée

Lorsqu'une transaction s'achève, avec succès ou échec, l'URL de retour automatique, définie dans vos paramètres de compte est appellée.

Vous recevez les résultats et le détail de la transaction dans une variable $_POST['data'].

Il faut alors demander au SDK de décrypter ces données, comme indiqué ci-contre.

Vous obtiendrez ainsi un tableau avec un code de succès ou d'échec ainsi que les détails de la transaction.

Si la réponse s'avérait corrompue, la fonction decodeData renverrait "false".

 

ParcelId : Id du colis chez Shopiles

BillUrl : Adresse de téléchargement de la facture Shopiles

A noter que ces 2 informations ne seront fournies qu'une fois le compte marchand passé en production.

$neadly = new \Neadly\Neadly($boutique, $cle_api, 'SANDBOX');
$response = $neadly->decodeData($_POST['data']);

// exemple de données retournées
{
    "Order": {
        "CustomerFirstName": "***",
        "CustomerLastName": "***",
        "CustomerEmail": "***",
        "CustomerPhone": ***,
        "CustomerAddressLine1": "***",
        "CustomerAddressLine2": "***",
        "CustomerPostalCode": ***,
        "CustomerCity": "***",
        "CustomerRegion": "***",
        "CustomerCountry": "***",
        "OrderId": ***,
        "OrderPrice": ***,
        "OrderTaxPrice": ***,
        "OrderCurrency": "***",
        "Products": [
            {
                "Reference": ***,
                "Name": "***",
                "Price": ***,
                "TaxPrice": ***,
                "Tax": ***,
                "TaxCode": "***",
                "Quantity": ***,
                "Weight": ***
            }
        ],
        "ReturnURL": "***",
        "SuccesURL": "***",
        "FailureURL": "***"
    },
    "State": "paid",
    "Code": "000000",
    "Message": "Success",
    "Shipping": {
        "Code": "",
        "Name": "NEADLY ***",
        "Address1": "ZA de la Morandière - Bât. 1",
        "Address2": "20 rue de Betnoms",
        "PostalCode": "33185",
        "City": "Le Haillan",
        "CountryCode": "FR"
    },
    "OrderId": ***,
    "CustomerId": "***",
    "ParcelId": ***,        // donnée disponibles uniquement en PROD
    "BillUrl": ***           // données disponibles uniquement en PROD
}

Envoyer la facture à Neadly

Lorsqu'une transaction a été payée par un client, le marchand doit fournir la facture de son achat à Neadly.

Une fonction existe dans le SDK pour simplifier cet envoi. 

$orderId : Id de la commande (voir Format Json)

$pdf_path: URL ou chemin interne vers la facture à envoyer. Le SDK utilise file_get_contents() pour récupérer le contenu de la facture et l'encoder en Base64

$neadly = new \Neadly\Neadly($boutique, $cle_api, 'SANDBOX');
$response = $neadly->sendBill($orderId, $pdf_path);

// exemples de données retournées
{
    "etat": "success",
    "response_code": "OK",
    "success": true,
    "value": "000000",
    "response_message":"OK"
}

{
    "etat": "error",
    "response_code": "KO",
    "success": false,
    "value": 208,
    "response_message": "OrderId with paid transaction not found"
}

Faire une demande de remboursement

Lorsqu'une transaction a été payée, si une demande de remboursement est engagée par l'internaute sur votre site, vous pouvez utiliser la fonctionnalité "remboursement" de notre service.

Une fonction existe dans le SDK pour faire cette demande. 

$orderId : Id de la commande (voir Format Json)

$neadly = new \Neadly\Neadly($boutique, $cle_api, 'SANDBOX');
$response = $neadly->sendRefund($orderId);

// exemples de données retournées
{
"etat": "success",
"response_code": "OK",
"success": true,
"value": "000000",
"response_message":"OK"
}

{
"etat": "error",
"response_code": "KO",
"success": false,
"value": 210,
"response_message": "Waiting for customer's IBAN"
}

{
"etat": "error",
"response_code": "KO",
"success": false,
"value": 211,
"response_message": "Shopiles does not have enough credit to refund the customer"
}

{
"etat": "error",
"response_code": "KO",
"success": false,
"value": 208,
"response_message": "OrderId with paid transaction not found"
}