Lors de la mise à niveau de votre ancienne intégration vers la nouvelle API, vous devrez régler votre gestionnaire de webhooks de façon à pouvoir gérer les nouveaux types de webhooks que nous vous envoyons.
Certaines actions que nous envoyions dans l'ancien système ont aussi changé. Vous trouverez ci-dessous un mappage de ces changements, ainsi que de nouvelles actions à prendre en compte :
Autorisations > Mandats
Les autorisations sont désormais des mandats. Les mandats sont bien plus flexibles : vous pouvez maintenant créer des paiements ponctuels ou des abonnements avec le même mandat, et les mandats peuvent être rattachés à plusieurs abonnements. Le client n'a pas besoin d'autoriser à nouveau les nouveaux paiements ou abonnements sur un mandat.
Ancienne API - actions relatives aux pré-autorisations/abonnements | Nouvelle API - actions relatives aux mandats | Description de l'action |
cancelled | cancelled | Ce mandat a été annulé, soit par le client via sa banque ou cette API, ou automatiquement lorsque son compte bancaire a été clôturé. |
expired | expired | Aucune tentative de prélèvement n'a été faite dans le cadre de ce mandat pendant plus de 13 mois. C'est pourquoi il a expiré, et il ne pourra plus être utilisé pour effectuer des prélèvements. Si vous souhaitez continuer de prélever des paiements sur le compte de ce client, vous devez demander son autorisation et utiliser le point de terminaison de réactivation. |
Nouvelle API - actions supplémentaires relatives aux mandats | Description de l'action |
created | Le mandat a été créé. |
customer_approval_granted | Le mandat exigeait une approbation supplémentaire du client (par exemple, l'autorisation d'un deuxième signataire), et cette approbation a été obtenue. |
customer_approval_skipped | Initialement, ce mandat exigeait supposément une approbation supplémentaire du client (par exemple, l'autorisation d'un deuxième signataire), mais celle-ci a été ignorée (parce que le mandat avait été marqué par erreur comme requérant un deuxième signataire, par exemple). |
active | Ce mandat a été mis en place correctement par la banque du client. |
failed | Ce mandat n'a pas pu être mis en place, en général parce que le compte bancaire spécifié ne prend pas en charge les paiements par prélèvement ou a été clôturé. |
transferred | Le mandat a été transféré vers un autre compte bancaire. L'événement inclura les liens [previous_customer_bank_account] et [new_customer_bank_account], et le mandat a peut-être été soumis à nouveau, selon la manière dont les banques impliquées ont géré le transfert. |
submitted | Le mandat a été envoyé aux banques, et devrait devenir actif dans quelques jours, à moins que la banque ne rejette la requête. |
resubmission_requested | Une requête de nouvelle soumission du mandat a été envoyée par le point de terminaison de réactivation du mandat. |
reinstated | Le mandat est redevenu actif, après avoir été annulé ou avoir expiré. Cela peut arriver lorsque la banque du client souhaite annuler une annulation ou un avis d'expiration envoyé, ou parce que le mandat a bien été réactivé via le point de terminaison de réactivation. |
replaced | Le mandat a été annulé et remplacé par un nouveau mandat (par exemple, parce que le créancier s'est vu attribuer un nouveau numéro SUN). L'événement inclura des liens [new_mandate] avec l'identifiant du nouveau mandat. |
Factures > Paiements
Notre ancienne API offrait la possibilité de créer des factures ponctuelles, ou une série de factures ponctuelles ayant fait l'objet d'une pré-autorisation. Les factures sont maintenant appelées des paiements, et un paiement créé peut être soit unique, soit faire partie d'un abonnement.
Ancienne API - actions relatives aux factures | Nouvelle API - actions relatives aux paiements | Description de l'action |
created | created | Le paiement a été créé. |
paid | confirmed | Le paiement a été prélevé du compte bancaire du client, et est maintenant détenu par GoCardless. Il faut parfois attendre jusqu'à 5 jours pour qu'un paiement soit prélevé, et il sera ensuite détenu pendant une courte période avant de passer au statut paid_out. |
withdrawn | paid_out | Le paiement a quitté GoCardless et a été envoyé sur le compte bancaire du créancier. |
failed | failed | Le paiement n'a pas pu être prélevé. Cela est généralement dû au fait que le client n'a pas de fonds suffisants disponibles. GoCardless n'effectuera pas de nouvelle tentative de paiement. |
cancelled | cancelled | Le paiement a été annulé. |
refunded | (envoyé comme objet de remboursement) ** | |
chargedback | charged_back | Le client a demandé à sa banque de rembourser le paiement dans le cadre de la garantie Direct Debit Guarantee, et celui-ci a été retransmis au client. |
retried | resubmission_requested | Une nouvelle demande de soumission du paiement a été faite par le point de terminaison de nouvelle tentative de paiement. |
Nouvelle API - actions supplémentaires relatives aux paiements | Description de l'action |
submitted | Le paiement a été soumis auprès des banques. Il faudra attendre quelque jours avant qu'il ne soit prélevé ou qu'il échoue. |
late_failure_settled | Le paiement avait échoué tardivement et avait déjà été versé. Il a été débité d'un versement. |
chargeback_cancelled | La banque du client a annulé la demande de rejet de paiement. Cette annulation se fait toujours à la demande du client. |
chargeback_settled | Le paiement avait été rejeté après avoir été versé, et a été débité d'un versement. |
** Les remboursements sont maintenant représentés par leur propre ressource. Si un paiement est remboursé, le statut de la ressource de paiement restera confirmé, et une ressource de remboursement distincte du paiement sera créée séparément.
Nouvelle API - actions relatives aux remboursements | Description de l'action |
created |
Un remboursement a été créé. payment_refunded s'affichera dans les détails [cause], et api dans les détails [origin]. |
paid | Le remboursement a été versé à votre client. refund_paid s'affichera dans les détails [cause], et gocardless dans les détails [origin]. |
refund settled | Le remboursement a été déduit d'un versement. refund_settled s'affichera dans les détails [cause], et gocardless dans les détails [origin]. |
Les abonnements sont maintenant créés dans le cadre d'un mandat. Vous recevrez les actions de webhook suivantes :
Nouvelle API - actions relatives aux abonnements | Description de l'action |
created | L'abonnement a été créé. |
customer_approval_granted | L'abonnement requérait l'approbation supplémentaire du client avant de pouvoir devenir actif, et cette approbation a été obtenue. |
customer_approval_denied | L'abonnement requérait une approbation supplémentaire du client avant de pouvoir devenir actif, et cette approbation a été refusée. |
payment_created | Un paiement a été créé par cet abonnement. |
cancelled | L'abonnement a été annulé. Plus aucun paiement ne sera créé. |
finished | L'abonnement est terminé. Plus aucun paiement ne sera créé. |
Versements
Notre nouvelle API vous permet toujours d'interroger les versements que vous recevez de GoCardless. De plus, nous avons ajouté quelques étapes supplémentaires pour vous aider à rapprocher les versements des événements, ce qui veut dire que vous pourrez obtenir une liste de paiements pour un versement spécifique via l'API.
Nouvelle API - actions relatives aux versements | Description de l'action |
paid | GoCardless a transféré le versement vers le compte bancaire du créancier. payout_paid s'affichera toujours dans les détails [cause], et gocardless apparaîtra dans les détails [origin]. |
Format des webhooks
Notre ancienne API envoyait des webhooks à propos du statut d'une facture, d'une pré-autorisation ou d'un abonnement. Notre nouvelle API envoie désormais des webhooks contenant bien plus d'information, et ils peuvent être envoyés à plusieurs points de terminaison. Lorsqu'une ressource change de statut, nous enregistrons un événement, et les événements sont regroupés dans des tableaux et publiés en tant que webhooks.
Exemple d'un ancien webhook de pré-autorisation :
{
"payload": {
"resource_type": "pre_authorization",
"action": "cancelled",
"pre_authorizations": [{
"id": "AKJ398H8KBOOO3",
"status": "cancelled",
"uri": "https://gocardless.com/api/v1/pre_authorizations/AKJ398H8KBOOO3"
}, {
"id": "AKJ398H8KBOOOA",
"status": "cancelled",
"uri": "https://gocardless.com/api/v1/pre_authorizations/AKJ398H8KBOOOA"
}],
"signature": "f6b9e6cd8eef30c444da48370e646839c9bb9e1cf10ea16164d5cf93a50231eb"
}
}
Exemple d'un webhook de mandat de la nouvelle API :
{
"events": [
{
"id": "EVTESTWKH4MPNG",
"created_at": "2017-04-25T11:20:47.542Z",
"resource_type": "mandates",
"action": "cancelled",
"links": {
"mandate": "MD123"
},
"details": {
"origin": "api",
"cause": "mandate_cancelled",
"description": "The mandate was cancelled at your request."
},
"metadata": {}
}
]
}
Vous trouverez aussi un outil pratique pour tester ces nouveaux webhooks dans l'onglet « Développeurs » de votre nouveau compte sandbox ou sur votre tableau de bord actif. Une fois que vous êtes dans la section dédiée aux développeurs, cliquez sur « Envoyer un webhook test » pour tester l'envoi d'un webhook quelconque que nous pourrions envoyer à votre point de terminaison de webhook.