Aller au contenu principal

Points de terminaison Giving

Le module Giving gère les dons, les fonds, le traitement des paiements, les abonnements et les opérations financières connexes. Il prend en charge plusieurs passerelles de paiement (Stripe, PayPal), gère les dons ponctuels et récurrents, suit les lots de dons et assure le traitement des webhooks pour les événements de paiement asynchrones.

Chemin de base : /giving

Dons​

Chemin de base : /giving/donations

MéthodeCheminAuthAutorisationDescription
GET/JWTDonations.View ou son propre personIdLister tous les dons. Filtrer par ?batchId= ou ?personId=. Avec ?personId=, les dons aux fonds non déductibles sont exclus (comme sur les reçus de dons), sauf si un appelant ayant Donations.View ajoute &includeNonDeductible=1, ce que fait la fiche de personne de B1Admin
GET/:idJWTDonations.ViewObtenir un don par ID
GET/myJWT—Obtenir les dons de l'utilisateur actuel
GET/my/summary?year=JWT—Total des dons de l'utilisateur actuel pour une année (par défaut cette année) : { year, total, count, currency, isConverted }, les totaux étant convertis dans la devise de l'église. Alimente l'aperçu des dons sur la page d'accueil du membre
GET/?startDate=&endDate=JWTDonations.ViewDons datés dans la plage (inclusive). Les deux dates sont obligatoires au format YYYY-MM-DD, sinon 400. Les pages de reçus de dons de B1Admin demandent ainsi une année civile à la fois plutôt que l'historique complet de l'église
GET/summaryJWTDonations.ViewSummaryObtenir le résumé des dons. Filtrer par ?startDate=&endDate=&type=. Utilisez type=person pour une ventilation par personne
GET/testEmailPublique—Envoyer un courriel de test (développement/débogage)
POST/JWTDonations.Edit ou Donations.EnterCréer ou mettre à jour des dons (lot). Avec Donations.Enter seulement, le lot cible et (pour une mise à jour) le lot actuel du don doivent être ouverts, et les dons de passerelle (ceux avec un transactionId) ne peuvent pas être modifiés ; sinon 403 { "error": "This batch is closed." }
DELETE/:idJWTDonations.Edit ou Donations.EnterSupprimer un don. Donations.Enter seulement : le don doit être dans un lot ouvert et ne pas être un don de passerelle, sinon 403

Exemple : lister les dons par lot​

GET /giving/donations?batchId=abc-123
Authorization: Bearer <token>
[
{
"id": "don-456",
"batchId": "abc-123",
"personId": "per-789",
"donationDate": "2025-03-15T00:00:00.000Z",
"amount": 100.00,
"method": "card"
}
]

Exemple : obtenir le résumé des dons​

GET /giving/donations/summary?startDate=2025-01-01&endDate=2025-12-31
Authorization: Bearer <token>
[
{
"week": "2025-01-06",
"fund": "General Fund",
"totalAmount": 2500.00,
"count": 15
}
]

Lots de dons​

Chemin de base : /giving/donationbatches

Hérite de GenericCrudController avec les routes CRUD : getById, getAll, post, delete. L'opération de suppression supprime aussi tous les dons du lot.

MéthodeCheminAuthAutorisationDescription
GET/JWTDonations.ViewSummary ou Donations.EnterLister tous les lots de dons
GET/:idJWTDonations.ViewSummary ou Donations.EnterObtenir un lot de dons par ID
POST/JWTDonations.Edit ou Donations.EnterCréer ou mettre à jour des lots de dons. Donations.Enter seulement : la mise à jour d'un lot existant exige qu'il soit ouvert, sinon 403 { "error": "This batch is closed." }. status est ignoré ici, donc enregistrer un lot ne peut pas le rouvrir
POST/:id/closeJWTDonations.EditFermer un lot : règle status sur closed, closedDate sur maintenant, et closedBy sur l'ID utilisateur de l'appelant. Renvoie le lot
POST/:id/reopenJWTDonations.EditRouvrir un lot : règle status sur open et efface closedDate et closedBy. Renvoie le lot
DELETE/:idJWTDonations.EditSupprimer un lot et tous ses dons

Chaque lot comprend status (open ou closed ; les lots nouveaux et existants sont open), closedDate et closedBy. Donations.Edit peut modifier les dons de n'importe quel lot ; Donations.Enter (affiché sous Saisir les dons dans l'éditeur de rôles) ne peut ajouter, modifier ou supprimer des dons et des répartitions de fonds que lorsque leur lot est ouvert.

Don​

Chemin de base : /giving/donate

Gère le flux de don public, y compris les paiements, les abonnements, les webhooks et les calculs de frais. Aucune route CRUD de base n'est activée ; tous les points de terminaison sont personnalisés.

MéthodeCheminAuthAutorisationDescription
GET/gateways/:churchIdPublique—Obtenir les passerelles de paiement disponibles pour une église (clés publiques seulement)
POST/client-tokenJWT—Générer un jeton client pour l'initialisation de la passerelle
POST/create-orderJWT—Créer une commande de paiement (paiement de type PayPal)
POST/chargeJWT—Traiter un paiement de don ponctuel
POST/subscribeJWT—Créer un abonnement de don récurrent
POST/logPublique—Enregistrer un don. Corps : { donation, fundData }
POST/webhook/:providerPublique—Recevoir les événements de webhook de paiement (Stripe, PayPal). Exige ?churchId=
POST/replay-stripe-eventsJWTDonations.EditRejouer les événements Stripe pour une plage de dates. Corps : { startDate, endDate, dryRun }
POST/feePublique—Calculer les frais de transaction. Corps : { type, provider, gatewayId, amount, currency }. Exige ?churchId=
POST/captcha-verifyPublique—Vérifier un jeton reCAPTCHA. Corps : { token, churchId? }. Une réponse humaine renvoie { response: "human", pass }, où pass est un laissez-passer signé de don pour visiteur valable 10 minutes (et seulement pour churchId lorsqu'il est envoyé)

Lorsque l'Api fonctionne avec CAPTCHA_ENFORCE=true, les appels de visiteurs (non connectés) à /giving/donate/create-order, /charge, /subscribe, /giving/paymentmethods/addcard et /giving/paymentmethods/ach-setup-intent-anon (ainsi que les appels POST /content/registrations/register avec tarification pour visiteurs) doivent inclure ce captchaPass dans le corps, sinon ils renvoient 403 Captcha verification required. Le laissez-passer peut être réutilisé jusqu'à son expiration, car le parcours de don Stripe pour visiteurs effectue deux appels (ajout de la carte, puis paiement). Les appels d'utilisateurs connectés ne sont pas touchés. CAPTCHA_ENFORCE est réglé par défaut sur false ; les formulaires de don pour visiteurs de @churchapps/apphelper envoient le laissez-passer automatiquement.

Exemple : traiter un paiement de don​

POST /giving/donate/charge
Authorization: Bearer <token>

{
"provider": "stripe",
"amount": 50.00,
"currency": "usd",
"person": { "id": "per-123", "email": "donor@example.com" },
"funds": [{ "id": "fund-001", "name": "General Fund", "amount": 50.00 }],
"church": { "name": "First Church", "subDomain": "firstchurch" }
}
{
"id": "ch_abc123",
"status": "succeeded",
"provider": "stripe"
}

Exemple : créer un abonnement récurrent​

POST /giving/donate/subscribe
Authorization: Bearer <token>

{
"provider": "stripe",
"amount": 100.00,
"customerId": "cus_abc123",
"interval": { "interval_count": 1, "interval": "month" },
"billing_cycle_anchor": 1710460800,
"person": { "id": "per-123", "email": "donor@example.com" },
"funds": [{ "id": "fund-001", "name": "General Fund", "amount": 100.00 }],
"church": { "name": "First Church", "subDomain": "firstchurch" }
}
{
"id": "sub_xyz789",
"status": "active",
"provider": "stripe"
}

Fonds​

Chemin de base : /giving/funds

Hérite de GenericCrudController avec les routes CRUD : getById, getAll, post, delete. La permission view est null (aucune autorisation requise pour consulter les fonds).

MéthodeCheminAuthAutorisationDescription
GET/JWT—Lister tous les fonds
GET/:idJWT—Obtenir un fonds par ID
GET/churchId/:churchIdPublique—Obtenir tous les fonds d'une église précise (public)
GET/public/:churchId/:fundId/total?startDate=&endDate=Publique—Obtenir le total des dons d'un fonds : { fundId, totalAmount, donationCount }. Alimente l'élément campaignProgress du générateur de site web
POST/JWTDonations.EditCréer ou mettre à jour des fonds
DELETE/:idJWTDonations.EditSupprimer un fonds

Dons par fonds​

Chemin de base : /giving/funddonations

Suit la façon dont les dons individuels sont répartis entre les fonds. Aucune route CRUD de base n'est activée ; tous les points de terminaison sont personnalisés.

MéthodeCheminAuthAutorisationDescription
GET/JWTDonations.ViewLister les dons par fonds. Filtrer par ?donationId=, ?personId=, ?fundId= ou ?fundName=. Vous pouvez ajouter ?startDate=&endDate= pour filtrer par date
GET/:idJWTDonations.ViewObtenir un don par fonds par ID
GET/myJWT—Obtenir les dons par fonds de l'utilisateur actuel
POST/JWTDonations.Edit ou Donations.EnterCréer ou mettre à jour des dons par fonds (lot). Donations.Enter seulement : le don parent doit être dans un lot ouvert et ne pas être un don de passerelle, sinon 403
DELETE/:idJWTDonations.Edit ou Donations.EnterSupprimer un don par fonds. Même règle de lot ouvert pour Donations.Enter

Passerelles​

Chemin de base : /giving/gateways

Gère les configurations des passerelles de paiement (Stripe, PayPal, etc.). Aucune route CRUD de base n'est activée ; tous les points de terminaison sont personnalisés. Les secrets des passerelles sont chiffrés au repos.

MéthodeCheminAuthAutorisationDescription
GET/JWT—Lister toutes les passerelles de l'église
GET/:idJWTSettings.EditObtenir une passerelle par ID
GET/churchId/:churchIdPublique—Obtenir les passerelles d'une église (clés publiques seulement)
GET/configured/:churchIdPublique—Vérifier si une église a une passerelle de paiement configurée
POST/JWTSettings.EditCréer ou mettre à jour des passerelles (chiffre les clés, provisionne les webhooks et les produits)
PATCH/:idJWTSettings.EditMettre à jour partiellement une passerelle
DELETE/:idJWTSettings.EditSupprimer une passerelle (supprime aussi ses webhooks)

Exemple : vérifier la configuration de la passerelle​

GET /giving/gateways/configured/church-123
{
"configured": true
}

Clients​

Chemin de base : /giving/customers

Hérite de GenericCrudController avec les routes CRUD : getAll, delete. Relie les personnes à leurs fiches client de la passerelle de paiement.

MéthodeCheminAuthAutorisationDescription
GET/JWTDonations.ViewSummaryLister tous les clients
GET/:idJWTDonations.ViewSummary ou sa propre ficheObtenir un client par ID
GET/:id/subscriptionsJWTDonations.ViewSummary ou sa propre ficheObtenir les abonnements de la passerelle d'un client
DELETE/:idJWTDonations.EditSupprimer un client

Abonnements​

Chemin de base : /giving/subscriptions

Gère les abonnements de dons récurrents. Aucune route CRUD de base n'est activée ; tous les points de terminaison sont personnalisés.

MéthodeCheminAuthAutorisationDescription
GET/JWTDonations.ViewSummaryLister tous les abonnements
GET/:idJWTDonations.ViewSummaryObtenir un abonnement par ID
POST/JWTDonations.Edit ou son propre abonnementMettre à jour les abonnements auprès de la passerelle de paiement
DELETE/:idJWTDonations.Edit ou son propre abonnementAnnuler un abonnement et le retirer de la base de données. Corps : { provider, reason }

Fonds des abonnements​

Chemin de base : /giving/subscriptionfunds

Suit les répartitions par fonds des abonnements récurrents. Aucune route CRUD de base n'est activée ; tous les points de terminaison sont personnalisés.

MéthodeCheminAuthAutorisationDescription
GET/JWTDonations.View ou son propre abonnementLister les fonds des abonnements. Filtrer par ?subscriptionId=
GET/:idJWTDonations.ViewSummaryObtenir un fonds d'abonnement par ID
DELETE/:idJWTDonations.EditSupprimer un fonds d'abonnement
DELETE/subscription/:idJWTDonations.Edit ou son propre abonnementSupprimer tous les fonds d'un abonnement

Moyens de paiement​

Chemin de base : /giving/paymentmethods

Gère les moyens de paiement enregistrés (cartes, comptes bancaires) par l'intermédiaire des API des passerelles de paiement. Aucune route CRUD de base n'est activée ; tous les points de terminaison sont personnalisés.

MéthodeCheminAuthAutorisationDescription
GET/personid/:idJWTDonations.View ou son propre personIdObtenir tous les moyens de paiement enregistrés d'une personne (cartes, comptes bancaires)
POST/addcardJWT—Joindre un moyen de paiement par carte. Corps : { id, personId, customerId, email, name, churchId, provider }
POST/updatecardJWTDonations.Edit ou son propre personIdMettre à jour les renseignements de la carte. Corps : { personId, paymentMethodId, cardData, provider }
POST/ach-setup-intentJWTDonations.Edit ou son propre personIdCréer un SetupIntent ACH Stripe pour relier un compte bancaire. Corps : { personId, customerId, email, name, churchId }
POST/ach-setup-intent-anonPublique—Créer un SetupIntent ACH anonyme pour les dons de visiteurs. Corps : { email, name, churchId, gatewayId }
POST/addbankaccountJWTDonations.Edit ou son propre personIdAjouter un compte bancaire par jeton (déprécié ; utilisez ach-setup-intent). Corps : { id, personId, customerId, email, name }
POST/updatebankJWTDonations.Edit ou son propre personIdMettre à jour les renseignements d'un compte bancaire. Corps : { paymentMethodId, personId, bankData, customerId }
POST/verifybankJWTDonations.Edit ou son propre clientVérifier un compte bancaire par micro-dépôts. Corps : { paymentMethodId, customerId, amountData }
DELETE/:id/:customeridJWTDonations.Edit ou son propre clientSupprimer un moyen de paiement (carte ou compte bancaire)

Journal des événements​

Chemin de base : /giving/eventLog

Hérite de GenericCrudController avec les routes CRUD : getById, getAll, post, delete. Suit les événements de webhook de la passerelle de paiement pour la vérification et la déduplication.

MéthodeCheminAuthAutorisationDescription
GET/JWTDonations.ViewSummaryLister tous les journaux d'événements
GET/:idJWTDonations.ViewSummaryObtenir un journal d'événements par ID
GET/type/:typeJWTDonations.ViewSummaryObtenir les journaux d'événements filtrés par type d'événement
POST/JWTDonations.EditCréer ou mettre à jour des journaux d'événements
DELETE/:idJWTDonations.EditSupprimer un journal d'événements

Pages connexes​