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
| Methode | Pfad | Auth | Berechtigung | Beschreibung |
|---|---|---|---|---|
| GET | / | JWT | Donations.View oder eigene personId | Alle 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 | /:id | JWT | Donations.View | Eine Spende anhand der ID abrufen |
| GET | /my | JWT | — | 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= | JWT | Donations.View | Spenden 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 | /summary | JWT | Donations.ViewSummary | Spendenzusammenfassung 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 | / | JWT | Donations.Edit oder Donations.Enter | Spenden (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 | /:id | JWT | Donations.Edit oder Donations.Enter | Eine 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.
| Methode | Pfad | Auth | Berechtigung | Beschreibung |
|---|---|---|---|---|
| GET | / | JWT | Donations.ViewSummary oder Donations.Enter | Alle Spendenstapel auflisten |
| GET | /:id | JWT | Donations.ViewSummary oder Donations.Enter | Einen Spendenstapel anhand der ID abrufen |
| POST | / | JWT | Donations.Edit oder Donations.Enter | Spendenstapel 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/close | JWT | Donations.Edit | Einen 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/reopen | JWT | Donations.Edit | Einen Stapel wieder öffnen: setzt status auf open und leert closedDate und closedBy. Gibt den Stapel zurück |
| DELETE | /:id | JWT | Donations.Edit | Einen 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.
| Methode | Pfad | Auth | Berechtigung | Beschreibung |
|---|---|---|---|---|
| GET | /gateways/:churchId | Öffentlich | — | Verfügbare Zahlungsgateways einer Gemeinde abrufen (nur öffentliche Schlüssel) |
| POST | /client-token | JWT | — | Client-Token für die Initialisierung des Gateways erzeugen |
| POST | /create-order | JWT | — | Eine Zahlungsbestellung erstellen (Checkout im PayPal-Stil) |
| POST | /charge | JWT | — | Eine einmalige Spendenbelastung verarbeiten |
| POST | /subscribe | JWT | — | 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-events | JWT | Donations.Edit | Stripe-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).
| Methode | Pfad | Auth | Berechtigung | Beschreibung |
|---|---|---|---|---|
| GET | / | JWT | — | Alle Fonds auflisten |
| GET | /:id | JWT | — | 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 | / | JWT | Donations.Edit | Fonds erstellen oder aktualisieren |
| DELETE | /:id | JWT | Donations.Edit | Einen 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.
| Methode | Pfad | Auth | Berechtigung | Beschreibung |
|---|---|---|---|---|
| GET | / | JWT | Donations.View | Fondsspenden auflisten. Filtern mit ?donationId=, ?personId=, ?fundId= oder ?fundName=. Optional mit ?startDate=&endDate= nach Datum eingrenzen |
| GET | /:id | JWT | Donations.View | Eine Fondsspende anhand der ID abrufen |
| GET | /my | JWT | — | Fondsspenden des aktuellen Benutzers abrufen |
| POST | / | JWT | Donations.Edit oder Donations.Enter | Fondsspenden (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 | /:id | JWT | Donations.Edit oder Donations.Enter | Eine 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.
| Methode | Pfad | Auth | Berechtigung | Beschreibung |
|---|---|---|---|---|
| GET | / | JWT | — | Alle Gateways der Gemeinde auflisten |
| GET | /:id | JWT | Settings.Edit | Ein 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 | / | JWT | Settings.Edit | Gateways erstellen oder aktualisieren (verschlüsselt Schlüssel, richtet Webhooks und Produkte ein) |
| PATCH | /:id | JWT | Settings.Edit | Ein Gateway teilweise aktualisieren |
| DELETE | /:id | JWT | Settings.Edit | Ein 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.
| Methode | Pfad | Auth | Berechtigung | Beschreibung |
|---|---|---|---|---|
| GET | / | JWT | Donations.ViewSummary | Alle Kunden auflisten |
| GET | /:id | JWT | Donations.ViewSummary oder eigener Datensatz | Einen Kunden anhand der ID abrufen |
| GET | /:id/subscriptions | JWT | Donations.ViewSummary oder eigener Datensatz | Gateway-Abonnements eines Kunden abrufen |
| DELETE | /:id | JWT | Donations.Edit | Einen Kunden löschen |
Abonnements
Basispfad: /giving/subscriptions
Verwaltet wiederkehrende Spendenabonnements. Es sind keine CRUD-Basisrouten aktiviert; alle Endpunkte sind benutzerdefiniert.
| Methode | Pfad | Auth | Berechtigung | Beschreibung |
|---|---|---|---|---|
| GET | / | JWT | Donations.ViewSummary | Alle Abonnements auflisten |
| GET | /:id | JWT | Donations.ViewSummary | Ein Abonnement anhand der ID abrufen |
| POST | / | JWT | Donations.Edit oder eigenes Abonnement | Abonnements beim Zahlungsgateway aktualisieren |
| DELETE | /:id | JWT | Donations.Edit oder eigenes Abonnement | Ein 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.
| Methode | Pfad | Auth | Berechtigung | Beschreibung |
|---|---|---|---|---|
| GET | / | JWT | Donations.View oder eigenes Abonnement | Abonnement-Fonds auflisten. Filtern mit ?subscriptionId= |
| GET | /:id | JWT | Donations.ViewSummary | Einen Abonnement-Fonds anhand der ID abrufen |
| DELETE | /:id | JWT | Donations.Edit | Einen Abonnement-Fonds löschen |
| DELETE | /subscription/:id | JWT | Donations.Edit oder eigenes Abonnement | Alle 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.
| Methode | Pfad | Auth | Berechtigung | Beschreibung |
|---|---|---|---|---|
| GET | /personid/:id | JWT | Donations.View oder eigene personId | Alle gespeicherten Zahlungsmethoden einer Person abrufen (Karten, Bankkonten) |
| POST | /addcard | JWT | — | Eine Kartenzahlungsmethode hinzufügen. Body: { id, personId, customerId, email, name, churchId, provider } |
| POST | /updatecard | JWT | Donations.Edit oder eigene personId | Kartendaten aktualisieren. Body: { personId, paymentMethodId, cardData, provider } |
| POST | /ach-setup-intent | JWT | Donations.Edit oder eigene personId | Einen 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 | /addbankaccount | JWT | Donations.Edit oder eigene personId | Ein Bankkonto über ein Token hinzufügen (veraltet; verwenden Sie ach-setup-intent). Body: { id, personId, customerId, email, name } |
| POST | /updatebank | JWT | Donations.Edit oder eigene personId | Bankkontodaten aktualisieren. Body: { paymentMethodId, personId, bankData, customerId } |
| POST | /verifybank | JWT | Donations.Edit oder eigener Kunde | Ein Bankkonto mit Kleinstbeträgen (Micro-Deposits) verifizieren. Body: { paymentMethodId, customerId, amountData } |
| DELETE | /:id/:customerid | JWT | Donations.Edit oder eigener Kunde | Eine 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.
| Methode | Pfad | Auth | Berechtigung | Beschreibung |
|---|---|---|---|---|
| GET | / | JWT | Donations.ViewSummary | Alle Ereignisprotokolle auflisten |
| GET | /:id | JWT | Donations.ViewSummary | Ein Ereignisprotokoll anhand der ID abrufen |
| GET | /type/:type | JWT | Donations.ViewSummary | Ereignisprotokolle nach Ereignistyp gefiltert abrufen |
| POST | / | JWT | Donations.Edit | Ereignisprotokolle erstellen oder aktualisieren |
| DELETE | /:id | JWT | Donations.Edit | Ein Ereignisprotokoll löschen |
Verwandte Seiten
- Membership-Endpunkte — Personen, Gemeinden, Gruppen, Rollen und Berechtigungen
- Authentifizierung und Berechtigungen — Anmeldeablauf, JWT, OAuth, Berechtigungsmodell
- Modulstruktur — Muster der Code-Organisation