Implémentation sur les appels WebService DirectPaymentAPI et WebPaymentAPI

Il est recommandé d'utiliser la bascule à la source au niveau des appels WebService effectués entre le backend marchand et l'API WebService Payline.

Pour implémenter ce mécanisme, il faut :

mettre à jour la version du kit java/php/.net avec celle supportant la bascule à la source
ou effectuer les développements sur le backend marchand si les kit fournis par Payline ne sont pas utilisés sur votre système.

Ci-dessous les détails des explications sur la manière de l'implémenter côté serveur marchand (utilisation du service d'annuaire, ajout d'en-tête http, cas de bascule, ...)

Cinématique de bascule

1. Comment utiliser le service d'annuaire ?

Monext propose un service d'annuaire de manière à rendre dynamique la liste des endpoints à utiliser. Ce service est optionnel, vous pouvez utiliser une liste statique, néanmoins il vous permet d'éviter des mises à jour manuelles. Ce service est au format REST et permet en fonction du chemin passé, de récupérer la liste des endpoint Payline REST ou SOAP

Cet annuaire est disponible ici et doit être appelé par un GET :

Environnement	URL de l'annuaire pour récupération des endpoints REST Payline	URL de l'annuraire pour récupération des endpoints SOAP Payline
Homologation	https://homologation-payment.payline.com/services/servicesendpoints/REST/{merchantId}	https://homologation-payment.payline.com/services/servicesendpoints/SOAP/{merchantId}
Production	https://payment.payline.com/services/servicesendpoints/REST/{merchantId}	https://payment.payline.com/services/servicesendpoints/SOAP/{merchantId}

Ces services renvoient un tableau JSON contenant :

l'ensemble des endpoints accessibles à utiliser, dans l'ordre de priorité (première URL de la liste, puis seconde URL de la liste, ...)
la durée de validité de ces URLs "ttl" (Time To Live)

Les URLs renvoyées par le service d'annuaire doivent être mises en cache pour la durée spécifiée dans la réponse.

Directory Response (exemple en production)

{
    "ttl":"10080",
    "urls":[
        "https://services.payline.com/V4",
        "https://services-2.payline.com/V4"
    ]
}

Gestion du service d'annuaire

Récupération des endpoint dans l'annuaire
Mise en cache des endpoints, pour la durée des TTL (en seconde)
Attente d'expiration du ttl et nouvel appel à l'annuaire
Si appel à l'annuaire en succès et réponse non vide, rafraichissement du cache

Attention - Appels à l'annuaire

Pour des raisons de performance, la mise à jour des URLs doit respecter le ttl (Time To Live) indiqués (il est en seconde.) En aucun cas cet annuaire ne doit être sollicité à chaque appel WebService/REST.

Attention - En cas d'indisponibilité de l'annuaire

Si l'appel à l'annuaire est en échec et/ou qu'une liste vide est retournée, ne pas supprimer les URL présentes côté serveur client et les conserver jusqu'au prochain appel en succès. Ceci afin d'éviter qu'en cas d'échec ou d'incident sur le service d'annuaire, tous les appels webservices soient en échec.

Attention - Nouvelles URL à contacter depuis vos serveurs et applications

En cas de restriction sur les URL joignables depuis vos applications/serveurs, des ouvertures vers de nouvelles URL sont à effectuer sur votre infrastructure. Voici le tableau récapitulatif :

	HORS PRODUCTION		PRODUCTION
	URL	IP	URL	IP
Endpoint Annuaire Payline	https://homologation-payment.payline.com/services/servicesendpoints/*	31.210.0.103 31.210.4.103	https://payment.payline.com/services/servicesendpoints/*	31.210.4.112 31.210.0.112
Endpoint de secours sur bascule	https://homologation-2.payline.com/*	31.210.5.100 31.210.1.100	https://services-2.payline.com/*	31.210.5.108 31.210.1.108

2. Dans quels cas déclencher la bascule à la source suite à l'échec d'un appel API WebService ?

Liste de services concernées

Les services suivants pourront être traités par la bascule pour améliorer la qualité de service :

services
`doAuthorization`
`doImmediateWalletPayment`
`verifyEnrollment`
`verifyAuthentication`
`doReAuthorization`
`doWebPayment`
`getWebPaymentDetails`

Conditions de bascule

Les conditions qui permettent de tenter un nouvel appel sur le endpoint suivant sont :

Timeout ou non réponse après 30 secondes

Réception d'une réponse avec un code HTTP :
- 408 - Request Timeout
- 500 - Internal server error
- 502 - Bad gateway
- 503 - Service unavailable
- 504 - Gateway timeout

Réception d'un code retour métier :
- 04901 - System error
- 02101 - Internal error

Conseil - Listes de codes retours

Les deux listes de codes retours http et de codes retours métier doivent pouvoir être paramétrables côté client. Elles pourraient être enrichies lors d'évolutions futures.

3. Comment enrichir l'appel WebService lors d'une bascule ?

De manière à pouvoir identifier un appel réalisé suite à une bascule, certains header HTTP doivent être positionnés lors des appels suivants :

Propriété	Description	Type	Exemple
`x-failover-cause`	Message indiquant la raison du déclenchement de la bascule à la source : `TIMEOUT` `HTTP_[code]` où `code` vaut le code HTTP reçu `APP_[code]` où `code` vaut le code Payline reçu Ce paramètre doit obligatoirement être présent avec une valeur non vide pour que la requête soit considérée comme une requête de bascule.	String	`"TIMEOUT"` `"HTTP_503"` `"APP_02101"`
`x-failover-duration`	Durée en millisecondes de la requête ayant déclenchée la bascule à la source Ce champ est facultatif.	Integer	255
`x-failover-origin`	URL du DataCenter qui était en erreur et qui a induit la bascule. Ce champ est facultatif.	String	"https://services.payline.com/services/V4"
`x-failover-index`	Index indiquant le nombre de bascule effectuées. Cet index commence à 1 pour la 1ere bascule. Ce champ est facultatif.	Integer	1

Arborescence des pages

Bascule à la source - Guide d'intégration sur les appels API Webservices