Format V1
Chaque fichier doit être composé d’une série d’enregistrements.
On appelle « enregistrement » une liste de paramètres séparés par le caractère « ; », et terminés par un retour chariot.
La structure des fichiers est la suivante :
- Un enregistrement d’en-tête spécifiant des informations sur la transmission.
- Un nombre variable d’enregistrements correspondant chacun à un ordre de paiement.
Le nombre d'enregistrements présents dans le fichier influe directement sur le temps de traitement du fichier ainsi que sur la mise à disposition du fichier de retour. Au-delà de 2000 enregistrements, il est conseillé de générer plusieurs fichiers de paiement
Au-delà de 2000 enregistrements, il est conseillé de générer plusieurs fichiers de paiement.
L'enregistrement d'en-tête
Pos. | Description | Valeurs |
---|---|---|
01 | Version du header | 01 |
02 | Identifiant de la boutique | 12345678 |
03 | Mode | TEST ou PRODUCTION |
04 | Canal | INVOICE |
L'enregistrement de détail
Pos. | Description |
---|---|
01 | Description : Définit l'opération à réaliser. Si le champ est envoyé
à vide, la valeur "PAYMENT" est appliquée par défaut. Type : VARCHAR | Longueur : 32 | Facultatif Équivalent API Formulaire : vads_page_action Équivalent API REST : formAction Valeur possible : PAYMENT |
02 | Description : Référence unique de la facture.
Le seul caractère spécial accepté est le tiret "-". Type : VARCHAR | Longueur : 64 | Obligatoire Équivalent API Formulaire : vads_order_id Équivalent API REST : orderId Ex : CX-1254 |
03 | Description : Montant de la transaction exprimé
dans la plus petite unité de la devise. Le montant ne peut pas être valorisé à 0, sauf si l'opération à réaliser (Position 01) est "REGISTER". Type : NUMERIC | Longueur : 13 | Obligatoire Équivalent API Formulaire : vads_amount Équivalent API REST : amount Ex : 4525 pour 45,25 EUR |
04 | Description : Code numérique de la devise du
paiement (norme ISO 4217). Type : NUMERIC | Longueur : 3 | Obligatoire |Doit correspondre à la devise de la société. Équivalent API Formulaire : vads_currency Équivalent API REST : currency Ex : 978 pour l'euro (EUR) (Voir chapitre Liste des devises supportées en annexes) |
05 | Description : Adresse e-mail de l'acheteur. Type : VARCHAR | Longueur : 255 | Facultatif Équivalent API Formulaire : vads_cust_email Équivalent API REST : customer.email Ex : sample@example.net |
06 | Description : Mode de validation. Pour plus
d'information, consultez le chapitre Paramétrer le mode de
validation par défaut du manuel utilisateur "Gestion des
transactions". Type : NUMERIC | Longueur : 1 | Facultatif |Équivalent API Formulaire : vads_validation_mode Équivalent API REST : cardOptions.manualValidation Valeurs possibles :
Ex : 0 |
07 | Description : Description de la facture à régler. Cette description
sera affichée à l'acheteur après saisie de la référence de la
facture sur le formulaire de collecte de données. Pour guider l’acheteur et le rassurer, la zone "Description" permet au marchand d’afficher à son acheteur des informations précisant la facture. Cette description est affichée lorsque l'acheteur clique sur le symbole "?" à droite du champ de saisie "Référence". Pour être en conformité avec la RGPD, il est conseillé de limiter l'affichage d'informations personnelles dans ce champ. Par exemple, pour le règlement d'un loyer, préciser la période de facturation et la référence du logement plutôt que le nom du locataire. Type : VARCHAR | Longueur : 65 | Facultatif Équivalent API Formulaire : vads_order_description Équivalent API REST : description Ex : My order description |
08 | Description : Date de fin de validité de l'ordre de paiement. Ne
peut pas être antérieure à la date courante et ne peut pas dépasser
90 jours. Si ce paramètre n’est pas envoyé, la valeur appliquée sera
celle définie dans le paramétrage de la boutique (Menu Paramétrage > Boutique, onglet Configuration). Type : NUMERIC | Longueur : 8 | Facultatif Équivalent API Formulaire : N/A Équivalent API REST : expirationDate Ex : 20210603 |
09 | Description : Champ spécifique à l'Amérique Latine. Taux de taxe
appliqué sur l’ensemble de la commande. La valeur doit être le
pourcentage à appliquer (19.6 pour 19.6%). Type : NUMERIC | Longueur : 4 | Facultatif Équivalent API Formulaire : vads_tax_rate Équivalent API REST : taxRate Ex : 19.6 |
10 | Description : Préférence marchand relative à l'authentification 3DS.
Si le champ est envoyé à vide, la valeur "NO_PREFERENCE" est
appliquée par défaut. Type : VARCHAR | Longueur : 32 | Facultatif Équivalent API Formulaire : vads_threeds_mpi Équivalent API REST : strongAuthentication Valeurs
possibles :
Ex : NO_PREFERENCE |
11 | Description : Utilisation du formulaire de collecte de données. Ce
champ doit être valorisé à true si
transmis. Type : BOOLEAN | Longueur : 1 | Facultatif Équivalent API Formulaire : N/A Équivalent API REST : dataCollectionForm Ex : true |
Exemples de fichier
- exemple basique :
01;12345678;TEST;INVOICE
PAYMENT;CX-1254;3000;978;;;;;;;
- exemple avancé :
01;12345678;TEST;INVOICE
PAYMENT;CX-1254;3000;978;sample@example.net;0;My Order Description;20210603;;NO_PREFERENCE;
Téléchargez le pack d'exemples : https://scelliuspaiement.labanquepostale.fr/doc/files/samples/sample-files.zip.
Vous trouverez les fichiers d'exemple dans le dossier INVOICE.