Hopp til hovedinnhold

Giving-endepunkter

Giving-modulen administrerer gaver, fond, betalingsbehandling, abonnementer og relaterte økonomiske operasjoner. Den støtter flere betalingsløsninger (Stripe, PayPal), håndterer engangs- og gjentakende gaver, følger gavebunter, og tilbyr webhook-behandling for asynkrone betalingshendelser.

Basisti: /giving

Gaver​

Basisti: /giving/donations

MetodeStiAutentiseringTillatelseBeskrivelse
GET/JWTDonations.View eller egen personIdList alle gaver. Filtrer med ?batchId= eller ?personId=. Med ?personId= utelates gaver til ikke-fradragsberettigede fond (som på giveroppgaver) med mindre en innringer med Donations.View legger til &includeNonDeductible=1, som B1Admins personpost gjør
GET/:idJWTDonations.ViewHent en gave etter ID
GET/myJWT—Hent gjeldende brukers gaver
GET/my/summary?year=JWT—Gjeldende brukers givertotal for et år (standard er inneværende år): { year, total, count, currency, isConverted }, med totaler konvertert til kirkens valuta. Brukes av giveforhåndsvisningen på hjemmesiden for medlemmer
GET/?startDate=&endDate=JWTDonations.ViewGaver datert innenfor intervallet (inkludert). Begge datoene kreves som YYYY-MM-DD, ellers 400. B1Admins giveroppgavesider ber om ett kalenderår på denne måten i stedet for kirkens fulle historikk
GET/summaryJWTDonations.ViewSummaryHent gaveoppsummering. Filtrer med ?startDate=&endDate=&type=. Bruk type=person for oppdeling per person
GET/testEmailOffentlig—Send en teste-post (utvikling/feilsøking)
POST/JWTDonations.Edit eller Donations.EnterOpprett eller oppdater gaver (bunt). Med bare Donations.Enter må både målbunten og (ved oppdatering) gavens nåværende bunt være åpne, og gatewaygaver (de med en transactionId) kan ikke endres; ellers 403 { "error": "This batch is closed." }
DELETE/:idJWTDonations.Edit eller Donations.EnterSlett en gave. Bare Donations.Enter: gaven må ligge i en åpen bunt og ikke være en gatewaygave, ellers 403

Eksempel: List gaver etter bunt​

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

Eksempel: Hent gaveoppsummering​

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

Gavebunter​

Basisti: /giving/donationbatches

Utvider GenericCrudController med CRUD-ruter: getById, getAll, post, delete. Sletteoperasjonen fjerner også alle gaver i bunten.

MetodeStiAutentiseringTillatelseBeskrivelse
GET/JWTDonations.ViewSummary eller Donations.EnterList alle gavebunter
GET/:idJWTDonations.ViewSummary eller Donations.EnterHent en gavebunt etter ID
POST/JWTDonations.Edit eller Donations.EnterOpprett eller oppdater gavebunter. Bare Donations.Enter: å oppdatere en eksisterende bunt krever at den er åpen, ellers 403 { "error": "This batch is closed." }. status ignoreres her, så lagring av en bunt kan ikke gjenåpne den
POST/:id/closeJWTDonations.EditLukk en bunt: setter status til closed, closedDate til nå, og closedBy til den innringendes bruker-ID. Returnerer bunten
POST/:id/reopenJWTDonations.EditGjenåpne en bunt: setter status til open og fjerner closedDate og closedBy. Returnerer bunten
DELETE/:idJWTDonations.EditSlett en bunt og alle dens gaver

Hver bunt inkluderer status (open eller closed; nye og eksisterende bunter er open), closedDate og closedBy. Donations.Edit kan endre gaver i alle bunter; Donations.Enter (vist som Registrer gaver i rolleredigeringsprogrammet) kan bare legge til, endre eller slette gaver og fondsfordelinger mens bunten er åpen.

Donasjon​

Basisti: /giving/donate

Håndterer den offentlige giveflyten, inkludert belastninger, abonnementer, webhooks og gebyrberegninger. Ingen basis-CRUD-ruter er aktivert; alle endepunkter er egendefinerte.

MetodeStiAutentiseringTillatelseBeskrivelse
GET/gateways/:churchIdOffentlig—Hent tilgjengelige betalingsløsninger for en kirke (kun offentlige nøkler)
POST/client-tokenJWT—Generer et klienttoken for initialisering av betalingsløsningen
POST/create-orderJWT—Opprett en betalingsordre (PayPal-stil kassen)
POST/chargeJWT—Behandle en engangs gavebelastning
POST/subscribeJWT—Opprett et gjentakende gaveabonnement
POST/logOffentlig—Logg en gave. Body: { donation, fundData }
POST/webhook/:providerOffentlig—Motta webhook-hendelser for betaling (Stripe, PayPal). Krever ?churchId=
POST/replay-stripe-eventsJWTDonations.EditSpill av Stripe-hendelser for et datointervall. Body: { startDate, endDate, dryRun }
POST/feeOffentlig—Beregn transaksjonsgebyrer. Body: { type, provider, gatewayId, amount, currency }. Krever ?churchId=
POST/captcha-verifyOffentlig—Verifiser reCAPTCHA-token. Body: { token, churchId? }. Et menneskelig svar returnerer { response: "human", pass }, der pass er et signert gjestegivepass som gjelder i 10 minutter (og bare for churchId når en sendes)

Når API-et kjøres med CAPTCHA_ENFORCE=true, må kall fra gjester (ikke innloggede) til /giving/donate/create-order, /charge, /subscribe, /giving/paymentmethods/addcard og /giving/paymentmethods/ach-setup-intent-anon (og gjester med priset POST /content/registrations/register-kall) inkludere captchaPass i body, ellers returneres 403 Captcha verification required. Passet kan gjenbrukes til det utløper, fordi gjestflyten for Stripe gjør to kall (legg til kort, deretter belastning). Kall fra innloggede brukere påvirkes ikke. CAPTCHA_ENFORCE er som standard false; skjemaene for gjestegivning i @churchapps/apphelper sender passet automatisk.

Eksempel: Behandle en gavebelastning​

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

Eksempel: Opprett et gjentakende abonnement​

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

Fond​

Basisti: /giving/funds

Utvider GenericCrudController med CRUD-ruter: getById, getAll, post, delete. Tillatelsen view er null (ingen tillatelse kreves for å se fond).

MetodeStiAutentiseringTillatelseBeskrivelse
GET/JWT—List alle fond
GET/:idJWT—Hent et fond etter ID
GET/churchId/:churchIdOffentlig—Hent alle fond for en bestemt kirke (offentlig)
GET/public/:churchId/:fundId/total?startDate=&endDate=Offentlig—Hent et fonds gavetotal: { fundId, totalAmount, donationCount }. Driver elementet campaignProgress i nettstedsbyggeren
POST/JWTDonations.EditOpprett eller oppdater fond
DELETE/:idJWTDonations.EditSlett et fond

Fondgaver​

Basisti: /giving/funddonations

Sporer hvordan enkeltgaver fordeles på fond. Ingen basis-CRUD-ruter er aktivert; alle endepunkter er egendefinerte.

MetodeStiAutentiseringTillatelseBeskrivelse
GET/JWTDonations.ViewList fondgaver. Filtrer med ?donationId=, ?personId=, ?fundId= eller ?fundName=. Du kan valgfritt legge til ?startDate=&endDate= for datofiltrering
GET/:idJWTDonations.ViewHent en fondgave etter ID
GET/myJWT—Hent gjeldende brukers fondgaver
POST/JWTDonations.Edit eller Donations.EnterOpprett eller oppdater fondgaver (bunt). Bare Donations.Enter: den overordnede gaven må ligge i en åpen bunt og ikke være en gatewaygave, ellers 403
DELETE/:idJWTDonations.Edit eller Donations.EnterSlett en fondgave. Samme regel for åpen bunt for Donations.Enter

Gatewayer​

Basisti: /giving/gateways

Administrerer konfigurasjoner for betalingsløsninger (Stripe, PayPal osv.). Ingen basis-CRUD-ruter er aktivert; alle endepunkter er egendefinerte. Hemmeligheter for gatewayer lagres kryptert i hvile.

MetodeStiAutentiseringTillatelseBeskrivelse
GET/JWT—List alle gatewayer for kirken
GET/:idJWTSettings.EditHent en gateway etter ID
GET/churchId/:churchIdOffentlig—Hent gatewayer for en kirke (kun offentlige nøkler)
GET/configured/:churchIdOffentlig—Sjekk om en kirke har en konfigurert betalingsgateway
POST/JWTSettings.EditOpprett eller oppdater gatewayer (krypterer nøkler, oppretter webhooks og produkter)
PATCH/:idJWTSettings.EditOppdater en gateway delvis
DELETE/:idJWTSettings.EditSlett en gateway (fjerner også dens webhooks)

Eksempel: Sjekk gatewaykonfigurasjon​

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

Kunder​

Basisti: /giving/customers

Utvider GenericCrudController med CRUD-ruter: getAll, delete. Kobler personer til deres kunderegistreringer hos betalingsgatewayen.

MetodeStiAutentiseringTillatelseBeskrivelse
GET/JWTDonations.ViewSummaryList alle kunder
GET/:idJWTDonations.ViewSummary eller egen postHent en kunde etter ID
GET/:id/subscriptionsJWTDonations.ViewSummary eller egen postHent abonnementer hos gatewayen for en kunde
DELETE/:idJWTDonations.EditSlett en kunde

Abonnementer​

Basisti: /giving/subscriptions

Administrerer gjentakende gaveabonnementer. Ingen basis-CRUD-ruter er aktivert; alle endepunkter er egendefinerte.

MetodeStiAutentiseringTillatelseBeskrivelse
GET/JWTDonations.ViewSummaryList alle abonnementer
GET/:idJWTDonations.ViewSummaryHent et abonnement etter ID
POST/JWTDonations.Edit eller eget abonnementOppdater abonnementer hos betalingsgatewayen
DELETE/:idJWTDonations.Edit eller eget abonnementAvslutt et abonnement og fjern det fra databasen. Body: { provider, reason }

Fond for abonnementer​

Basisti: /giving/subscriptionfunds

Sporer fondfordelinger for gjentakende abonnementer. Ingen basis-CRUD-ruter er aktivert; alle endepunkter er egendefinerte.

MetodeStiAutentiseringTillatelseBeskrivelse
GET/JWTDonations.View eller eget abonnementList fond for abonnementer. Filtrer med ?subscriptionId=
GET/:idJWTDonations.ViewSummaryHent et fond for abonnement etter ID
DELETE/:idJWTDonations.EditSlett et fond for abonnement
DELETE/subscription/:idJWTDonations.Edit eller eget abonnementSlett alle fond for et abonnement

Betalingsmetoder​

Basisti: /giving/paymentmethods

Administrerer lagrede betalingsmetoder (kort, bankkontoer) via betalingsgatewayens API-er. Ingen basis-CRUD-ruter er aktivert; alle endepunkter er egendefinerte.

MetodeStiAutentiseringTillatelseBeskrivelse
GET/personid/:idJWTDonations.View eller egen personIdHent alle lagrede betalingsmetoder for en person (kort, bankkontoer)
POST/addcardJWT—Legg til en kortbetalingsmetode. Body: { id, personId, customerId, email, name, churchId, provider }
POST/updatecardJWTDonations.Edit eller egen personIdOppdater kortdetaljer. Body: { personId, paymentMethodId, cardData, provider }
POST/ach-setup-intentJWTDonations.Edit eller egen personIdOpprett en Stripe ACH SetupIntent for kobling av bankkonto. Body: { personId, customerId, email, name, churchId }
POST/ach-setup-intent-anonOffentlig—Opprett en anonym ACH SetupIntent for gjestegaver. Body: { email, name, churchId, gatewayId }
POST/addbankaccountJWTDonations.Edit eller egen personIdLegg til en bankkonto via token (utdatert; bruk ach-setup-intent). Body: { id, personId, customerId, email, name }
POST/updatebankJWTDonations.Edit eller egen personIdOppdater bankkontodetaljer. Body: { paymentMethodId, personId, bankData, customerId }
POST/verifybankJWTDonations.Edit eller egen kundeVerifiser en bankkonto med småbeløp. Body: { paymentMethodId, customerId, amountData }
DELETE/:id/:customeridJWTDonations.Edit eller egen kundeSlett en betalingsmetode (kort eller bankkonto)

Hendelseslogg​

Basisti: /giving/eventLog

Utvider GenericCrudController med CRUD-ruter: getById, getAll, post, delete. Sporer webhook-hendelser fra betalingsgatewayer for revisjon og deduplisering.

MetodeStiAutentiseringTillatelseBeskrivelse
GET/JWTDonations.ViewSummaryList alle hendelseslogger
GET/:idJWTDonations.ViewSummaryHent en hendelseslogg etter ID
GET/type/:typeJWTDonations.ViewSummaryHent hendelseslogger filtrert etter hendelsestype
POST/JWTDonations.EditOpprett eller oppdater hendelseslogger
DELETE/:idJWTDonations.EditSlett en hendelseslogg

Relaterte sider​