Amex Recurring

S’abonner


Qu'est-ce que la carte Amex Recurring ?

Cette page est une présentation des fonctionnalités du moyen de paiement American Express Recurring (Amex Recurring) disponible sur Payline. Ce moyen de paiement est particulièrement adapté aux paiements récurrents et par abonnement.

En effet, sur la plateforme de paiement American Express nommée « SmartBill », American Express propose aux marchands de créer un alias de carte qui lui permettra de débiter la carte associée sans à devoir se préoccuper de la vie de la carte : expiration, type ou résiliation d’une carte.

Le moyen de paiement « Amex Recurring » vous permet de débiter une carte American Express sur simple demande de paiement par alias. Le consommateur est sollicité uniquement lors de la phase d’enrôlement pour enregistrer sa carte.

Fonctions monétiques disponibles

Les Web Services que vous pourrez utiliser  :

  • Création de wallet : createWallet
  • Récupère les données d’un portefeuille virtuel : getWallet
  • Désactivation du wallet : disableWallet / enableWallet
  • Enregistre une demande de paiement programmée et réalise le jour indiqué une demande d’autorisation  : doScheduledWalletPayment
  • Récupère les informations d’un dossier de paiement récurrent : getPaymentRecord
  • Recherche  le détail d’une transaction de paiement : getTransactionDetails


Les différents type de notification (notificationType )  , les paramètres  ainsi que  le Web Service à appeler en fonction  du type de notif et des paramètres

  • Wallet         :    retour d'enrollement  AMEX  ou mise à jour wallet
  • BILL            :    retour du résultat du paiement

La cinématique de paiement

Étape 1 : L’enrôlement de la carte American Express

Pour pouvoir utiliser le moyen de paiement AMEX Recurring, vous devez dans un premier temps enregistrer les données cartes American Express sur Payline :

  • Par page Web de paiement
  • Par Web Services
  • Par le TPEV
  • Par fichier

Suite à cet enregistrement, à partir des données que vous nous avez transmises, Payline créé un alias et soumet à American Express une demande d’enrôlement par fichier sous 24h.

L’alias AMEX

Les fonctionnalités de paiement récurrent par American Express reposent sur la création d’un alias pour identifier une carte de paiement.

Vous choisissez un identifiant unique par consommateur. Puis, vous nous transmettez à Payline cet identifiant dans un champ intitulé « walletID » correspondant à un numéro de portefeuille. Payline attribue à chaque carte contenue dans le portefeuille de votre consommateur un numéro index de carte (par exemple 1, 2, 3 etc.).

L’alias de carte transmis à American Express est créé par Payline lors de l’enregistrement des données cartes dans un portefeuille Payline par la concaténation du numéro de portefeuille et de l’index de la carte.

ALIAS Amex = walletID + cardIndex

Vous nous communiquez le numéro de portefeuille. Nous vous recommandons d’utiliser l’identifiant consommateur de votre système d’information comme identifiant du portefeuille client. L’index de la carte est communiqué par Payline. Pour que l’alias soit validé, il est nécessaire d’enrôler la carte American Express au dispositif Amex SmartBill.

Détail de la procédure d’enrôlement

Voici le détail de la procédure d’enrôlement d’une carte American Express :

1. Enregistrement des données carte American Express par web de paiement, webservices createWallet, TPVE ou fichier

2. American Express communique un compte rendu de traitement qui confirme l’éligibilité des cartes sous 24h à Payline.

3. Payline peut vous notifier par email ou par serveur du résultat de l’enrôlement

4. Vous pouvez venir chercher le résultat de l’enrôlement :

a. Sur le centre d’administration Payline

b. Par le web service « getWallet »

Enrôlement d’une carte AMEX depuis les pages de paiement

Payline vous propose des pages web qui permettent d’enregistrer une carte dans un portefeuille virtuel Payline.
Lors de l’appel à cette page, vous devez préciser l’alias qu’il souhaite utiliser (champ walletID) et Payline se charge de faire le lien entre cet alias et la carte qui sera débitée chez American Express (cf. L’alias Amex).
Ces pages sont entièrement personnalisables : charte graphique + URL ; et s’intègrent ainsi parfaitement dans le tunnel d’achat d’une boutique en ligne.
Pour accéder à ces pages de paiement, vous avez à votre disposition deux web services : createWebWallet() et ManageWebWallet()
Lors de création du portefeuille via les pages web de paiement une demande d’autorisation à 1 euro est effectuée. Cette autorisation permet de valider que la carte n’est pas en opposition et qu’elle est bien adossée à un compte American Express.

Enrôlement d’une carte AMEX par Web Service

Payline vous propose une API webservice SOAP qui permet d’enregistrer et mettre à jour une carte dans un portefeuille virtuel Payline. Dans ce cas, vous devez préalablement collectées les données cartes.
La fonction createWallet() permet l’enregistrement d’une carte dans un portefeuille virtuel Payline. Lors de l’appel à cette fonction, vous devez préciser l’alias à utiliser (champ walletID) et Payline se charge de faire le lien entre cet alias et la carte qui sera débité chez American Express (cf. L’alias Amex).

Enrôlement d’une carte AMEX par le TPEV

Payline vous propose une application web conçu pour des téléconseillers et opérateurs backoffice. Elle permet d’enregistrer une carte dans un portefeuille virtuel Payline et d’encaisser ou rembourser des paiements.
Cette application est accessible via l’adresse internet https://homologation-tpv.payline.com.

L’opérateur doit renseigner les données carte Amex dans un second écran. Ces données sont enregistrées dans un portefeuille virtuel Payline. L’identifiant du portefeuille (walletID) est la référence client renseignée dans l’écran.

Enrôlement d’une carte AMEX par fichier

Vous pouvez réaliser la création de portefeuille depuis notre fonctionnalité nommée « Interface batch ». Pour cela, vous devez nous transmettre par un flux sécurisé CFT ou FTPS un fichier contenant 1 à N demande de création de portefeuille via la méthode createWallet

Le format du fichier attendu est décrit dans la spécification PAYLINE-Description_batch interface.

Étape 2 : Réaliser vos paiements avec Amex Recurring

Vous pouvez réaliser vos demandes de paiement AMEX Recurring par Payline :

  • Par fichier : vous pouvez nous transmettre vos demandes de paiements en précisant l’alias et le montant à débiter selon un format de fichier défini dans la spécification « PAYLINE-Description_batch interface-FR-v1.D.pdf »
  • Par web services : vous pouvez appeler les web services doImmediateWalletpayment et doScheduledWalletPayment pour réaliser des paiements immédiats ou programmés.

Vous pouvez suivre vos paiements sur Payline :

  • Par le centre d’administration : le détail de chaque transaction est consultable sur les 11 derniers mois.
  • Par reporting transmis de manière automatique quotidiennement ou générés depuis le centre d’administration.

Détail de la procédure de paiement

Voici le détail d’un exemple de procédure de paiement d’une carte American Express :

1. Le Commerçant transmets à Payline un fichier contenant ses paiements avant 17h pour une prise en compte le jour même par American Express.

2. Payline fournit un fichier compte-rendu consécutivement

3. Payline transmet à American Express les demandes de paiements et récupère les validations

4. Le commerçant consulte le détail des transactions réalisées :

a. Sur le centre d’administration Payline

b. Par reporting

Étape 3 : Suivre les mises à jour de vos cartes

Quand la carte d’un porteur est mise à jour pour les motifs suivants :

  • Nouvelle date d’expiration
  • Nouveau produit
  • Résiliation d’une carte

American Express informe Payline de ces modifications par fichier.

Payline enregistre un statut de la carte propre à chaque mise à jour réalisée par AMEX.

Liste des statuts cartes AMEX

Lors de la création d’un portefeuille, avant confirmation de l’enrôlement par AMEX, le portefeuille est actif et la valeur par défaut du statut est égale à « WR » correspondant à « Waiting Enrolment Result ».

Lors des mises à jour réalisées par AMEX (confirmation d’enrôlement, refus d’enrôlment, carte résiliée par exemple), la valeur de ce statut évolue et peut prendre une valeur décrite dans le tableau ci-dessous :

Statut des cartes Description / Valeur de l’acronyme
EDU

Expiration Date Updated / Date d’expiration mise à jour

PU Product Updated /Produit mis à jour
CC Card Cancelled / Carte Résiliée
EA

Enrollement Accepted / Enrôlement accepté par AMEX

ER

Enrollement Refused/ Enrôlement refusé par AMEX

WR

Wainting Enrolment Result / En attente de la réponse de AMEX

Consulter l'évolution de vos cartes clients

Pour consulter l’évolution de vos cartes clients, nous vous conseillons de configurer les notifications serveurs et/ou email pour être alerté du changement d’état des cartes.

Suite à ces notifications, vous pouvez consulter sur le centre d’administration Payline et par Web services l’état d’une carte AMEX.

Notification email et serveur

Vous pouvez configurer l’envoi d’un email ou/et d’une notification serveur sur le centre d’administration Payline pour être alerté du changement de statut d’une carte dans ces deux cas :

  • Résultat de l’enrôlement accepté ou refusé
  • Résiliation d’une carte

Pour réaliser cette configuration, vous devez vous connecter au centre d’administration Payline, puis rendez-vous dans le menu « Configuration > Vos points de vente > Edition d’un point de vente ». Sur cet écran, vous pouvez cocher deux options correspondantes à ces deux types de notifications :

  • Configuration pour recevoir une notification par email
  • Configuration pour recevoir une notification serveur

Vous pouvez choisir d’être notifié dans les cas suivants :

Cas Notification mail  Notification serveur
Résultat de l’enrôlement d’une carte Amex SmartBill . (coche) (coche)
Désactivation d’une carte à cause d’une résiliation.
(coche)
Expiration d’une carte dans un portefeuille (coche)
Création d’un portefeuille
(coche)


Consulter le statut de votre carte

  • Sur le centre d’administration : Depuis le centre d’administration, vous pouvez consulter le statut d’une carte à partir du menu « Paiement récurrent > Gestion des portefeuilles > Edition d’un portefeuille »
  • Dans nos Web Services : Vous pouvez réaliser un appel au web service « getWallet » pour consulter le statut d’une carte dans le champ « card_status ».

Mail résultat d’enrôlement

Si vous choisissez d’être alerté par email, vous recevrez un email résultat d’enrôlement sur ce modèle :

Mail Version Française Version Anglaise
Sujet Résultat d’enrôlement SmartBill SmartBill enrollement result

Message dans le cas d’un enrôlement accepté

Bonjour

L’enrôlement de votre portefeuille Smartbill suivant a été validé par American Express

N° portefeuille: .

Cordialement

Hello,

The enrollment of your following portfolio “Smartbill” was validated by American Express

N° portfolio: .

Regards

Message dans le cas d’un enrôlement refusé

Bonjour,

L’enrôlement de votre portefeuille Smartbill suivant a été refusé par American Express

N° portefeuille: .

Code de refus :

Message de refus :

Ce portefeuille ainsi que ses dossiers de paiement et ses échéances ont été désactivés.

Cordialement

Hello,

The enrollment of your following portfolio “Smartbill” was refused by American

Express : N° portfolio: < alias du portefeuille >.

Return code : < code_refus >

Message de refus :

This portfolio and its payment records and billing records were disabled

Regards


En cas d’échec d’enrôlement, les champs :

seront remplies par des codes et description AMEX fournis en annexe de cette documentation.

Notification serveur résultat d’enrôlement

Voici les paramètres de la notification que vous recevrez pour vous informer du résultat de l’enrôlement d’une carte :

Paramètre Valeur
notificationType Wallet
walletId EXTERNAL_WALLET_ID
type smartbillEnrollResult
result

Y (si l’enrôlement est accepté)

N (si l’enrôlement est refusé)

resultCode code retour de l’enrôlement

Notification serveur carte résiliée

Voici les paramètres de la notification que vous recevrez pour vous informer de la résiliation d’une carte :


Paramètre Valeur
notificationType Wallet
walletId EXTERNAL_WALLET_ID
type smartBillCanceledCard
CancellationCode motif de la résiliation


Suivre vos paiements AMEX Recurring

Suivi des transactions depuis le back office

Vous pouvez consulter, dans le détail d’une transaction, depuis le centre d’administration Payline, le résultat précis de chacune de vos transactions. Dans le cas d’un enrôlement, vous pouvez consulter le détail de la transaction d’un euro.

L’encart « Historique des statuts » pourra prendre une valeur de la liste fournie en annexe de cette documentation pour préciser les raisons d’un refus d’enrôlement.

Dans les autres cas de transactions, les codes retours consultés seront ceux des codes retours AMEX standards.

Fichiers reporting

Vous pouvez consulter l’ensemble de vos transactions quotidiennement dans les reporting suivants :

  • Fichier « Suivi des transactions »
  • Fichier des paiements

Chacun de ces fichiers peut être transmis de manière automatisée par transfert sécurisé CFT ou FTPS.

Comment réaliser l'intégration dans Payline

1) createWallet


Exemple pour la création du wallet W1 :




2) NOTIFICATION du retour d'enrollement d' AMEX

  • A réception  des retours d' enrollement  d' AMEX.
  • PAYLINE mets à jour le status du wallet à EA ( Enrolment Accepted )  : Enrôlement  Accepté par AMEX.
  • PAYLINE notifie le commerçant sur son URL.


Exemple :

https://xxxxxxxxxx?notificationType=Wallet&walletId=W1&type=smartbillEnrollResult&result=Y&resultCode=S
xxxxxxx= URL de notification du commerçant
notificationType=Wallet
walletId=W1
type=smartbillEnrollResult
result=Y
resultCode=S


  • Le commerçant acquitte la notification si réception alors code retour 200.
  • Sur réception de l'acquittement , PAYLINE stoppe la notification sur le wallet W1.

3)  getWallet   


Exemple pour le wallet W1:



Exemple avec les wallets que nous avions créés ensemble  via le TPEV :





Comment gérer son Portefeuille :

Il est possible de modifier un Portefeuille, de mettre à jour les données privées et/ou les données monétiques à l'aide de la fonction « updatewallet », et il est tout à fait possible de désactiver un Portefeuille à l'aide de la fonction « disableWallet », lorsqu'un portefeuille est désactivé, il n'est plus possible d'effectuer des paiements via celui-ci.

Information du Portefeuille

A tout moment, il est possible d'utiliser les fonctions suivantes qui vous permettent d'interroger votre Portefeuille :

  • « getWallet » cette fonction permet de récupérer les informations qui constituent un portefeuille client ;
  • « getPaymentRecord » cette fonction permet de récupérer les informations d'un dossier de paiement récurrent.

4) disableWallet



Le status du wallet  est à MAN  et le flag  isdisable est à 1 : désactivation  MANuelle



5) doScheduledWalletPayment  


Exemple de la programmation au 06/12/2016 d'un paiement  de 10 € sur le wallet W1 :

  • Pas de rejet technique, le paiement est bien programmé ( code retour 02500 ) et un dossier de paiement est créé.



6)  getPaymentRecord


7) NOTIFICATION du retour  du paiement

  • Réception  du résultat du paiement.
  • PAYLINE mets à jour le dossier de paiement.
  • PAYLINE notifie le commerçant sur son URL.


Exemple  

https://xxxxxxxxxx?notificationType= BILL&paymentRecordId=37xx6 &walletId=W1&transactionId=263xxxxxxx6106&billingRecordDate=20161121&orderRef=TST_commerçant_W1&cardIndex=1&billingRecordId=xxxxxxx

paymentMode=CPT
xxxxxxx= URL de notification du commerçant
notificationType=BILL
paymentRecordId=37xx26
walletId=W1
transactionId = 263xxxxxxx06


  • Les paramètres qui suivent peuvent être différents suivant les types de paiement.
  • Le commerçant acquitte la notification si  réception : code retour 200.
  • Sur réception de l' acquittement , PAYLINE stoppe la notification sur le recordpayment 3xxx6.
  • Pour connaitre le résultat du paiement , le commerçant pourra faire appel au WS vu précédemment getPaymentRecord   ou getTransactionDetails
    • getPaymentRecord(AMEX_REC,3xxx6)
    • getTransactionDetails (26xxxxxxxxx106)


                                                                  
     7.a) getPaymentRecord (AMEX_REC, 37xx26 )



     7.b) getTransactionDetails (263xxxxxx6106 ) avec affichage historique



8)  NOTIFICATION d'un retour de status carte résiliée

  • Réception  d'AMEX d'une mise à jour wallet pour carte résiliée.
  • PAYLINE met à jour le status du wallet à CC ( Card Cancelled )  : carte résiliée.
  • Payline notifiie le commerçant sur son URL.

Exemple  :

https://xxxxxxxxxx?notificationType=Wallet&walletId=W1&type=smartbillCanceledCard&CancellationCode=R999
xxxxxxx= URL de notification le commerçant
notificationType=Wallet
walletId=W1
type=smartbillCanceledCard
CancellationCode=R999

  • Le commerçant acquitte la notification si  réception : code retour 200.
  • sur réception de l'acquittement , PAYLINE stoppe la notification sur le wallet W1




9) A partir du centre d'admin  PAYLINE

    1. Se connecter sur le commerçant
    2. Aller dans le menu Paiement Récurent
    3. Gestion des portefeuilles :  Afficher les portefeuilles actifs ;  nous retrouvons le wallet crée ce jour W1


    1.  Sélectionner le wallet W1 : il y a 3 dossiers de paiement ( 37xx06 , 37xx16 , 37xx26 )


    1. Sélectionner le dossier 37xx26


    1. Sélectionner le dossier 375226 : le paiement est à venir , il est programmé au 06/12/2016  alors que le suivant a été effectué et est remisé

    1. On pourra donc trouver  ce paiement  dans le menu Transactions de paiement ; récupérer l' Id Trans de l' écran ci-dessus : 26337190216106  et effectuer une recherche avec l' identifiant de la transaction ,ce qui donne :


  1. Sélectionner la transaction : 26337190216106




les privatedatas  :


Vous avez d’autres questions ? Envoyer une demande

Commentaires

Réalisé par Zendesk