Zum Hauptinhalt springen

Giving-Endpunkte

Das Giving-Modul verwaltet Spenden, Fonds, Zahlungsabwicklung, Daueraufträge und verwandte Finanzvorgänge. Es unterstützt mehrere Zahlungsgateways (Stripe, PayPal), verarbeitet einmalige und wiederkehrende Spenden, verfolgt Spendenstapel und bietet Webhook-Verarbeitung für asynchrone Zahlungsereignisse.

Basispfad: /giving

Spenden​

Basispfad: /giving/donations

MethodePfadAuthBerechtigungBeschreibung
GET/JWTDonations.View oder eigene personIdAlle Spenden auflisten. Filtern mit ?batchId= oder ?personId=. Bei ?personId= werden Zuwendungen an nicht absetzbare Fonds ausgelassen (wie auf Spendenbescheinigungen), sofern der Aufrufer mit Donations.View nicht &includeNonDeductible=1 anhängt. Das tut der Personendatensatz von B1Admin
GET/:idJWTDonations.ViewEine Spende anhand der ID abrufen
GET/myJWT—Spenden des aktuellen Benutzers abrufen
GET/my/summary?year=JWT—Spendensumme des aktuellen Benutzers für ein Jahr (standardmäßig dieses Jahr): { year, total, count, currency, isConverted }; die Summen werden in die Gemeindewährung umgerechnet. Liefert die Daten für die Spendenvorschau auf der Startseite der Mitglieder
GET/?startDate=&endDate=JWTDonations.ViewSpenden innerhalb des Zeitraums (einschließlich). Beide Daten sind als YYYY-MM-DD erforderlich, andernfalls 400. Die Spendenbescheinigungsseiten von B1Admin fragen auf diese Weise ein Kalenderjahr ab, statt der gesamten Historie der Gemeinde
GET/summaryJWTDonations.ViewSummarySpendenzusammenfassung abrufen. Filtern mit ?startDate=&endDate=&type=. Verwenden Sie type=person für eine Aufschlüsselung pro Person
GET/testEmailÖffentlich—Eine Test-E-Mail senden (Entwicklung/Fehlersuche)
POST/JWTDonations.Edit oder Donations.EnterSpenden (als Stapel) erstellen oder aktualisieren. Bei alleiniger Berechtigung Donations.Enter müssen sowohl der Zielstapel als auch (bei einer Aktualisierung) der aktuelle Stapel der Spende geöffnet sein; Gateway-Zahlungen (mit transactionId) können nicht geändert werden. Andernfalls 403 { "error": "This batch is closed." }
DELETE/:idJWTDonations.Edit oder Donations.EnterEine Spende löschen. Nur Donations.Enter: Die Spende muss in einem geöffneten Stapel liegen und darf keine Gateway-Zahlung sein, andernfalls 403

Beispiel: Spenden nach Stapel auflisten​

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"
}
]

Beispiel: Spendenzusammenfassung abrufen​

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
}
]

Spendenstapel​

Basispfad: /giving/donationbatches

Erweitert GenericCrudController mit CRUD-Routen: getById, getAll, post, delete. Der Löschvorgang entfernt außerdem alle Spenden innerhalb des Stapels.

MethodePfadAuthBerechtigungBeschreibung
GET/JWTDonations.ViewSummary oder Donations.EnterAlle Spendenstapel auflisten
GET/:idJWTDonations.ViewSummary oder Donations.EnterEinen Spendenstapel anhand der ID abrufen
POST/JWTDonations.Edit oder Donations.EnterSpendenstapel erstellen oder aktualisieren. Nur Donations.Enter: Das Aktualisieren eines bestehenden Stapels setzt voraus, dass er geöffnet ist, andernfalls 403 { "error": "This batch is closed." }. status wird hier ignoriert, sodass das Speichern eines Stapels ihn nicht wieder öffnen kann
POST/:id/closeJWTDonations.EditEinen Stapel schließen: setzt status auf closed, closedDate auf den aktuellen Zeitpunkt und closedBy auf die Benutzer-ID des Aufrufers. Gibt den Stapel zurück
POST/:id/reopenJWTDonations.EditEinen Stapel wieder öffnen: setzt status auf open und leert closedDate und closedBy. Gibt den Stapel zurück
DELETE/:idJWTDonations.EditEinen Stapel und alle seine Spenden löschen

Jeder Stapel enthält status (open oder closed; neue und bereits vorhandene Stapel sind open), closedDate und closedBy. Donations.Edit kann Spenden in jedem Stapel ändern. Donations.Enter (im Rollen-Editor als Spenden erfassen angezeigt) kann Spenden und Fondsaufteilungen nur hinzufügen, ändern oder löschen, solange deren Stapel geöffnet ist.

Spenden (Donate)​

Basispfad: /giving/donate

Verarbeitet den öffentlichen Spendenablauf einschließlich Belastungen, Daueraufträgen, Webhooks und Gebührenberechnungen. Es sind keine CRUD-Basisrouten aktiviert; alle Endpunkte sind benutzerdefiniert.

MethodePfadAuthBerechtigungBeschreibung
GET/gateways/:churchIdÖffentlich—Verfügbare Zahlungsgateways einer Gemeinde abrufen (nur öffentliche Schlüssel)
POST/client-tokenJWT—Client-Token für die Initialisierung des Gateways erzeugen
POST/create-orderJWT—Eine Zahlungsbestellung erstellen (Checkout im PayPal-Stil)
POST/chargeJWT—Eine einmalige Spendenbelastung verarbeiten
POST/subscribeJWT—Ein wiederkehrendes Spenden-Abonnement erstellen
POST/logÖffentlich—Eine Spende protokollieren. Body: { donation, fundData }
POST/webhook/:providerÖffentlich—Zahlungs-Webhook-Ereignisse empfangen (Stripe, PayPal). Erfordert ?churchId=
POST/replay-stripe-eventsJWTDonations.EditStripe-Ereignisse für einen Zeitraum erneut abspielen. Body: { startDate, endDate, dryRun }
POST/feeÖffentlich—Transaktionsgebühren berechnen. Body: { type, provider, gatewayId, amount, currency }. Erfordert ?churchId=
POST/captcha-verifyÖffentlich—reCAPTCHA-Token prüfen. Body: { token, churchId? }. Eine menschliche Antwort liefert { response: "human", pass }, wobei pass ein signierter Gast-Spendenpass ist, der 10 Minuten gültig ist (und nur für churchId gilt, falls eine übermittelt wurde)

Wenn die API mit CAPTCHA_ENFORCE=true läuft, müssen Gastaufrufe (ohne Anmeldung) an /giving/donate/create-order, /charge, /subscribe, /giving/paymentmethods/addcard und /giving/paymentmethods/ach-setup-intent-anon das captchaPass im Body enthalten. Andernfalls antworten sie mit 403 Captcha verification required. Der Pass kann bis zu seinem Ablauf wiederverwendet werden, da der Stripe-Gastablauf zwei Aufrufe ausführt (Karte hinterlegen, dann belasten). Aufrufe von angemeldeten Benutzern sind nicht betroffen. CAPTCHA_ENFORCE ist standardmäßig false; die Gastspendenformulare von @churchapps/apphelper senden den Pass automatisch.

Beispiel: Spendenbelastung verarbeiten​

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"
}

Beispiel: Wiederkehrendes Abonnement erstellen​

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​

Basispfad: /giving/funds

Erweitert GenericCrudController mit CRUD-Routen: getById, getAll, post, delete. Die Berechtigung view ist null (zum Anzeigen von Fonds ist keine Berechtigung erforderlich).

MethodePfadAuthBerechtigungBeschreibung
GET/JWT—Alle Fonds auflisten
GET/:idJWT—Einen Fonds anhand der ID abrufen
GET/churchId/:churchIdÖffentlich—Alle Fonds einer bestimmten Gemeinde abrufen (öffentlich)
GET/public/:churchId/:fundId/total?startDate=&endDate=Öffentlich—Die Spendensumme eines Fonds abrufen: { fundId, totalAmount, donationCount }. Versorgt das Element campaignProgress des Website-Builders
POST/JWTDonations.EditFonds erstellen oder aktualisieren
DELETE/:idJWTDonations.EditEinen Fonds löschen

Fondsspenden​

Basispfad: /giving/funddonations

Erfasst, wie einzelne Spenden auf Fonds verteilt werden. Es sind keine CRUD-Basisrouten aktiviert; alle Endpunkte sind benutzerdefiniert.

MethodePfadAuthBerechtigungBeschreibung
GET/JWTDonations.ViewFondsspenden auflisten. Filtern mit ?donationId=, ?personId=, ?fundId= oder ?fundName=. Optional mit ?startDate=&endDate= nach Datum eingrenzen
GET/:idJWTDonations.ViewEine Fondsspende anhand der ID abrufen
GET/myJWT—Fondsspenden des aktuellen Benutzers abrufen
POST/JWTDonations.Edit oder Donations.EnterFondsspenden (als Stapel) erstellen oder aktualisieren. Nur Donations.Enter: Die übergeordnete Spende muss in einem geöffneten Stapel liegen und darf keine Gateway-Zahlung sein, andernfalls 403
DELETE/:idJWTDonations.Edit oder Donations.EnterEine Fondsspende löschen. Für Donations.Enter gilt dieselbe Regel zum geöffneten Stapel

Gateways​

Basispfad: /giving/gateways

Verwaltet die Konfiguration der Zahlungsgateways (Stripe, PayPal usw.). Es sind keine CRUD-Basisrouten aktiviert; alle Endpunkte sind benutzerdefiniert. Gateway-Geheimnisse werden im Ruhezustand verschlüsselt.

MethodePfadAuthBerechtigungBeschreibung
GET/JWT—Alle Gateways der Gemeinde auflisten
GET/:idJWTSettings.EditEin Gateway anhand der ID abrufen
GET/churchId/:churchIdÖffentlich—Gateways einer Gemeinde abrufen (nur öffentliche Schlüssel)
GET/configured/:churchIdÖffentlich—Prüfen, ob für eine Gemeinde ein Zahlungsgateway konfiguriert ist
POST/JWTSettings.EditGateways erstellen oder aktualisieren (verschlüsselt Schlüssel, richtet Webhooks und Produkte ein)
PATCH/:idJWTSettings.EditEin Gateway teilweise aktualisieren
DELETE/:idJWTSettings.EditEin Gateway löschen (entfernt auch dessen Webhooks)

Beispiel: Gateway-Konfiguration prüfen​

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

Kunden​

Basispfad: /giving/customers

Erweitert GenericCrudController mit CRUD-Routen: getAll, delete. Verknüpft Personen mit ihren Kundendatensätzen beim Zahlungsgateway.

MethodePfadAuthBerechtigungBeschreibung
GET/JWTDonations.ViewSummaryAlle Kunden auflisten
GET/:idJWTDonations.ViewSummary oder eigener DatensatzEinen Kunden anhand der ID abrufen
GET/:id/subscriptionsJWTDonations.ViewSummary oder eigener DatensatzGateway-Abonnements eines Kunden abrufen
DELETE/:idJWTDonations.EditEinen Kunden löschen

Abonnements​

Basispfad: /giving/subscriptions

Verwaltet wiederkehrende Spendenabonnements. Es sind keine CRUD-Basisrouten aktiviert; alle Endpunkte sind benutzerdefiniert.

MethodePfadAuthBerechtigungBeschreibung
GET/JWTDonations.ViewSummaryAlle Abonnements auflisten
GET/:idJWTDonations.ViewSummaryEin Abonnement anhand der ID abrufen
POST/JWTDonations.Edit oder eigenes AbonnementAbonnements beim Zahlungsgateway aktualisieren
DELETE/:idJWTDonations.Edit oder eigenes AbonnementEin Abonnement kündigen und aus der Datenbank entfernen. Body: { provider, reason }

Abonnement-Fonds​

Basispfad: /giving/subscriptionfunds

Erfasst die Fondszuordnungen für wiederkehrende Abonnements. Es sind keine CRUD-Basisrouten aktiviert; alle Endpunkte sind benutzerdefiniert.

MethodePfadAuthBerechtigungBeschreibung
GET/JWTDonations.View oder eigenes AbonnementAbonnement-Fonds auflisten. Filtern mit ?subscriptionId=
GET/:idJWTDonations.ViewSummaryEinen Abonnement-Fonds anhand der ID abrufen
DELETE/:idJWTDonations.EditEinen Abonnement-Fonds löschen
DELETE/subscription/:idJWTDonations.Edit oder eigenes AbonnementAlle Fonds eines Abonnements löschen

Zahlungsmethoden​

Basispfad: /giving/paymentmethods

Verwaltet gespeicherte Zahlungsmethoden (Karten, Bankkonten) über die APIs der Zahlungsgateways. Es sind keine CRUD-Basisrouten aktiviert; alle Endpunkte sind benutzerdefiniert.

MethodePfadAuthBerechtigungBeschreibung
GET/personid/:idJWTDonations.View oder eigene personIdAlle gespeicherten Zahlungsmethoden einer Person abrufen (Karten, Bankkonten)
POST/addcardJWT—Eine Kartenzahlungsmethode hinzufügen. Body: { id, personId, customerId, email, name, churchId, provider }
POST/updatecardJWTDonations.Edit oder eigene personIdKartendaten aktualisieren. Body: { personId, paymentMethodId, cardData, provider }
POST/ach-setup-intentJWTDonations.Edit oder eigene personIdEinen Stripe-ACH-SetupIntent für die Verknüpfung eines Bankkontos erstellen. Body: { personId, customerId, email, name, churchId }
POST/ach-setup-intent-anonÖffentlich—Einen anonymen ACH-SetupIntent für Gastspenden erstellen. Body: { email, name, churchId, gatewayId }
POST/addbankaccountJWTDonations.Edit oder eigene personIdEin Bankkonto über ein Token hinzufügen (veraltet; verwenden Sie ach-setup-intent). Body: { id, personId, customerId, email, name }
POST/updatebankJWTDonations.Edit oder eigene personIdBankkontodaten aktualisieren. Body: { paymentMethodId, personId, bankData, customerId }
POST/verifybankJWTDonations.Edit oder eigener KundeEin Bankkonto mit Kleinstbeträgen (Micro-Deposits) verifizieren. Body: { paymentMethodId, customerId, amountData }
DELETE/:id/:customeridJWTDonations.Edit oder eigener KundeEine Zahlungsmethode (Karte oder Bankkonto) löschen

Ereignisprotokoll​

Basispfad: /giving/eventLog

Erweitert GenericCrudController mit CRUD-Routen: getById, getAll, post, delete. Protokolliert Webhook-Ereignisse der Zahlungsgateways zur Prüfung und Duplikatserkennung.

MethodePfadAuthBerechtigungBeschreibung
GET/JWTDonations.ViewSummaryAlle Ereignisprotokolle auflisten
GET/:idJWTDonations.ViewSummaryEin Ereignisprotokoll anhand der ID abrufen
GET/type/:typeJWTDonations.ViewSummaryEreignisprotokolle nach Ereignistyp gefiltert abrufen
POST/JWTDonations.EditEreignisprotokolle erstellen oder aktualisieren
DELETE/:idJWTDonations.EditEin Ereignisprotokoll löschen

Verwandte Seiten​