10 endpoints
Webhooks
Vos URL de réception, leurs secrets de signature, la liste des événements émis et le détail de chaque livraison.
Les intitulés et descriptions d'endpoints viennent du contrat OpenAPI, en anglais — ils ne peuvent pas diverger de l'API.
En clair
Les notifications signées que ChariPay envoie à votre serveur.
Quand l'utiliser
Dès le premier paiement. Sans webhook, votre système ne saura jamais de façon fiable qu'un paiement a abouti.
Comment l'intégrer
- 1Déclarez une URL avec la liste explicite des événements qui vous intéressent.
- 2Récupérez le secret de signature et conservez-le comme une clé d'API.
- 3Envoyez un événement de test pour valider votre réception de bout en bout.
- 4Consultez le journal des livraisons quand un événement semble manquant — il dit si nous avons envoyé, et ce que votre serveur a répondu.
- 5Faites tourner le secret périodiquement, et réactivez un endpoint que nous aurions suspendu après trop d'échecs.
Les événements réellement émis
Ce sont les seuls types d'événements que l'API envoie. D'autres valeurs apparaissent dans l'énumération du contrat : elles sont réservées et ne partent jamais — s'y abonner produit un branchement mort.
- Paiements
payment.succeededpayment.failedorder.paid
- Abonnements
subscription.payment_succeededsubscription.payment_failedsubscription.canceled
- Remboursements
refund.succeededrefund.failed
- Mouvements du compte
merchant_transfer.completedmerchant_transfer.failedtopup.succeededtopup.failedbill_payment.pendingbill_payment.succeededbill_payment.failed
- Distribution
wallet.activatedwallet.rejectedpayout.completedpayout.failedsubmerchant.near_cap
- GET
/api/v1/partner/webhooks/endpointsLister les endpoints webhook partenaires - POST
/api/v1/partner/webhooks/endpointsEnregistrer un endpoint webhook partenaire - POST
/api/v1/partner/webhooks/endpoints/{id}/testEnvoyer un événement de test à un endpoint webhook partenaire - POST
/api/v1/partner/webhooks/endpoints/{id}/rotate-secretRenouveler le secret de signature d'un webhook partenaire - POST
/api/v1/partner/webhooks/endpoints/{id}/activateRéactiver un endpoint webhook partenaire suspendu - GET
/api/v1/partner/webhooks/endpoints/{id}Récupérer un endpoint webhook partenaire - PATCH
/api/v1/partner/webhooks/endpoints/{id}Mettre à jour un endpoint webhook partenaire - DELETE
/api/v1/partner/webhooks/endpoints/{id}Supprimer un endpoint webhook partenaire - GET
/api/v1/partner/webhooks/eventsLister les événements webhook émis - GET
/api/v1/partner/webhooks/events/{deliveryId}Récupérer un événement webhook émis
Lister les endpoints webhook partenaires
| Champ | Type | Emplacement | Requis | Description |
|---|---|---|---|---|
pageable | Pageable | query | Requis |
Enregistrer un endpoint webhook partenaire
Renvoie le secret de signature une seule fois ; il n'est plus exposé par les lectures ultérieures. Conservez-le dans un gestionnaire de secrets. L'endpoint n'appartient qu'à l'environnement SANDBOX ou PRODUCTION de la clé d'API. Abonnez-vous à subscription.payment_succeeded pour marquer une période de facturation du marchand comme payée, à subscription.payment_failed pour des informations de recouvrement normalisées et à subscription.canceled pour la clôture définitive de la relance. Les événements incluent ExternalId, PeriodDate et les metadata du marchand pour le rapprochement.
Schéma · WebhookEndpointRequest
| Champ | Type | Emplacement | Requis | Description |
|---|---|---|---|---|
url | string | body | Requis | URL publique du récepteur en HTTPS sur le port 443. Les cibles privées, loopback, link-local et non HTTPS sont rejetées. |
description | string | body | Optionnel | Libellé du point de terminaison côté marchand. |
enabledEvents | array of enum | body | Optionnel | Liste d'autorisation explicite d'événements. Une valeur null ou vide abonne à tous les événements actuels et futurs ; une liste explicite est recommandée pour les intégrations stables. |
customHeaders | object | body | Optionnel | En-têtes de routage statiques facultatifs. Host, Authorization, Cookie, Chari-* et X-CHARI-* ne peuvent pas être remplacés. |
apiVersion | string | body | Optionnel | Version du contrat de charge utile du webhook. |
enabled | boolean | body | Optionnel | Indique si la livraison démarre immédiatement. |
environment | enum | body | Optionnel | SANDBOX ou PRODUCTION. Routes du portail uniquement — vaut PRODUCTION par défaut si omis. Ignoré sur /api/v1/partner/**, où la clé d'API fait foi, et ignoré à la mise à jour (un endpoint ne peut pas changer d'environnement ; supprimez-le puis recréez-le).Valeurs SANDBOXPRODUCTION |
Envoyer un événement de test à un endpoint webhook partenaire
Met en file d'attente un événement payment.succeeded synthétique portant Test: true, signé exactement comme un événement réel et ignorant la liste d'événements autorisés. Renvoie l'identifiant de livraison ; relisez-le via GET /api/v1/partner/webhooks/events/{deliveryId} pour consulter la réponse de votre récepteur.
| Champ | Type | Emplacement | Requis | Description |
|---|---|---|---|---|
id | string (uuid) | path | Requis |
Renouveler le secret de signature d'un webhook partenaire
Invalide immédiatement l'ancien secret et renvoie le nouveau une seule fois. Mettez à jour le récepteur de façon atomique pour éviter de rejeter des livraisons.
| Champ | Type | Emplacement | Requis | Description |
|---|---|---|---|---|
id | string (uuid) | path | Requis |
Réactiver un endpoint webhook partenaire suspendu
Les endpoints sont suspendus automatiquement après des échecs de livraison répétés ; les événements en file d'attente sont conservés et reprennent dans l'ordre à la réactivation.
| Champ | Type | Emplacement | Requis | Description |
|---|---|---|---|---|
id | string (uuid) | path | Requis |
Récupérer un endpoint webhook partenaire
| Champ | Type | Emplacement | Requis | Description |
|---|---|---|---|---|
id | string (uuid) | path | Requis |
Mettre à jour un endpoint webhook partenaire
Met à jour l'URL, la liste d'autorisation explicite d'événements, les en-têtes de routage personnalisés ou l'état d'activation. Utilisez une liste enabledEvents explicite pour éviter de recevoir automatiquement les événements nouvellement introduits.
Schéma · WebhookEndpointRequest
| Champ | Type | Emplacement | Requis | Description |
|---|---|---|---|---|
id | string (uuid) | path | Requis | |
url | string | body | Requis | URL publique du récepteur en HTTPS sur le port 443. Les cibles privées, loopback, link-local et non HTTPS sont rejetées. |
description | string | body | Optionnel | Libellé du point de terminaison côté marchand. |
enabledEvents | array of enum | body | Optionnel | Liste d'autorisation explicite d'événements. Une valeur null ou vide abonne à tous les événements actuels et futurs ; une liste explicite est recommandée pour les intégrations stables. |
customHeaders | object | body | Optionnel | En-têtes de routage statiques facultatifs. Host, Authorization, Cookie, Chari-* et X-CHARI-* ne peuvent pas être remplacés. |
apiVersion | string | body | Optionnel | Version du contrat de charge utile du webhook. |
enabled | boolean | body | Optionnel | Indique si la livraison démarre immédiatement. |
environment | enum | body | Optionnel | SANDBOX ou PRODUCTION. Routes du portail uniquement — vaut PRODUCTION par défaut si omis. Ignoré sur /api/v1/partner/**, où la clé d'API fait foi, et ignoré à la mise à jour (un endpoint ne peut pas changer d'environnement ; supprimez-le puis recréez-le).Valeurs SANDBOXPRODUCTION |
Supprimer un endpoint webhook partenaire
| Champ | Type | Emplacement | Requis | Description |
|---|---|---|---|---|
id | string (uuid) | path | Requis |
Lister les événements webhook émis
Renvoie les événements émis pour l'environnement de cette clé d'API, du plus récent au plus ancien. Filtrez par endpoint, type d'événement, statut de livraison ou fenêtre de création. Les types d'événement utilisent leur valeur pointée, par exemple payment.succeeded ; le catalogue complet est disponible via GET /api/v1/partner/webhooks/event-types. Les payloads sont omis ici : lisez un événement individuel pour obtenir le corps signé exact.
| Champ | Type | Emplacement | Requis | Description |
|---|---|---|---|---|
endpointId | string (uuid) | query | Optionnel | |
eventType | enum | query | Optionnel | Valeurs payment_link.createdpayment_link.updatedpayment_link.expiredpayment_link.cancelledpayment.initiatedpayment.requires_actionpayment.succeededpayment.failedsubscription.payment_succeededsubscription.payment_failedsubscription.canceledrefund.initiatedrefund.succeededrefund.failedsecurity.token_reusedsecurity.rate_limit_exceededsecurity.invalid_signaturewallet.activatedwallet.rejectedpayout.completedpayout.failedsubmerchant.near_capwallet.fundedwallet.transfer_completedmerchant_transfer.completedmerchant_transfer.failedtopup.pendingtopup.succeededtopup.failedtopup.reversedbill_payment.pendingbill_payment.succeededbill_payment.failedbill_payment.reversedvoucher.issuedvoucher.failedvoucher.redeemedvoucher.expiredsavings.deposit_succeededsavings.withdrawal_succeededsavings.instruction_failedsavings.goal_reachedorder.paid |
status | enum | query | Optionnel | Valeurs pendingsendingdeliveredfailedretryingexhaustedskipped |
from | string (date-time) | query | Optionnel | |
to | string (date-time) | query | Optionnel | |
pageable | Pageable | query | Requis |
Récupérer un événement webhook émis
Inclut la charge utile signée exactement telle qu'elle a été envoyée au récepteur, ce qui permet à un partenaire de reproduire la signature en local avant de rejouer l'événement.
| Champ | Type | Emplacement | Requis | Description |
|---|---|---|---|---|
deliveryId | string (uuid) | path | Requis |
Une question sur l'intégration ?
Notre équipe technique répond aux intégrateurs, du premier appel en sandbox jusqu'à la mise en production.