Systempay - Paiement simple par carte bancaire

Ressources

L’accès aux paiements carte peut se faire via :

- Accès aux paiements par carte d’un utilisateur connecté
/api/[domaine_partenaire]/payins/cardpayments

- Accès aux paiements par carte d’un utilisateur appartenant à l’application tierce connectée
/api/[domaine_partenaire]/users/appUserId/payins/cardpayments

1.CardPayment v2

Contient les informations d’un paiement par carte bancaire

Propriété Type Exemple Description
Id Long 123 Id du paiement
OrderId String 456 Identifiant du paiement chez l’application tierce
PaymentDate DateTime 2013-09-10 T15:49:58 .791121+02:00 Date du paiement
Amount Long 2350 Montant du paiement (en centimes)
Fee Long Montant de la commission (la propriété "amount" ne comprend pas le montant de la commission)
Status Int 1 Statut du paiement
0 = En attente
1 = Réalisé
2 = Remboursé
3 = Echoué
4 = En attente de validation
5 = Annulé
6 = En attente de remise
Beneficiary SubAccountRef Objet contenant le détail de receveur
Si non précisé, c’est le sous-compte principal de l’utilisateur connecté qui est utilisé
Message String "Déjeuner au restaurant" Message du paiement
IsMine Bool true Vrai si le titulaire du compte est également le titulaire de la carte bancaire (il s’agit d’un chargement du compte et non pas d’un paiement), Faux si le titulaire de la carte n’est pas le titulaire du compte S-money
ErrorCode Int 0 Code d’erreur pour les paiements échoués, 0 si aucune erreur.
1 = Le commerçant doit contacter la banque du porteur
2 = Paiement refusé
3 = Paiement annulé par le client
4 = Porteur non enrôlé 3D-Secure
5 = Erreur authentification 3D-Secure
6 = Erreur technique Systempay
7 = Transaction inexistante chez le PSP (exemple : fermeture du navigateur sans que l’utilisateur finisse son paiement)
ExtraResults ExtraResults Contient les codes de retour détaillés
UrlReturn String Url de retour client appelée en fin de paiement
UrlCallback String Spécifie l’url de callback serveur appelée en fin de paiement
AvailableCards String "CB ;VISA" Liste des cartes à afficher sur la page d’enregistrement.
Valeurs possibles (à séparer par des ‘ ;’) :
CB
MASTERCARD
MAESTRO
VISA
VISA_ELECTRON
PAYPAL (activé sur demande uniquement)
ECV
SOFORT
Type Int 0 Type du paiement :
0 = Paiement
1 = Remboursement
Card Card Détails de la carte associée au paiement.
A renseigner à la création du paiement si la carte doit être enregistrée. Elle sera liée automatiquement à l’utilisateur si le paramètre « IsMine » est à true.
(option à souscrire auprès de S-money)
PaymentSchedule PaymentSchedule Tableau des échéances de paiement
(option à souscrire auprès de S-money)
Payments Payments Tableau des paiements dans le cas d’un paiement vers plusieurs destinataires
PayerInfo PayerInfo Informations concernant le payeur
Require3DS Bool true Permet d’activer ou désactiver le 3DS, si le paramètre n’est pas transmis, alors le 3DS sera toujours demandé.
(option à souscrire auprès de S-money)
Extraparameters Extraparameters Liste des paramètres permettant d’appliquer un profil prédéfini à la transaction.

2.ExtraResults

Propriété Type Description
BankAuthResult Int Code retour de la demande d’autorisation retournée par la banque émettrice, si disponible
0 = transaction approuvée ou traitée avec succès
2 = contacter l’émetteur de carte
3 = accepteur invalide
4 = conserver la carte
5 = ne pas honorer
7 = conserver la carte, conditions spéciales
8 = approuver après identification
12 = transaction invalide
13 = montant invalide
14 = numéro de porteur invalide
15 = Émetteur de carte inconnu
17 = Annulation client
19 = Répéter la transaction ultérieurement
20 = Réponse erronée (erreur dans le domaine serveur)
24 = Mise à jour de fichier non supportée
25 = Impossible de localiser l’enregistrement dans le fichier
26 = Enregistrement dupliqué, ancien enregistrement remplacé
27 = Erreur en « edit » sur champ de lise à jour fichier
28 = Accès interdit au fichier
29 = Mise à jour impossible
30 = erreur de format
31 = identifiant de l’organisme acquéreur inconnu
33 = date de validité de la carte dépassée
34 = suspicion de fraude
38 = Date de validité de la carte dépassée
41 = carte perdue
43 = carte volée
51 = provision insuffisante ou crédit dépassé
54 = date de validité de la carte dépassée
55 = Code confidentiel erroné
56 = carte absente du fichier
57 = transaction non permise à ce porteur
58 = transaction interdite au terminal
59 = suspicion de fraude
60 = l’accepteur de carte doit contacter l’acquéreur
61 = montant de retrait hors limite
63 = règles de sécurité non respectées
68 = réponse non parvenue ou reçue trop tard
75 = Nombre d’essais code confidentiel dépassé
76 = Porteur déjà en opposition, ancien enregistrement conservé
90 = arrêt momentané du système
91 = émetteur de cartes inaccessible
94 = transaction dupliquée
96 = mauvais fonctionnement du système
97 = échéance de la temporisation de surveillance globale
98 = serveur indisponible routage réseau demandé à nouveau
99 = incident domaine initiateur
RiskControlResult Int Code numérique du résultat des contrôles risques
Null = Pas de contrôle effectué
0 = Tous les contrôles se sont déroulés avec succès
2 = La carte a dépassé l’encours autorisé
3 = La carte appartient à la liste grise du commerçant
4 = Le pays d’émission de la carte appartient à la liste grise du commerçant ou le pays d’émission de la carte n’appartient pas à la liste blanche du commerçant.
5 = L’adresse IP appartient à la liste grise du commerçant
6 = Le code bin appartient à la liste grise du commerçant
7 = Détection d’une e-carte bleue
8 = Détection d’une carte commerciale nationale
9 = Détection d’une carte commerciale étrangère
14 = Détection d’une carte à autorisation systématique
20 = Contrôle de cohérence : aucun pays ne correspond (pays IP, pays carte, pays client)
30 = Le pays de l’adresse IP appartient à la liste grise
99 = Problème technique rencontré par le serveur lors du traitement d’un
des contrôles locaux
ThreedsResult Int Statut final du processus 3D-Secure
0 = statut initial
1 = Statut non applicable (global, raison non détaillée)
2 = Statut non applicable (integrator disabled)
3 = Paiement non e-commerce
4 = Paiement sans 3DS (paiement par identifiant, paypal, cetelem, etc.)
5 = Marchand non enrôlé, pas de 3DS
6 = Erreur technique lors du processus 3DS, pas de 3DS
7 = Porteur non enrôlé, pas de 3DS
8 = Signature invalide
9 = Problème venant de l’ACS
10 = Le processus 3DS s’est déroulé correctement
11 = Le processus 3DS a été fait par l’intégrateur
12 = Problème venant du DS
13 = Timeout lors d’une connexion au DS
14 = Maintien pour la livraison de ce statut
15 = Statut non applicable (3DS présent mais désactivé)
16 = Canal de paiement pour lequel 3DS n’est pas disponible (paiements par fichier...)
98 = L’initialisation du processus 3DS est OK
99 = Statut inconnu
WarrantyResult bool Garantie de paiement

3. SubaccountRef

Cet objet permet d’identifier les comptes entre lesquels les opérations s’effectuent.

Propriété Type Exemple Description
Id Long 98 Identifiant du compte.
AppAccountId String "123" Identifiant du compte fournit par l’appli tierce.
DisplayName String "Jean Dupont" Nom d’affichage du compte
Href Uri "/api/[domainePartenaire]
/accounts/123"		 Uri vers le détail du compte
Propriété Type Exemple Description
Id Long 1 Id de la carte
AppCardId String "card123" Nom de la carte
Name String "Carte bancaire" Nom de la carte
Hint String "597010XXXXXX0009" Masque du numéro de la carte
Network Long 1 UNKNOWN = -1,
AMEX = 0,
CB = 1,
MASTERCARD = 2,
VISA = 3,
MAESTRO = 4,
ECARTEBLEUE = 5,
AUROREMULTI = 6,
BUYSTER = 7,
COFINOGA = 8,
JCB = 9,
ONEY = 10,
ONEY_SANDBOX = 11,
PAYPAL = 12,
PAYPAL_SB = 13,
PAYSAFECARD = 14,
VISA_ELECTRON = 15,
COF3XCB = 16,
COF3XCB_SB = 17,
SOFORT_BANKING = 19,
BANCONTACT = 20,
IDEAL = 21,
POSTFINANCE = 22,
POSTFINANCE_EFIN = 23
Country String "FR" Code ISO du pays de la carte utilisée pour le paiement

4.Card

Propriété Type Exemple Description
Id Long 1 Id de la carte
AppCardId String "card123" Identifiant de la carte chez l’application tierce
Name String "Carte bancaire" Nom de la carte
Hint String "597010XXXXXX0009" Masque du numéro de la carte
Country String "FR" Code ISO du pays de la carte utilisée pour le paiement
ExpiryDate DateTime 2017-07-01T00:00:00 Date d’expiration de la carte (date à partir de laquelle un paiement ne sera plus possible avec cette carte)

5. PaymentSchedule

Le tableau PaymentSchedule permet de gérer des paiements en plusieurs fois.

Propriété Type Exemple Description
SequenceNumber Int 1 Numéro du paiement.
Pour un paiement en 3 fois, la valeur peut être 1, 2 ou 3.
Amount long 150 Montant du paiement de l’échéance
Date DateTime 2013-09-10T
00:00:00.000000
+02:00		 Date à laquelle le paiement sera remis
Status Int 1 Statut du paiement
0 = En attente
1 = Réalisé
2 = Remboursée
3 = Echoué
4 = En attente de validation
5 = Annulé
6 = En attente de remise
Fee long Montant de la commission
(la propriété "amount" ne comprend pas le montant de la commission)

Il est possible de passer à la création d’un paiement soit directement le tableau des échéances, soit l’objet ci-dessous qui calcule automatiquement les montants et dates d’échéance :

Propriété Type Exemple Description
FirstAmount Long 10000 Montant de la première échéance
Count Int 3 Nombre d’échéances
Period Int 30 Nombre de jour entre chaque échéance
FirstFee long Montant de la commission de la première échéance
(la propriété "FirstAmount" ne comprend pas le montant de la commission)

Le calcul des échéances (montant et commission) se fait à l’aide de la règle suivante :

N° d’échéance Montant de l’échéance
1 Montant de la 1ère échéance
2 Valeur entière de [(montant total - montant de la 1ère échéance) / (nombre d’échéance - 1)]
…
N (=nbre d’échéances) Valeur entière de [(montant total - montant de la 1ère échéance) / (nombre d’échéance - 1)] + reste de la division

6. Payerinfo

Propriété Type Exemple Description
Name String "Jean Dupont" Nom et prénom du payeur
Mail String "jean@dupont.fr e-mail du payer

7. Payments

Le tableau Payments permet de gérer la liste des paiements créés lors d’un paiement vers plusieurs destinataires

Propriété Type Exemple Description
OrderId Sring "paiement123" Identifiant du paiement chez l’application tierce
Amount long 1500 Montant du paiement
Status Int 1 Statut du paiement
0 = En attente
1 = Réalisé
2 = Remboursée
3 = Echoué
4 = En attente de validation
5 = Annulé
6 = En attente de remise
Beneficiary SubAccountRef Objet contenant les informations du compte destinataire du paiement.
Fee long 100 Montant de la commission
(la propriété "Amount" ne comprend pas le montant de la commission)

8. Extraparameters

Propriété Type Exemple Description
ProfileName String "directpayment" Un profil est un ensemble de paramètres prédéfinis qui seront appliqués à la transaction si celui-ci est renseigné.
SystempayLanguage String "fr" Paramètre permettant la traduction de la page du formulaire de paiement.
Langues disponibles dans Systempay :
Allemand : de
Anglais : en
Chinois : zh
Espagnol : es
Français : fr
Italien : it
Japonais : ja
Néerlandais : nl
Polonais : pl
Portugais : pt
Russe : ru
Suédois : sv
Turc : tr

Recommandations pour intégrer l’iframe

2.1 Saisie des informations carte

2.1.1 Dimensions de l’iframe

L’iframe fait 390 px X 400 px, ce sont les dimensions recommandées pour l’affichage du protocole de 3-D Secure, ces valeurs ne doivent pas être modifiées idéalement pour conserver un affichage optimal, elles sont valables pour l’ensemble des pages visionnées dans l’iframe.

Ces valeurs sont spécifiées dans le fichier CSS externe qui cible directement l’iframe pour fixer ses dimensions, ici dans l’exemple, le fichier CSS s’intitule « Site.css »

2.1.2 HTML

Un fichier CSS (ici « Site.css ») doit être appelé dans le code html pour customiser l’iframe. Un conteneur (« cntnr-iframe ») peut être nécessaire pour le centrage de l’iframe sur la page.

<link rel="stylesheet" type="text/css" href=" Site.css">
<div class="cntnr-iframe">
  <iframe src="url" id="iframe1" frameborder="0"
scrolling="no"></iframe>
</div>

2.1.3 CSS à l’extérieur de l’iframe (customisation du conteneur parent du formulaire)

1 - Appliquer le background

Il est possible de mettre un background avec la css sur le body par exemple (derrière l’iframe) et de placer un fond avec effet de transparence sur l’iframe (cf l’exemple ci-dessous)

body {
…
background:url('background.gif') no-repeat center center;
background-size: cover;
height:100%;
…
}
#iframe1 {
…
background-color: rgba(0, 0, 0, 0.2);
…
}

2. Centrage de l’iframe

.cntnr-iframe {
position : relative ;
width : 100% ;
height : 100% ;
{
fixer une autre hauteur si l’iframe ne doit pas être
centrée sur l’ensemble de la fenêtre, la hauteur minimale doit être de 400
pixels
}
#iframe1 {
…
width: 390px;
height: 400px;
position: absolute;
left:50%;
top: 50%;
margin-top: -200px; (équivalent à la moitié de la hauteur spécifiée en css (400px))
margin-left:-195px; (équivalent à la moitié de la largeur spécifiée en css (390px))
…
}

3 - Réduire la taille de l’iframe

C’est possible de réduire la taille de l’iframe avec la technique du transform scale. La réduction à 0.82 est vivement recommandée pour les écrans de largeur inférieure à 320px. Cette technique doit être utilisée avec beaucoup de précaution : Il faut éviter de mettre moins de 0.82 pour garder un texte lisible, à l’inverse, une valeur supérieur à 0.82 ne permettrait pas un affichage adapté pour un petit téléphone.

#iframe1 {
…
transform : scale(0.82,0.82);
…
}

2.1.4 CSS à l’intérieur de l’iframe (customisation de formulaire)

D’autres styles css sont chargés à l’intérieur de l’iframe, ça permet le bon affichage des différents éléments de la page se trouvant dans l’iframe.

C’est donc dans ces CSS que se trouvent les styles pour modifier les typos, les couleurs, le positionnement des éléments du formulaire, les styles de la tooltip… l’affichage de l’ensemble des éléments de la page chargée dans l’iframe sont gérés par ces CSS.

Ces styles css se trouvent dans les balises head de la page chargée à l’intérieur de l’iframe et peuvent être modifiés. Les modifications doivent être communiquées à l’équipe S-money.

2.2 Validation

Lorsque le paiement ou l’enregistrement CB a été réalisé, 2 scénarios de validation sont envisageables :

  • L’internaute arrive sur une page de validation qui le redirige automatiquement sur la page
    d’arrivée. La page de validation ne sera pas visible par l’utilisateur car la redirection se fait
    directement.
  • L’internaute est dirigé vers une page qui comporte un bouton de retour, il ne lui reste plus qu’à
    cliquer sur ce bouton pour arriver sur une nouvelle page.

2.2.1 Cas 1 : Validation avec redirection automatique

Il suffit pour la redirection automatique d’intégrer dans le code source de la page de validation une redirection automatique avec le JavaScript ci-dessous qui apparaît dans les balises script se trouvant entre les balises head. Il faut mettre l’adresse prévue pour la redirection à la place de « http://www.example.com »

<head>
    …
   <script>
       function RedirectionJavascript() {
          window.top.location.href = "http://www.example.com";
       }
    RedirectionJavascript();
    </script>
</head>

2.2.2 Cas 2 : Validation avec redirection manuelle à l’aide d’un bouton

1 - HTML

L’attribut target="_parent" du lien est obligatoire pour que la redirection se fasse correctement dans la fenêtre. Dans cet exemple, il y a une div « container » et une div « inner » pour centrer verticalement et horizontalement le contenu de la page.

<body>
 <div class="container">
   <div class="inner ">
     <strong class="title">Bravo !</strong>
     <p class="text">Votre paiement a été effectué avec succès.</p>
           <a  href="http://www.example.com"  target="_parent" class="button">Retour à l'accueil</a>
     </div>
 </div>
</body>

2 - CSS

Le fichier CSS spécifique à la page pourra être inclus dans le code source directement.
Le css ci-dessous permet un centrage vertical et horizontal de manière fluide sur tous les supports (mobiles, tablettes…).

body {
   text-align :center ;
}
.container {
   display:table;
   height:100%;
   width:80%;
   margin:0 auto;
}
.inner {
   display:table-cell;
   padding:50px 0;
   text-align:center;
   vertical-align:middle;
}

Créer un paiement par carte bancaire

Envoi des données de la requête de paiement carte au serveur S-money

Pour créer un paiement par carte bancaire veuillez vous référer à l’exemple présent en marge de droite de cette page.

Envoi des données du paiement réalisé au serveur Tiers

Le serveur tiers doit mettre à disposition une url serveur permettant au serveur S-money de le notifier du résultat de l’exécution du paiement.

L’appel du serveur S-money est effectué en méthode HTTP POST.

Les paramètres de la requête HTTP sont :

Paramètre Type Description
id string OrderId de l’opération
error Int Code d’erreur pour les paiements échoués, 0 si aucune erreur.
1 = Le commerçant doit contacter la banque du porteur
2 = Paiement refusé
3 = Paiement annulé par le client
4 = Porteur non enrôlé 3D-Secure
5 = Erreur authentification 3D-Secure
6 = Erreur technique SystemPay
type Int Type de l’opération
1 = paiement carte
status Int Statut de l’opération
-1 = inconnu
0 = en attente
1 = complété
2 = remboursé
3 = refusé
4 = en attente de validation
5 = Annulé
6 = en attente de remise
sequencenumber Int Numéro de séquence du paiement multiple (si paiement multiple)
userid String Identifiant de l’utilisateur chez l’application tierce
userstatus Int Statut de l’utilisateur
0 = Non confirmé
1 = OK
2 = Gelé
3 = A la volée
4 = En cours de fermeture
5 = Fermé
6 = En attente de KYC (virements bloqués)

Redirection en fin de paiement carte

Le serveur tiers doit mettre à disposition une url permettant au serveur S-money de rediriger le client vers l’environnement tiers.

L’url peut-être soit associée au scheme web (http/https) ou à un scheme privatif dans le cas où l’appel serait effectué à partir d’une application mobile tierce.

Les informations renvoyées le sont à titre purement informatif et ne doivent en aucun cas être utilisées pour la validation du paiement par le serveur tiers.

Les paramètres de la requête HTTP sont :

Paramètre Type Description
Id String OrderId du paiement
type Int Type de l’opération
1 = paiement carte
Result Int Statut de la transaction
0 : Aucune erreur.
2 : Le commerçant doit contacter la banque du porteur.
5 : Paiement refusé.
17 : Annulation client.
30 : Erreur de format de la requête. A mettre en rapport avec la
valorisation du champ vads_extra_result.
96 : Erreur technique lors du paiement.

Fonctionnement de l’iframe

1.1 Processus pour utiliser le mode iframe

L’utilisateur valide le montant de l’opération de paiement carte bancaire, il est alors redirigé vers une page comportant une iframe dans laquelle le formulaire de saisie des données carte est affiché.

1.2 Exemples d’iframes

1.2.1 Exemple 1

Après avoir cliqué sur « Participer », l’utilisateur arrive sur une page proposant de payer, ensuite, il est dirigé vers l’iframe qui affiche le formulaire de paiement par CB.

1.2.2 Exemple 2

Après avoir cliqué sur « Enregistrer », l’utilisateur arrive sur une page contenant une iframe qui va charger en autoload dans l’iframe l’url du formulaire de paiement par CB.

Récupérer la liste des paiements entrants

Pour récupérer la liste des paiements entrants veuillez vous référer à l’exemple présent en marge de droite de cette page.

Récupérer un paiement entrant

Pour récupérer un paiement entrant veuillez vous référer à l’exemple présent en marge de droite de cette page.

Cas d’erreurs :

Code HTTP Code erreur Explication
404 356 Opération introuvable

Rembourser un paiement entrant

Pour rembourser un paiement entrant veuillez vous référer à l’exemple présent en marge de droite de cette page.

Cas d’erreurs :

Code HTTP Code erreur Explication
404 356 Opération introuvable
500 706 Le montant du remboursement dépasse le montant de l’opération originale

Récupérer une échéance de paiement

Pour récupérer une échéance de paiement veuillez vous référer à l’exemple présent en marge de droite de cette page.

Cas d’erreurs :

Code HTTP Code erreur Explication
404 356 Opération introuvable

Rembourser une échéance de paiement

Pour rembourser une échéance de paiement veuillez vous référer à l’exemple présent en marge de droite de cette page.

Cas d’erreurs :

Code HTTP Code erreur Explication
404 356 Opération introuvable
500 706 Le montant du remboursement dépasse le montant de l’opération originale

Annuler une échéance de paiement

Pour annuler une échéance de paiement veuillez vous référer à l’exemple présent en marge de droite de cette page.

Cas d’erreurs :

Code HTTP Code erreur Explication
404 356 Opération introuvable
500 706 Le montant du remboursement dépasse le montant de l’opération originale

Modifier une échéance de paiement

Pour modifier une échéance de paiement veuillez vous référer à l’exemple présent en marge de droite de cette page.

Cas d’erreurs :

Code HTTP Code erreur Explication
404 356 Opération introuvable
500 706 Le montant du remboursement dépasse le montant de l’opération originale