Protocoles

Le protocole utilisé pour la procédure est HTTPS (HTTP + SSL).

Lors d'une requête, le résultat est fourni au format text/plain.

La première ligne est toujours soit 'OK', soit 'ERREUR'.

S'il s'agit d'un 'OK', ceci signifie que l'étape est validée et des renseignements supplémentaires peuvent être fournis en deuxième ligne.

S'il s'agit d'une ligne 'ERREUR', un problème est survenu et les explications sont données à partir de la deuxième ligne.

Ce protocole est volontairement simple pour garantir un fonctionnement rapide et exempt d'erreurs.

N.B. : Chaque ligne doît se terminer par le caractère '\n' (code ASCII 10).

Lors des échanges de données, et par deux fois, un hash est envoyé. Celui-ci est le résultat d'une fonction de hashage MD5 des données de la transaction, plus des données aléatoires. Ce hash permet de vérifier la bonne origine de la transaction.

Attention : Lors du transfert de ce hash dans une URL, veillez bien à "échapper" les caractères de celui-ci qui pourraient être interprétés comme faisant partie de l'URL. Une fonction existe pour cela dans la plupart des langages, par exemple uri_escape() en Perl. Cet "échappement" est inutile (et interdit) dans les résultat de requêtes.


Fonctionnement de la procédure de paiement d'un achat

Prenons comme hypothèse un achat effectué par un client Freenaute qui choisit comme mode de paiement Free HA. Il s'agit d'une commande de 132,45 € référencée par votre S.I. sous le numéro #2006/564251A. Votre numéro de commerçant (numéro attribué lors de votre inscription et visible sur la page d'information de votre compte) est 10 et l'adresse IP du Freenaute est 81.56.55.113. Le SID (Session ID), ou référence de session du client sur votre site est ABCDEFGH121345678.

1. Votre S.I. doît tout d'abord appeler l'URL suivante : https://achats.free.fr/achats/preachat.pl avec, comme paramètres, votre numéro de commerçant (paramètre id), le montant T.T.C. en centimes d'euros (paramètre montant), le montant H.T. en centimes d'euros (paramètre montant_ht), l'adresse IP du Freenaute sous la forme habituelle de 4 octets séparés par des caractères "point" (e.g. 81.56.55.113, paramètre ip) et la désignation ou référence de l'achat (paramètre desi).

Veillez à ce que cette désignation soir suffisamment explicite car elle apparaîtra sur la facture du Freenaute. Il est conseillé de la limiter à 40 caractères. Les espaces sont autorisés.

Exemple : https://achats.free.fr/achats/preachat.pl?id=10;montant=13245;montant_ht=11074;ip=81.56.55.113;desi=Commande+%232006%2F564251A (Notez l'utilisation de l'échappement d'URI pour la désignation)

Vous recevrez en retour un résultat qui vous permettra de savoir si vous pouvez continuer la transaction. Si le résultat est une erreur, la raison de cette erreur se trouve sur les lignes suivantes. Si le résultat est OK, vous trouverez en deuxième ligne le numéro temporaire de transaction et en troisième ligne un hash qui servira à l'étape suivante.

Exemple de réponse : 
OK
65
$1$zL8Jg5aC$EFLpjki5zJ0cyDvrWcxHz0
2. Vous redirigez le Freenaute vers l'URL suivante : https://achats.free.fr/achats/achat.pl avec, comme paramètres, votre numéro de commerçant (paramètre id), le numéro de transaction temporaire (paramètre old_tid) et le hash sus-mentionné en prenant bien garde à effectuer un échappement URI (paramètre hash). Rajoutez de plus le SID (paramètre sid) pour conserver la trace de la session lors du retour.

Exemple : https://achats.free.fr/achats/achat.pl?id=10;old_tid=65;hash=%241%24zL8Jg5aC%24EFLpjki5zJ0cyDvrWcxHz0;sid=ABCDEFGH121345678 (Notez l'utilisation de l'échappement d'URI pour le hash)

3. Après validation et enregistrement de la transaction, notre site contacte le votre, sur l'URL de confirmation et lui envoie en paramètres le numéro temporaire de transaction (paramètre old_tid), le numéro définitif de transaction (paramètre new_tid), ainsi qu'un nouveau hash (paramètre hash2). Exemple : https://admin.votre-site.fr/confirmation?old_tid=65;new_tid=43;hash2=%241%245J8hEb%2F0%24vcMOpcQKP.uzTILigaLzZ1;sid=ABCDEFGH121345678. N.B. : Le numéro temporaire de transaction et le numéro définitif de transaction n'appartiennent pas à la même séquence. Ils n'ont donc aucun rapport entre eux. Le paramètre sid est simplement le même que celui que vous avez passé précédemment, pour que vous puissiez retrouver à quelle session appartient la transaction.

Cet appel signifie que la transaction est en passe d'être validée et une réponse OK de votre serveur la validera définitivement. Par mesure de sécurité, votre système doît appeler, pendant le traîtement ce cette confirmation l'URL https://achats.free.fr/achats/postachat.pl avec en paramètres votre numéro de commerçant (paramètre id), l'ancien numéro de transaction (paramètre old_tid), le numéro définitif de transaction (paramètre new_tid) ainsi que le paramètre hash2 reçu précédemment. Un résultat OK en provenance de postachat.pl certifiera de la bonne fin de la transaction. Vous n'avez plus qu'à nous le retourner tel quel en résultat de votre script de confirmation.

Pour résumer, notre serveur appelle le votre sur l'URL de confirmation, qui appelle à son tour postachat.pl sur notre serveur, et nous retourne comme résultat un "OK\n" si tout va bien.

4. Notre système renvoie le Freenaute sur l'URL de retour avec en paramètres le résultat de la transaction (paramètre res) et le SID (paramètre sid). Exemple : https://admin.votre-site.fr/retour?res=OK;sid=ABCDEFGH121345678.

Dans le cas d'une annulation par le client, le paramètre res vaudra 'annulation'.

La transaction est terminée.

N.B. : Le renvoi vers l'URL de confirmation ne sert qu'à faire revenir le Freenaute sur votre site. La transaction a été entièrement validée à partir du moment où l'URL de confirmation a renvoyé un 'OK'.

Fonctionnement de la procédure de paiement d'un abonnement



Prenons comme hypothèse un abonnement effectué par un client Freenaute qui choisit comme mode de paiement Free HA. Il s'agit d'une commande de 54,06 € par mois, durant 6 mois, référencée par votre S.I. sous le numéro #2006/412563B. Votre numéro de commerçant (numéro attribué lors de votre inscription et visible sur la page d'information de votre compte) est 10 et l'adresse IP du Freenaute est 81.56.55.113. Le SID ( Session ID ), ou référence de session du client sur votre site est ABCDEFGH121345678.

1. Votre S.I. doît tout d'abord appeler l'URL suivante : https://achats.free.fr/achats/preabo.pl avec, comme paramètres, votre numéro de commerçant (paramètre id), le montant T.T.C. en centimes d'euros à prélever chaque mois que dure l'abonnement ( paramètre montant), le montant H.T. en centimes d'euros correspondant ( paramètre montant_ht), la durée de l'abonnement comptée en mois ( paramètre duree), l'adresse IP du Freenaute sous la forme habituelle de 4 octets séparés par des caractères "point" (e.g. 81.56.55.113, paramètre ip) et la désignation ou référence de l'achat ( paramètre desi).

Veillez à ce que cette désignation soir suffisamment explicite car elle apparaîtra sur la facture du Freenaute. Il est conseillé de la limiter à 40 caractères. Les espaces sont autorisés.

Exemple : https://achats.free.fr/achats/preabo.pl?id=10;montant=5406;montant_ht=4520;duree=6;ip=81.56.55.113;desi=Commande+%232006%2F412563B (Notez l'utilisation de l'échappement d'URI pour la désignation). Si le paramètre duree est égal à 0 (zéro), l'abonnement est à durée indéterminée ; votre S.I. pourra mettre un terme à cet abonnement à tout moment (cf. point 6).

Vous recevrez en retour un résultat qui vous permettra de savoir si vous pouvez continuer la transaction. Si le résultat est une erreur, la raison de cette erreur se trouve sur les lignes suivantes. Si le résultat est OK, vous trouverez en deuxième ligne le numéro temporaire de transaction et en troisième ligne un hash qui servira à l'étape suivante.

Exemple de réponse : 
OK
65
$1$zL8Jg5aC$EFLpjki5zJ0cyDvrWcxHz0
2. Vous redirigez le Freenaute vers l'URL suivante : https://achats.free.fr/achats/abo.pl avec, comme paramètres, votre numéro de commerçant (paramètre id), le numéro de transaction temporaire (paramètre old_tid) et le hash sus-mentionné en prenant bien garde à effectuer un échappement URI (paramètre hash). Rajoutez de plus le SID (paramètre sid) pour conserver la trace de la session lors du retour.

Exemple : https://achats.free.fr/achats/abo.pl?id=10;old_tid=65;hash=%241%24zL8Jg5aC%24EFLpjki5zJ0cyDvrWcxHz0;sid=ABCDEFGH121345678 (Notez l'utilisation de l'échappement d'URI pour le hash)

3. Après validation et enregistrement de la transaction, notre site contacte le votre, sur l'URL de confirmation et lui envoie en paramètres le numéro temporaire de transaction (paramètre old_tid), le numéro définitif de transaction (paramètre new_tid), ainsi qu'un nouveau hash (paramètre hash2). Exemple : https://admin.votre-site.fr/confirmation?old_tid=65;new_tid=43;hash2=%241%245J8hEb%2F0%24vcMOpcQKP.uzTILigaLzZ1;sid=ABCDEFGH121345678. N.B. : Le numéro temporaire de transaction et le numéro définitif de transaction n'appartiennent pas à la même séquence. Ils n'ont donc aucun rapport entre eux. Le paramètre sid est simplement le même que celui que vous avez passé précédemment, pour que vous puissiez retrouver à quelle session appartient la transaction.

Cet appel signifie que la transaction est en passe d'être validée et une réponse OK de votre serveur la validera définitivement. Par mesure de sécurité, votre système doît appeler, pendant le traîtement ce cette confirmation l'URL https://achats.free.fr/achats/postabo.pl avec en paramètres votre numéro de commerçant (paramètre id), l'ancien numéro de transaction (paramètre old_tid), le numéro définitif de transaction (paramètre new_tid) ainsi que le paramètre hash2 reçu précédemment. Un résultat OK en provenance de postabo.pl certifiera de la bonne fin de la transaction. Vous n'avez plus qu'à nous le retourner tel quel en résultat de votre script de confirmation.

Pour résumer, notre serveur appelle le votre sur l'URL de confirmation, qui appelle à son tour postabo.pl sur notre serveur, et nous retourne comme résultat un "OK\n" si tout va bien.

4. Notre système propose au Freenaute de retourner sur l'URL de retour avec en paramètres le résultat de la transaction (paramètre res) et le SID (paramètre sid). Exemple : https://admin.votre-site.fr/retour?res=OK;sid=ABCDEFGH121345678.

Dans le cas d'une annulation par le client, le paramètre res vaudra 'annulation'.

La transaction est terminée.

N.B. : Le renvoi vers l'URL de confirmation ne sert qu'à faire revenir le Freenaute sur votre site. La transaction a été entièrement validée à partir du moment où l'URL de confirmation a renvoyé un 'OK'.

5. À tout moment, votre S.I. peut vérifier la validité d'un abonnement en appelant l'URL https://achats.free.fr/achats/test_abo.pl avec en paramètres votre numéro de commerçant (paramètre id) et le numéro d'abonné concerné (paramètre abo). Ce numéro d'abonnement correspond au numéro de transaction définitif qui a été renvoyé lors de la procédure d'abonnement.

Le résultat, s'il est OK donne en deuxième ligne le nombre de secondes avant la fin de l'abonnement. Sinon, s'il s'agit d'une erreur et que la deuxième ligne est ABO_NOK, la raison de la non-validité de l'abonnement se trouve en troisième ligne. Enfin, si la deuxième ligne est différente de ABO_NOK, il s'agit d'une erreur dans l'exécution du test.

Si le paramètre abo est égal à "all", le test retournera la liste complète de tous les abonnements en cours. La première ligne sera OK si tout s'est bien passé, les lignes suivantes seront de la forme "ID SECONDES" avec ID l'identifiant de l'abonnement et SECONDES le nombre de secondes restantes ou 0 si la durée de l'abonnement est indéterminée. Si aucun abonnement n'est en cours, la seconde ligne sera "ABO_NONE".

6. À tout moment, votre S.I. peut terminer un abonnement en appelant l'URL https://achats.free.fr/achats/desabo.pl avec en paramètres votre numéro de commerçant (paramètre id) et le numéro d'abonné concerné (paramètre abo). Ce numéro d'abonnement correspond au numéro de transaction définitif qui a été renvoyé lors de la procédure d'abonnement. La terminaison de l'abonnement est calculée pour tomber sur la prochaine date d'échéance de l'abonnement. Vous pouvez aussi, si besoin, ajouter le paramètre now=1 et dans ce cas la terminaison de l'abonnement est immédiate et il n'y aura pas de facturation le mois suivant .

Le résultat, est soit OK si tout s'est bien déroulé, soit ERREUR avec la raison en deuxième ligne.

7. Option « période de gratuité »

Durant l'appel à preabo.pl vous pouvez, optionnellement, passer un paramètre supplémentaire nommé mgratis. Celui-ci correspond a une durée initiale (en mois) durant laquelle le Freenaute ne sera pas facturé. Cette période ne rallonge pas la durée nominale. Par exemple, un abonnement de 6 mois avec une période de gratuité de 2 mois durera effectivement 6 mois, mais ne commencera à être facturé qu'à partir du troisième mois. La durée de facturation sera de 4 mois.

8. Facturation des abonnements

La facturation des abonnements est effectuée au début de chaque mois. Tout abonnement qui est valide le premier jour du mois à minuit est facturé. Le montant de l'abonnement est alors passé en transaction (cf. le suivi des transactions) avec le type 'abo'. Concrètement, seule la liste des transactions valides est facturée au Freenaute, comprenant, ou pas, des abonnements insérés au début du mois.

Procédure de test de l'intégration des S.I. (achat ou abonnement)



Vous pouvez tester votre configuration à partir de l'IP de test paramétrée lors de l'inscription. Lorsque vous testerez, vous serez reconnu comme '[Votre ID] (Test)' et le mot de passe est simplement 'test' (en minuscules). La transaction sera enregistrée mais pas facturée. Vous pouvez, suite à vos tests, effacer ces transactions à partir du lien 'Purger les test' dans la page de gestion du compte.