Dictionnaire des données

Pour Paybox Direct et Direct Plus

L’ensemble des variables Paybox Direct est résumée dans ce tableau. Le détail de chaque variable (format, contenu, exemples) est donné dans les pages qui suivent.

VARIABLE	QUESTION	REPONSE	RESUME
ACQUEREUR	X		Moyen de paiement à utiliser
ACTIVITE	X		Provenance du flux envoyé
ARCHIVAGE	X		Référence archivage
AUTORISATION	X	X	Numéro d’autorisation Pour la requêtetrame Question, utilisé si appel phonie
CODEREPONSE		X	Code réponse concernant l’état de la question traitée : opération acceptée ou refusée.
COMMENTAIRE		X	Messages pour information (ex : messages d’erreur)
CVV	X		Cryptogramme visuel de la carte
DATENAISS	X		Spécifique COFINOGA
DATEQ	X		Date et heure d’envoi
DATEVAL	X		Date de validité de la carte
DEVISE	X		Devise (monnaie)
DIFFERE	X		Nombre de jours pour un paiement différé
ERRORCODETEST	X		Code erreur à renvoyer (pour tests)
ID3D	X		Contexte 3D-Secure renvoyé par la solution RemoteMPI
MONTANT	X		Montant
NUMAPPEL	X	X	Numéro d’appel retourné par Paybox
NUMQUESTION	X	X	Identifiant unique et séquentiel
NUMTRANS	X	X	Numéro de transaction retourné par Paybox
PAYS	X	X	Indication du pays de la carte
PORTEUR	X		Numéro de carte
PRIV_CODETRAITEMENT	X		Spécifique SOFINCO/COFINOGA
RANG	X	X	Numéro de rang fourni par la banque
REFABONNE	X	X	Référence d’une carte enregistrée (Direct Plus)
REFERENCE	X		Référence de la transaction
REMISE		X	Identifiant Paybox de la remise
SHA-1	X	X	Indication que l’empreinte de la carte doit être retournée
SITE	X	X	Numéro de site fourni par la banque
STATUS		X	Etat de la transaction
TYPE	X		Type d’action à réaliser
TYPECARTE	X	X	Indication du type de carte
VERSION	X		Version du protocole

Tableau 1 : Liste des variables PAYBOX DIRECT

Variables d’appel PAYBOX DIRECT

SITE
Format : 7 chiffres. Obligatoire.
C’est le numéro de site (TPE) fourni par la banque du Commerçant.
Exemple : 1999888

RANG
Format : 2 chiffres. Obligatoire.
C’est le numéro de rang (ou « machine ») fourni par la banque du Commerçant.
Exemple : 01

VERSION
Format : 5 chiffres. Obligatoire.
Version du protocole PPPS.
Valeurs :

• 00103 pour Paybox Direct
• 00104 pour Paybox Direct Plus

TYPE
Format : 5 chiffres. Obligatoire.
Paybox Direct permet la réalisation de transactions, mais aussi de toutes les opérations de caisse liées à ces transactions : capture, remboursement, annulation,… Cette variable définit l’action à réaliser.
Dans le cas des requêtes trames de capture (00002) qui suivent une demande d’auto seule, il est conseillé :

• D’attendre quelques instants (quelques secondes) entre la demande d’autorisation seule et la capture
• D’envoyer la capture sur la même plateforme (Nanterre ou Strasbourg) que la demande d’autorisation seule afin d’éviter d’éventuels problèmes de réplication entre les plateformes.

 

CODE	DESCRIPTION	OPTION
00001	Autorisation seule
00002	Débit (Capture)
00003	Autorisation + Capture
00004	Crédit
00005	Annulation
00011	Vérification de l’existence d’une transaction
00012	Transaction sans demande d’autorisation
00013	Modification du montant d’une transaction
00014	Remboursement
00017	Consultation
00051	Autorisation seule sur un abonné	Direct Plus uniquement
00052	Débit sur un abonné	Direct Plus uniquement
00053	Autorisation + Capture sur un abonné	Direct Plus uniquement
00054	Crédit sur un abonné	Direct Plus uniquement
00055	Annulation d’une opération sur un abonné	Direct Plus uniquement
00056	Inscription nouvel abonné	Direct Plus uniquement
00057	Modification abonné existant	Direct Plus uniquement
00058	Suppression abonné	Direct Plus uniquement
00061	Transaction sans demande d’autorisation (forçage)	Direct Plus uniquement

DATEQ
Format : 14 chiffres. Obligatoire.
Date et heure d’envoi de la requête trame (date du jour) sous la forme JJMMAAAAHHMMSS. (jour mois année heure minute seconde).
Utilisé dans les requêtes SQL pour la question du type 11 (format JJMMAAAA)
Exemple : 13042012125959

NUMQUESTION
Format : 10 chiffres (min :1 ; max : 2147483647). Obligatoire.
Identifiant unique de la requête permettant d’éviter les confusions au niveau des réponses en cas de questions multiples et simultanées.
Chaque appel doit avoir un numéro de question unique sur une journée. Il pourra être réinitialisé chaque jour.
Exemple : 0000000001

CLE
Format : 8 à 10 caractères. Obligatoire.
Ce champ permet d’identifier plus précisément l’expéditeur et représente une sécurité supplémentaire sur les échanges PPPS.
La valeur de ce champ correspond au mot de passe du back office qui est remis par fax exclusivement au commerçant sur simple demande auprès du support technique.
NB : Depuis octobre 2013, les mots de passe envoyés par Paybox sont sur 10 caractères.

MONTANT
Format : 10 chiffres. Obligatoire pour les questions de type 1, 2, 3, 4, 5, 11, 12, 13, 14, 51, 52, 53, 54, 55, 56, 57 et 61.
Montant total de la transaction en centimes (sans virgule ni point).
Exemple pour 19€90 : 0000001990

DEVISE
Format : 3 chiffres. Obligatoire pour les questions de type 1, 2, 3, 4, 5, 11, 12, 13, 14, 51, 52, 53, 54, 55, 56, 57 et 61.
Code monnaie de la transaction suivant la norme ISO 4217 (code numérique)
Exemples :

• Euro : 978
• US Dollar : 840
• CFA : 952

Avant d’effectuer un paiement en devises, assurez-vous que votre banque et que votre contrat l’autorisent.

REFERENCE
Format : 1 à 250 caractères. Obligatoire pour les questions de type 1, 2, 3, 4, 5, 11, 12, 51, 52, 53, 54, 55, 56 et 61.
C’est la référence commande côté commerçant (champ libre). Ce champ permet au commerçant de garder un lien entre sa plate-forme de e-commerce et la plate-forme de paiement de Paybox.
Exemple : CMD9542124-01A5G

REFABONNE
Format : 1 à 250 caractères. Obligatoire pour les questions de type 51, 53, 54, 55, 56, 57, 58 et 61.
Référence du commerçant permettant d’identifier clairement l’abonné (profil) correspondant à la transaction.
Exemple : AZERTY1234567

PORTEUR
Format : 19 caractères. Obligatoire pour les questions de type 1, 3, 4, 12, 51, 53, 54, 55, 56, 57 et 61.
Numéro de carte du porteur (client) sans espace, cadré à gauche (Type 1, 2, 3, 12, 56 et 57).
Numéro porteur partiel rendu à Paybox lors de l’inscription ou de la modification (Type 51, 53, 54 et 55)
Exemple : 1111222233334444

DATEVAL
Format : Date (MMAA) Obligatoire pour les questions de type 1, 3, 4, 12, 51, 53, 54, 55, 56, 57 et 61.
Date de fin de validité de la carte.
Exemple : 1213 (décembre 2013)

CVV
Format : 3 ou 4 caractères.
Cryptogramme visuel situé au dos de la carte bancaire.
Remarque : Les cartes AMERICAN EXPRESS ont sur leur recto un CIN (Card Identification Number) sur 4 chiffres.
Exemple : 123

ACTIVITE
Format : 3 chiffres. Valeur par défaut : 024
Il s’agit pour la banque de différencier la provenance des différents flux monétiques envoyés ; ceci ayant pour but de renseigner de la manière la plus correcte possible les champs relatifs à l’ERT (Environnement réglementaire et technique)

Voici les valeurs possibles pour le type d’activité :

CODE	DESCRIPTION
020	Non spécifié
021	Demande par téléphone
022	Demande par correspondance
023	Demande par minitel
024	Demande par internet
027	Paiement récurrent

ARCHIVAGE
Format : jusqu’à 12 caractères alphanumériques
Référence transmise à la banque du Commerçant au moment de la télécollecte. Elle devrait être unique et peut permettre à la banque du Commerçant de lui fournir une information en cas de litige sur un paiement.

DIFFERE
Format : 3 chiffres maximum
Nombre de jours de différé (entre la transaction et sa capture).
A noter qu’il est possible de supprimer cette mise en attente à partir du back office commerçant. Par exemple, une transaction réalisée le 2 novembre et différée jusqu’au 4 novembre, peut être débloquée et envoyée le 3 novembre par action manuelle.
Une valeur par défaut de ce paramètre peut avoir été définie dans la fiche d’inscription. Si ce paramètre est envoyé dans l’appel, la valeur spécifiée dans l’appel est prioritaire sur celle par défaut.
Exemple : 004 pour gérer un différé de 4 jours

NUMAPPEL
Format : 10 chiffres. Obligatoire pour les questions de type 2, 5, 13, 14, 52 et 55.
Ce numéro est remis par Paybox suite à la réalisation d’une transaction.
Pour Paybox System, il se trouve dans les paramètres de retour (IPN).
Pour Paybox Direct, il est présent dans le message de réponse.
Il est aussi visible dans le Back-office.

NUMTRANS
Format : 10 chiffres. Obligatoire pour les questions de type 2, 5, 13, 14, 17 52 et 55.
Ce numéro est remis par Paybox suite à la réalisation d’une transaction.
Pour Paybox System, il se trouve dans les paramètres de retour (IPN).
Pour Paybox Direct, il est présent dans le message de réponse.
Il est aussi visible dans le Back-office.

AUTORISATION
Format : jusqu’à 10 caractères. Utilisable dans les questions de type 1, 3 et 13, 51, 56 et 57.
Numéro d’autorisation fournie par le commerçant suite à un appel phonique auprès de sa banque. Exemple : 123456

PAYS
Format : vide.
Si ce champ est présent (même vide), Paybox Direct renvoie le code pays de la carte dans la réponse.

PRIV_CODETRAITEMENT
Format : 3 chiffres.
Valeur renseignée par le commerçant pour indiquer l’option de paiement qu’il propose au porteur de la carte SOFINCO (ou carte Partenaire-SOFINCO) ou COFINOGA.

DATENAISS
Format : Date JJMMAAAA (8 chiffres).
Date de naissance du porteur pour les cartes COFINOGA.

ACQUEREUR
Format : jusqu’à 16 caractères.
Définit le moyen de paiement utilisé. Les valeurs possibles sont :

• PAYPAL
• EMS
• ATOSBE
• BCMC
• PSC
• FINAREF
• BUYSTER
• 34ONEY

Dans le cas de requêtes Paybox Direct ne concernant pas l’un de ces acquéreurs, ce champ ne doit pas être envoyé.

TYPECARTE
Format : vide
Si ce champ est présent (même vide), Paybox Direct renvoie le type de carte dans la réponse (pour un paiement par carte).

SHA-1
Format : vide
Si ce champ est présent (même vide), Paybox Direct renvoie l’empreinte de la carte dans la réponse (pour un paiement par carte).
Le numéro de carte est hashé avec la méthode SHA-1

ERRORCODETEST
Format : 5 chiffres
Code erreur à retourner lors de l’intégration dans l’environnement de pré-production. Variable non prise en compte dans l’environnement de production.

ID3D
Format : 20 chiffres
Identifiant de contexte Paybox contentant les données d’authentification retournées par le MPI
Ce contexte d’authentification est stocké pendant une durée de 5 minutes.
Au-delà, les applications de Paybox considèreront que la phase d’authentification du porteur est non valide car en timeout.

Variables réponse Paybox Direct

SITE
Format : 7 chiffres.
C’est le numéro de site (TPE) fourni par la banque du Commerçant. Echo de la variable transmise à l’appel.
Exemple : 1999888

RANG
Format : 2 chiffres.
C’est le numéro de rang (ou « machine ») fourni par la banque du Commerçant. Echo de la variable transmise à l’appel.
Exemple : 01

NUMQUESTION
Format : 10 chiffres (min :1 ; max : 2147483647).
Identifiant unique de la requête permettant d’éviter les confusions au niveau des réponses en cas de questions multiples et simultanées.
Chaque appel doit avoir un numéro de question unique sur une journée. Il pourra être réinitialisé chaque jour. Echo de la variable transmise à l’appel.
Exemple : 0000000001

NUMAPPEL
Format : 10 chiffres
Numéro de la requête gérée sur Paybox.
Exemple : 0000782653

NUMTRANS
Format : 10 chiffres
Numéro de la transaction créée sur Paybox.
Exemple : 0000563149

AUTORISATION
Format : jusqu’à 10 caractères maximum (généralement 6 chiffres)
Numéro d’autorisation délivré par le centre d’autorisation de la banque du commerçant si le paiement est accepté.
Exemple : 168753

CODEREPONSE
Format : 5 chiffres
Code réponse concernant l’état de la question traitée : opération acceptée ou refusée.

CODE	DESCRIPTION
00000	Opération réussie.
00001	La connexion au centre d’autorisation a échoué ou une erreur interne est survenue. Dans ce cas, il est souhaitable de faire une tentative sur le site secondaire : ppps1.paybox.com.
001xx	Paiement refusé par le centre d’autorisation. [voir Codes réponses du centre d’autorisation]. En cas d’autorisation de la transaction par le centre d’autorisation de la banque, le résultat “00100” sera en fait remplacé directement par “00000”.
00002	Une erreur de cohérence est survenue.
00003	Erreur Paybox. Dans ce cas, il est souhaitable de faire une tentative sur le site secondaire : ppps1.paybox.com.
00004	Numéro de porteur invalide.
00005	Numéro de question invalide.
00006	Accès refusé ou site / rang incorrect.
00007	Date invalide.
00008	Date de fin de validité incorrecte.
00009	Type d’opération invalide.
00010	Devise inconnue.
00011	Montant incorrect.
00012	Référence commande invalide.
00013	Cette version n’est plus soutenue.
00014	Trame reçue incohérente.
00015	Erreur d’accès aux données précédemment référencées.
00016	Abonné déjà existant (inscription nouvel abonné).
00017	Abonné inexistant.
00018	Transaction non trouvée (question du type 11).
00019	Réservé.
00020	Cryptogramme visuel non présent.
00021	Carte non autorisée.
00022	Plafond atteint
00023	Porteur déjà passé aujourd’hui
00024	Code pays filtré pour ce commerçant
00040	Porteur enrôlé mais non authentifié
00097	Timeout de connexion atteint.
00098	Erreur de connexion interne.
00099	Incohérence entre la question et la réponse. Refaire une nouvelle tentative ultérieurement.

Exemple : 00007 (date invalide)

REFABONNE
Format : jusqu’à 250 caractères
Numéro d’abonné donné dans la requête. Vide (zéros binaires) en contexte hors abonnement.
Exemple : AZERTY1234567

PORTEUR
Format : jusqu’à 19 caractères
Numéro porteur partiel rendu par Paybox lors de l’inscription ou de la modification. Identique au contenu de la requête trame question pour les autres cas.
Exemple : 1111222233334444

COMMENTAIRE
Format : jusqu’à 100 caractères
Messages divers pour information (explications d’erreurs notamment).
Exemple : PAYBOX+PPPS

PAYS
Format : 3 caractères (code ISO3166 alphabétique)
Code pays du porteur de la carte. La valeur « ??? » sera retournée si le code pays est inconnu.
Exemple : FRA

TYPECARTE
Format : jusqu’à 10 caractères
Type de carte utilisée pour le paiement
Exemple : VISA

SHA-1
Format : 40 caractères (SHA-1 codé en hexadécimal)
Empreinte SHA-1 de la carte utilisée.
Exemple : F8BF2903A1149E682BE599C5C20788788256AA46

STATUS
Format : jusqu’à 32 caractères
Envoyé uniquement dans les questions de type 17.
État de la transaction. Les valeurs possibles sont :

• Remboursé,
• Annulé,
• Autorisé,
• Capturé,
• Crédit,
• Refusé,
• Demande de solde (Carte cadeaux),
• Crédit Annulé,
• Rejet support

REMISE
Format : jusqu’à 9 chiffres.
Envoyé uniquement dans les questions de type 17.
Identifiant Paybox de la remise télécollectée.
Exemple : 509625890