Skip to main content

Giving Endpoints

The Giving module manages donations, funds, payment processing, subscriptions, and related financial operations. It supports multiple payment gateways (Stripe, PayPal), handles one-time and recurring donations, tracks donation batches, and provides webhook processing for asynchronous payment events.

Base path: /giving

Donations​

Base path: /giving/donations

MethodPathAuthPermissionDescription
GET/JWTDonations.View or own personIdList all donations. Filter by ?batchId= or ?personId=. With ?personId=, gifts to non-deductible funds are left out (as on giving statements) unless a Donations.View caller adds &includeNonDeductible=1, which B1Admin's person record does
GET/:idJWTDonations.ViewGet a donation by ID
GET/myJWT—Get current user's donations
GET/my/summary?year=JWT—Current user's giving total for a year (default this year): { year, total, count, currency, isConverted }, with totals converted to the church currency. Backs the giving preview on the member home page
GET/?startDate=&endDate=JWTDonations.ViewDonations dated within the range (inclusive). Both dates are required as YYYY-MM-DD, otherwise 400. B1Admin's giving statements pages request one calendar year this way instead of the church's full history
GET/summaryJWTDonations.ViewSummaryGet donation summary. Filter by ?startDate=&endDate=&type=. Use type=person for per-person breakdown
GET/testEmailPublic—Send a test email (development/debugging)
POST/JWTDonations.Edit or Donations.EnterCreate or update donations (batch). With Donations.Enter only, both the target batch and (for an update) the donation's current batch must be open, and gateway gifts (those with a transactionId) can't be changed; otherwise 403 { "error": "This batch is closed." }
DELETE/:idJWTDonations.Edit or Donations.EnterDelete a donation. Donations.Enter only: the donation must be in an open batch and not a gateway gift, otherwise 403

Example: List Donations by Batch​

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

Example: Get Donation Summary​

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

Donation Batches​

Base path: /giving/donationbatches

Extends GenericCrudController with CRUD routes: getById, getAll, post, delete. The delete operation also removes all donations within the batch.

MethodPathAuthPermissionDescription
GET/JWTDonations.ViewSummary or Donations.EnterList all donation batches
GET/:idJWTDonations.ViewSummary or Donations.EnterGet a donation batch by ID
POST/JWTDonations.Edit or Donations.EnterCreate or update donation batches. Donations.Enter only: updating an existing batch requires it to be open, otherwise 403 { "error": "This batch is closed." }. status is ignored here, so saving a batch can't reopen it
POST/:id/closeJWTDonations.EditClose a batch: sets status to closed, closedDate to now, and closedBy to the caller's user id. Returns the batch
POST/:id/reopenJWTDonations.EditReopen a batch: sets status to open and clears closedDate and closedBy. Returns the batch
DELETE/:idJWTDonations.EditDelete a batch and all its donations

Each batch includes status (open or closed; new and pre-existing batches are open), closedDate, and closedBy. Donations.Edit can change donations in any batch; Donations.Enter (shown as Enter Donations in the role editor) can only add, change, or delete donations and fund splits while their batch is open.

Base path: /giving/donate

Handles the public-facing donation flow including charges, subscriptions, webhooks, and fee calculations. No base CRUD routes are enabled; all endpoints are custom.

MethodPathAuthPermissionDescription
GET/gateways/:churchIdPublic—Get available payment gateways for a church (public keys only)
POST/client-tokenJWT—Generate a client token for gateway initialization
POST/create-orderJWT—Create a payment order (PayPal-style checkout)
POST/chargeJWT—Process a one-time donation charge
POST/subscribeJWT—Create a recurring donation subscription
POST/logPublic—Log a donation. Body: { donation, fundData }
POST/webhook/:providerPublic—Receive payment webhook events (Stripe, PayPal). Requires ?churchId=
POST/replay-stripe-eventsJWTDonations.EditReplay Stripe events for a date range. Body: { startDate, endDate, dryRun }
POST/feePublic—Calculate transaction fees. Body: { type, provider, gatewayId, amount, currency }. Requires ?churchId=
POST/captcha-verifyPublic—Verify reCAPTCHA token. Body: { token, churchId? }. A human answer returns { response: "human", pass }, where pass is a signed guest-giving pass good for 10 minutes (and only for churchId when one is sent)

When the Api runs with CAPTCHA_ENFORCE=true, guest (not signed-in) calls to /giving/donate/create-order, /charge, /subscribe, /giving/paymentmethods/addcard, and /giving/paymentmethods/ach-setup-intent-anon (and guest priced POST /content/registrations/register calls) must include that captchaPass in the body, or they return 403 Captcha verification required. The pass can be reused until it expires, because the Stripe guest flow makes two calls (add card, then charge). Signed-in calls are not affected. CAPTCHA_ENFORCE defaults to false; @churchapps/apphelper's guest giving forms send the pass automatically.

Example: Process a Donation Charge​

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

Example: Create a Recurring Subscription​

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

Funds​

Base path: /giving/funds

Extends GenericCrudController with CRUD routes: getById, getAll, post, delete. The view permission is null (no permission required for viewing funds).

MethodPathAuthPermissionDescription
GET/JWT—List all funds
GET/:idJWT—Get a fund by ID
GET/churchId/:churchIdPublic—Get all funds for a specific church (public)
GET/public/:churchId/:fundId/total?startDate=&endDate=Public—Get a fund's donation total: { fundId, totalAmount, donationCount }. Powers the website builder's campaignProgress element
POST/JWTDonations.EditCreate or update funds
DELETE/:idJWTDonations.EditDelete a fund

Fund Donations​

Base path: /giving/funddonations

Tracks how individual donations are allocated across funds. No base CRUD routes are enabled; all endpoints are custom.

MethodPathAuthPermissionDescription
GET/JWTDonations.ViewList fund donations. Filter by ?donationId=, ?personId=, ?fundId=, or ?fundName=. Optionally add ?startDate=&endDate= for date filtering
GET/:idJWTDonations.ViewGet a fund donation by ID
GET/myJWT—Get current user's fund donations
POST/JWTDonations.Edit or Donations.EnterCreate or update fund donations (batch). Donations.Enter only: the parent donation must be in an open batch and not a gateway gift, otherwise 403
DELETE/:idJWTDonations.Edit or Donations.EnterDelete a fund donation. Same open-batch rule for Donations.Enter

Gateways​

Base path: /giving/gateways

Manages payment gateway configurations (Stripe, PayPal, etc.). No base CRUD routes are enabled; all endpoints are custom. Gateway secrets are encrypted at rest.

MethodPathAuthPermissionDescription
GET/JWT—List all gateways for the church
GET/:idJWTSettings.EditGet a gateway by ID
GET/churchId/:churchIdPublic—Get gateways for a church (public keys only)
GET/configured/:churchIdPublic—Check if a church has a configured payment gateway
POST/JWTSettings.EditCreate or update gateways (encrypts keys, provisions webhooks and products)
PATCH/:idJWTSettings.EditPartially update a gateway
DELETE/:idJWTSettings.EditDelete a gateway (also removes its webhooks)

Example: Check Gateway Configuration​

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

Customers​

Base path: /giving/customers

Extends GenericCrudController with CRUD routes: getAll, delete. Links people to their payment gateway customer records.

MethodPathAuthPermissionDescription
GET/JWTDonations.ViewSummaryList all customers
GET/:idJWTDonations.ViewSummary or own recordGet a customer by ID
GET/:id/subscriptionsJWTDonations.ViewSummary or own recordGet gateway subscriptions for a customer
DELETE/:idJWTDonations.EditDelete a customer

Subscriptions​

Base path: /giving/subscriptions

Manages recurring donation subscriptions. No base CRUD routes are enabled; all endpoints are custom.

MethodPathAuthPermissionDescription
GET/JWTDonations.ViewSummaryList all subscriptions
GET/:idJWTDonations.ViewSummaryGet a subscription by ID
POST/JWTDonations.Edit or own subscriptionUpdate subscriptions with the payment gateway
DELETE/:idJWTDonations.Edit or own subscriptionCancel a subscription and remove from database. Body: { provider, reason }

Subscription Funds​

Base path: /giving/subscriptionfunds

Tracks fund allocations for recurring subscriptions. No base CRUD routes are enabled; all endpoints are custom.

MethodPathAuthPermissionDescription
GET/JWTDonations.View or own subscriptionList subscription funds. Filter by ?subscriptionId=
GET/:idJWTDonations.ViewSummaryGet a subscription fund by ID
DELETE/:idJWTDonations.EditDelete a subscription fund
DELETE/subscription/:idJWTDonations.Edit or own subscriptionDelete all funds for a subscription

Payment Methods​

Base path: /giving/paymentmethods

Manages stored payment methods (cards, bank accounts) via payment gateway APIs. No base CRUD routes are enabled; all endpoints are custom.

MethodPathAuthPermissionDescription
GET/personid/:idJWTDonations.View or own personIdGet all stored payment methods for a person (cards, bank accounts)
POST/addcardJWT—Attach a card payment method. Body: { id, personId, customerId, email, name, churchId, provider }
POST/updatecardJWTDonations.Edit or own personIdUpdate card details. Body: { personId, paymentMethodId, cardData, provider }
POST/ach-setup-intentJWTDonations.Edit or own personIdCreate a Stripe ACH SetupIntent for bank account linking. Body: { personId, customerId, email, name, churchId }
POST/ach-setup-intent-anonPublic—Create an anonymous ACH SetupIntent for guest donations. Body: { email, name, churchId, gatewayId }
POST/addbankaccountJWTDonations.Edit or own personIdAdd a bank account via token (deprecated; use ach-setup-intent). Body: { id, personId, customerId, email, name }
POST/updatebankJWTDonations.Edit or own personIdUpdate bank account details. Body: { paymentMethodId, personId, bankData, customerId }
POST/verifybankJWTDonations.Edit or own customerVerify a bank account with micro-deposits. Body: { paymentMethodId, customerId, amountData }
DELETE/:id/:customeridJWTDonations.Edit or own customerDelete a payment method (card or bank account)

Event Log​

Base path: /giving/eventLog

Extends GenericCrudController with CRUD routes: getById, getAll, post, delete. Tracks payment gateway webhook events for auditing and deduplication.

MethodPathAuthPermissionDescription
GET/JWTDonations.ViewSummaryList all event logs
GET/:idJWTDonations.ViewSummaryGet an event log by ID
GET/type/:typeJWTDonations.ViewSummaryGet event logs filtered by event type
POST/JWTDonations.EditCreate or update event logs
DELETE/:idJWTDonations.EditDelete an event log