Activer les webhooks pour recevoir les états d’une demande
Les webhooks vous permettent d’être informé automatiquement lorsque l’état de la demande d’un marchand que vous êtes en train d’intégrer change.
Il ne s’agit pas d’une requête API de gestion de compte. Vous devez configurer les webhooks dans le Portail Paysafe pour activer ce service.
Pour configurer les webhooks :
- Connectez-vous au Portail Paysafe.
- Allez à Paramètres > Notifications.
- Assurez-vous que l’onglet État de compte est sélectionné.
- Sélectionnez la case à cocher Mises à jour de l’état du compte.
- Dans le champ Point de terminaison, entrez l’URL à laquelle vous souhaitez que les rappels soient envoyés.
- Cliquez sur Enregistrer.
- Il est important de prendre note de la clé secrète HMAC située juste en dessous du champ Point de terminaison. Cette signature est utilisée pour vérifier l’authenticité de la notification du webhook et confirmer qu’aucune donnée n’a été modifiée.
Une fois configurés, vous recevrez des rappels lorsque l’état d’un compte marchand que vous avez intégré a été modifié, p. ex. de Différé à Activé (voir États des webhooks ci-dessous pour la liste des éventuels états de compte). Par exemple, vous recevrez la notification suivante si l’état du compte marchand que vous avez créé passe à Activé.
{
"id": "6a275b7c-6f11-4ed1-ae77-21071724574a",
"resourceId": "1003296300",
"mode": "live",
"eventDate": "2016-09-21T15:02:23Z",
"eventType": "ACCT_ENABLED",
"attemptNumber": 0,
"payload": {
"partnerId": 1000,
"acctStatus": "Enabled",
"accountNumber": "1003296300"
},
"links": [
{
"rel": "accounts",
"href": "https://api.test.paysafe.com/accountmanagement/v1/accounts/1003296300"
}
]
}
Éléments de notification
| Élément | Élément enfant | Requis | Type | Description |
|---|---|---|---|---|
| Id | Requis | string Max = 36 | Il s’agit de l’identifiant unique de cette requête. | |
| resourceId | Requis | string Max = 255 | Il s’agit de la ressource (numéro de compte) dont l’état est mis à jour. | |
| mode | Requis | string | Indique s’il s’agit d’un événement en direct ou d’un événement test. Les valeurs éventuelles sont :
| |
| eventDate | Requis | dateTime | Il s’agit de la date et de l’heure de l’événement (p. ex. mise à jour de l’état du compte). P. ex. 2017-01-26T10:32:28Z | |
| eventType | Requis | string Max = 255 | Il s’agit du type d’événement de rappel. | |
| payload | Requis | |||
| partnerId | Requis | string | Il s’agit de l’identifiant de partenaire qui vous a été attribué par Paysafe. | |
| acctStatus | Requis | string | Il s’agit de l’état actuel du compte marchand que vous intégrez à Paysafe. | |
| accountNumber | Requis | string Max = 36 | Il s’agit du numéro de compte marchand que vous utilisez avec Paysafe. | |
| externalAccountId | Facultatif | string Max = 36 | Il s’agit d’un identifiant de compte externe facultatif qui peut être attribué par le partenaire. | |
| links | Requis | |||
| rel | Requis | string | Il s’agit du type de lien qui permet de cibler différents terminaux en fonction de l’état final de la transaction. | |
| href | Requis | string | Il s’agit de l’URI de la ressource. | |
Remarques à propos des webhooks
- Toutes les URL de point de terminaison doivent être sécurisées avec un protocole HTTPS/SSL pour assurer la sécurité.
- Lorsque l’état de l’une de vos demandes de marchand change, Paysafe envoie immédiatement un rappel à l’URL de votre point de terminaison webhooks pour vous informer du changement d’état.
- Pour accuser réception d’un webhook, Paysafe s’attend à recevoir un état HTTP de 200 depuis votre point de terminaison. Si nous recevons un autre code d’état HTTP, nous supposerons que vous n’avez pas reçu les webhooks et nous essaierons de les renvoyer ultérieurement.
- Si le rappel pour cet événement de changement d’état du compte échoue (c.-à-d. que Paysafe ne reçoit pas d’accusé de réception avec un code d’état HTTP de 200), Paysafe effectuera un maximum de 10 tentatives supplémentaires pour envoyer un rappel à cette URL jusqu’à ce qu’il soit reçu avec succès, deux fois par jour pendant 5 jours.
- Si l’état d’une autre demande de marchand change et que vous utilisez la même URL de webhooks pour laquelle certains webhooks ont échoué, Paysafe effectuera toujours une première tentative de rappel, puis 10 tentatives supplémentaires pour ce changement d’état du compte marchand. (En d’autres termes, Paysafe ne désactive pas les rappels vers une URL advenant un échec pour un compte marchand.) Cela permet de s’assurer que les notifications continuent d’être envoyées pour des événements ultérieurs (c.-à-d. d’autres demandes de marchand) en cas de problème temporaire avec votre point de terminaison.
- Paysafe n’ayant pas de méthode de notification pour vous avertir lorsque les rappels n’atteignent pas l’URL de votre point de terminaison, vous devez vous assurer de tester la configuration de vos webhooks et de maintenir la disponibilité de votre point de terminaison.
États des webhooks
Paysafe envoie une notification webhook lorsque l’état du compte marchand est modifié dans l’un des cas suivants :
| État | Description | eventType |
|---|---|---|
| Approuvé | Le compte marchand a été approuvé, mais n’a pas encore été activé. | ACCT_APPROVED |
| Différé | La demande de compte marchand a été reportée jusqu’à ce que la souscription par le service risques/conformité soit terminée. | ACCT_DEFERRED |
| Désactivé | La demande de compte marchand a été désactivée en raison d’une suspension ou d’une résiliation. | ACCT_DEFERRED |
| Activé | Le compte marchand a été activé pour le traitement des paiements. | ACCT_ENABLED |
| En attente | La demande de compte marchand n’a pas encore été achevée. | ACCT_PENDING |
| Traitement | La demande de compte marchand est traitée par le service risques/conformité. | ACCT_PROCESSING |
| Refusé | La demande de compte marchand a été refusée en raison d’un échec de la vérification par le service risques/conformité. | ACCT_REJECTED |
| Renvoyé | La demande d’ouverture d’un compte marchand a été renvoyée par le service des risques au service de la conformité pour examen. | ACCT_RETURNED |
| Soumis | Le compte marchand a été soumis au service risques/conformité. | ACCT_SUBMITTED |
| En attente | Le service de conformité attend des informations supplémentaires de la part du marchand. | ACCT_WAITING |
| Retiré | La demande de compte marchand a été retirée. | ACCT_WITHDRAWN |
Test webhooks
Comme vous utiliserez la même URL de rappel pour plusieurs comptes marchands, il est important de tester l’URL pour vous assurer que l’URL des webhooks fonctionne correctement. Pour tester le service webhooks, une fois que vous avez configuré votre URL de rappel, cliquez sur le bouton Test de connectivité.
Paysafe enverra immédiatement un rappel de test avec un contenu similaire à l’exemple suivant.
{
"mode": "test",
"eventDate": "2017-11-17T16:21:01Z",
"eventType": "test",
"attemptNumber": 1
}
Pour que le calcul de la signature soit précis, HMACkey du Portail Paysafe doit être DÉCODÉ en Base64 avant toute opération (binaire – UTF8).