Webhooks
Recevez des notifications signées lors de changements concernant les paiements, les remboursements, les commerçants et l’onboarding.
Les webhooks informent votre serveur des changements dans votre organisation Tapaya. Utilisez la même intégration pour les paiements en magasin et en ligne, quel que soit le processeur de paiement.
Fonctionnement
TapayaConfigurez une destination HTTPS par organisation et sélectionnez les événements dont vous avez besoin. Tapaya envoie un POST HTTP avec un instantané JSON et une signature. Vérifiez la signature, stockez l’événement et renvoyez une réponse de succès avant d’exécuter votre logique métier.
Vous pouvez vous abonner à des types individuels ou à tous les types pris en charge. Un abonnement à tous les types reçoit également les nouveaux types pris en charge à l’avenir ; ignorez donc les types que votre application ne reconnaît pas.
Intégration rapide
Enregistrer une destination
Dans la Platform, ouvrez API Keys, puis Webhooks. Saisissez votre URL HTTPS, choisissez les événements dont vous avez besoin et enregistrez. Copiez dès maintenant le signing secret ; il n’est affiché qu’une seule fois. Consultez la configuration.
Vérifier chaque requête
Calculez un HMAC-SHA256 de l’horodatage, d’un point et du corps brut avec votre signing secret, puis comparez-le à X-Tapaya-Signature. Consultez Vérifier la signature.
Stocker l’événement, puis renvoyer 2xx
Enregistrez l’événement avec un id unique, répondez 2xx dans les 10 secondes et traitez-le ensuite. Consultez Stocker et accuser réception.
Envoyer un webhook de test
Sur la même page, utilisez l’action de test pour envoyer un webhook.test signé. Consultez Envoyer un webhook de test.
Enveloppe des événements
Chaque événement utilise cette structure commune. L’instantané de la ressource dans data dépend de son type.
{
"id": "019a0000-0000-7000-8000-000000000001",
"type": "payment.succeeded",
"apiVersion": "1",
"organizationId": "019a0000-0000-7000-8000-000000000002",
"merchantId": "019a0000-0000-7000-8000-000000000005",
"createdAt": "2026-10-30T12:00:00.000000Z",
"data": {
"payment": {
"id": "019a0000-0000-7000-8000-000000000003",
"token": "example_payment_token",
"merchantId": "019a0000-0000-7000-8000-000000000005",
"status": "success",
"statusId": 2,
"requestedAmount": 10000,
"requestedCurrencyId": 203,
"settlementAmount": 10000,
"settlementCurrencyId": 203
}
}
}| Champ | Signification |
|---|---|
id | Identifiant unique de l’événement. Utilisez-le pour dédupliquer les livraisons. Les nouvelles tentatives conservent le même identifiant. |
type | Nom de l’événement dans le catalogue des événements. |
apiVersion | Identifiant du schéma du payload, actuellement la chaîne "1". |
organizationId | Organisation à laquelle appartient l’événement. Vérifiez qu’elle correspond à votre intégration. |
merchantId | Commerçant auquel appartient la ressource. Peut être null pour les paiements anciens dont l’appartenance n’est pas déterminée ou pour un test de diagnostic. |
createdAt | Heure UTC à laquelle l’événement a été enregistré, plutôt que son heure de livraison. |
data | Instantané immuable de la ressource au moment de l’enregistrement de l’événement. |
Les montants sont des entiers exprimés dans la plus petite unité de la devise du champ. Par exemple, 10000 avec l’identifiant numérique de devise ISO 4217 203 correspond à 100,00 CZK. Les montants demandés et les montants de règlement peuvent utiliser des devises différentes.
Chaque type d’événement place son propre instantané dans data. Consultez les types d’événements pour la structure de chaque payload et chaque valeur de statut.
Règles de livraison
Tapaya envoie un événement dès que son changement est enregistré, et continue de l’envoyer jusqu’à ce que votre serveur réponde 2xx.
| Règle | Comportement |
|---|---|
| Accusé de réception | Toute réponse 2xx dans les 10 secondes. Les redirections ne sont pas suivies. |
| Nouvelles tentatives | Jusqu’à 12 tentatives sur environ 20 heures, avec des délais de 1, 2, 4, 8, 16, 32, 64, 128, 256, 360 et 360 minutes. |
| Ordre | Non garanti. La livraison a lieu au moins une fois : attendez-vous à des doublons et à des instantanés plus anciens. |
| Simultanéité | 2 requêtes à la fois par organisation, partagées avec les tests manuels. Les autres événements attendent dans la file. |
Une livraison échouée ne modifie jamais le paiement lui-même, et les livraisons passées ne peuvent pas être renvoyées. Pour vous remettre à jour après une interruption, lisez l’état actuel via les API de paiements et de commerçants.