Lumipat sa pangunahing nilalaman

Mga Giving Endpoint

Pinamamahalaan ng Giving module ang mga donasyon, fund, pagproseso ng bayad, subscription, at mga kaugnay na operasyong pinansyal. Sinusuportahan nito ang maraming payment gateway (Stripe, PayPal), humahawak sa isang beses at paulit-ulit na donasyon, sumusubaybay sa mga batch ng donasyon, at nagbibigay ng pagproseso ng webhook para sa mga asynchronous na pangyayari sa bayad.

Base path: /giving

Mga Donasyon​

Base path: /giving/donations

MethodPathAuthPermisoPaglalarawan
GET/JWTDonations.View o sariling personIdIlista ang lahat ng donasyon. I-filter gamit ang ?batchId= o ?personId=. Gamit ang ?personId=, hindi isinasama ang mga regalo sa mga fund na hindi ma-deduct (gaya ng nasa giving statement) maliban kung magdagdag ang caller na may Donations.View ng &includeNonDeductible=1, na ginagawa ng person record ng B1Admin
GET/:idJWTDonations.ViewKunin ang donasyon ayon sa ID
GET/myJWT—Kunin ang mga donasyon ng kasalukuyang user
GET/my/summary?year=JWT—Kabuuang giving ng kasalukuyang user para sa isang taon (default ang taong ito): { year, total, count, currency, isConverted }, na may mga kabuuang na-convert sa currency ng simbahan. Sumusuporta sa giving preview sa home page ng miyembro
GET/?startDate=&endDate=JWTDonations.ViewMga donasyong may petsa sa loob ng saklaw (kasama ang dalawang dulo). Kailangan ang parehong petsa bilang YYYY-MM-DD, kung hindi ay 400. Ganito humihiling ang mga pahina ng giving statement ng B1Admin ng isang kalendaryong taon sa halip na buong kasaysayan ng simbahan
GET/summaryJWTDonations.ViewSummaryKunin ang buod ng donasyon. I-filter gamit ang ?startDate=&endDate=&type=. Gamitin ang type=person para sa breakdown bawat tao
GET/testEmailPublic—Magpadala ng test email (development/debugging)
POST/JWTDonations.Edit o Donations.EnterGumawa o mag-update ng mga donasyon (batch). Kapag Donations.Enter lang, dapat bukas ang target na batch at (para sa update) ang kasalukuyang batch ng donasyon, at hindi maaaring baguhin ang mga gateway gift (yaong may transactionId); kung hindi, 403 { "error": "This batch is closed." }
DELETE/:idJWTDonations.Edit o Donations.EnterBurahin ang donasyon. Donations.Enter lang: dapat nasa bukas na batch ang donasyon at hindi gateway gift, kung hindi ay 403

Halimbawa: Ilista ang Mga Donasyon Ayon sa 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"
}
]

Halimbawa: Kunin ang Buod ng Donasyon​

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

Mga Donation Batch​

Base path: /giving/donationbatches

Nagmamana mula sa GenericCrudController na may mga CRUD route: getById, getAll, post, delete. Inaalis din ng operasyong delete ang lahat ng donasyon sa loob ng batch.

MethodPathAuthPermisoPaglalarawan
GET/JWTDonations.ViewSummary o Donations.EnterIlista ang lahat ng donation batch
GET/:idJWTDonations.ViewSummary o Donations.EnterKunin ang donation batch ayon sa ID
POST/JWTDonations.Edit o Donations.EnterGumawa o mag-update ng mga donation batch. Kapag Donations.Enter lang: ang pag-update ng umiiral na batch ay nangangailangang bukas ito, kung hindi ay 403 { "error": "This batch is closed." }. Hindi pinapansin dito ang status, kaya hindi maibabalik sa bukas ang batch sa pag-save
POST/:id/closeJWTDonations.EditIsara ang batch: itinatakda ang status sa closed, ang closedDate sa ngayon, at ang closedBy sa user id ng caller. Ibinabalik ang batch
POST/:id/reopenJWTDonations.EditBuksan muli ang batch: itinatakda ang status sa open at binubura ang closedDate at closedBy. Ibinabalik ang batch
DELETE/:idJWTDonations.EditBurahin ang batch at lahat ng donasyon nito

Kasama sa bawat batch ang status (open o closed; ang mga bago at umiiral na batch ay open), closedDate, at closedBy. Maaaring baguhin ng Donations.Edit ang mga donasyon sa anumang batch; ang Donations.Enter (ipinapakita bilang Enter Donations sa role editor) ay maaari lang magdagdag, magbago, o magbura ng mga donasyon at hati ng fund habang bukas ang batch nila.

Base path: /giving/donate

Humahawak sa pampublikong daloy ng donasyon kabilang ang mga singil, subscription, webhook, at kalkulasyon ng bayarin. Walang naka-enable na base CRUD route; lahat ng endpoint ay custom.

MethodPathAuthPermisoPaglalarawan
GET/gateways/:churchIdPublic—Kunin ang mga available na payment gateway para sa isang simbahan (public key lang)
POST/client-tokenJWT—Gumawa ng client token para sa initialization ng gateway
POST/create-orderJWT—Gumawa ng payment order (checkout na istilong PayPal)
POST/chargeJWT—Iproseso ang singil ng isang beses na donasyon
POST/subscribeJWT—Gumawa ng paulit-ulit na donasyong subscription
POST/logPublic—Mag-log ng donasyon. Body: { donation, fundData }
POST/webhook/:providerPublic—Tumanggap ng mga event ng webhook ng bayad (Stripe, PayPal). Kailangan ang ?churchId=
POST/replay-stripe-eventsJWTDonations.EditI-replay ang mga event ng Stripe para sa saklaw ng petsa. Body: { startDate, endDate, dryRun }
POST/feePublic—Kalkulahin ang mga bayarin sa transaksyon. Body: { type, provider, gatewayId, amount, currency }. Kailangan ang ?churchId=
POST/captcha-verifyPublic—I-verify ang reCAPTCHA token. Body: { token, churchId? }. Ang sagot na tao ay nagbabalik ng { response: "human", pass }, kung saan ang pass ay naka-sign na guest-giving pass na valid nang 10 minuto (at para lang sa churchId kapag may ipinadala)

Kapag tumatakbo ang Api na may CAPTCHA_ENFORCE=true, dapat isama sa body ang captchaPass na iyon ng mga guest (hindi naka-sign in) na tawag sa /giving/donate/create-order, /charge, /subscribe, /giving/paymentmethods/addcard, at /giving/paymentmethods/ach-setup-intent-anon (at ang guest na may presyong POST /content/registrations/register na tawag), kung hindi ay magbabalik sila ng 403 Captcha verification required. Maaaring gamitin muli ang pass hanggang mag-expire ito, dahil dalawang tawag ang ginagawa ng Stripe guest flow (idagdag ang card, pagkatapos ang singil). Hindi apektado ang mga naka-sign in na tawag. Ang default ng CAPTCHA_ENFORCE ay false; awtomatikong ipinapadala ng mga guest giving form ng @churchapps/apphelper ang pass.

Halimbawa: Iproseso ang Singil ng Donasyon​

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

Halimbawa: Gumawa ng Paulit-ulit na 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"
}

Mga Fund​

Base path: /giving/funds

Nagmamana mula sa GenericCrudController na may mga CRUD route: getById, getAll, post, delete. Ang permiso na view ay null (walang kailangang permiso para tingnan ang mga fund).

MethodPathAuthPermisoPaglalarawan
GET/JWT—Ilista ang lahat ng fund
GET/:idJWT—Kunin ang fund ayon sa ID
GET/churchId/:churchIdPublic—Kunin ang lahat ng fund ng isang partikular na simbahan (public)
GET/public/:churchId/:fundId/total?startDate=&endDate=Public—Kunin ang kabuuang donasyon ng fund: { fundId, totalAmount, donationCount }. Nagpapagana sa campaignProgress element ng website builder
POST/JWTDonations.EditGumawa o mag-update ng mga fund
DELETE/:idJWTDonations.EditBurahin ang fund

Fund Donations​

Base path: /giving/funddonations

Sinusubaybayan kung paano inilalaan ang bawat donasyon sa mga fund. Walang naka-enable na base CRUD route; lahat ng endpoint ay custom.

MethodPathAuthPermisoPaglalarawan
GET/JWTDonations.ViewIlista ang mga fund donation. I-filter gamit ang ?donationId=, ?personId=, ?fundId=, o ?fundName=. Opsyonal na idagdag ang ?startDate=&endDate= para sa pag-filter ayon sa petsa
GET/:idJWTDonations.ViewKunin ang fund donation ayon sa ID
GET/myJWT—Kunin ang mga fund donation ng kasalukuyang user
POST/JWTDonations.Edit o Donations.EnterGumawa o mag-update ng mga fund donation (batch). Kapag Donations.Enter lang: dapat bukas ang batch ng parent donation at hindi ito gateway gift, kung hindi ay 403
DELETE/:idJWTDonations.Edit o Donations.EnterBurahin ang fund donation. Parehong panuntunan ng bukas na batch para sa Donations.Enter

Mga Gateway​

Base path: /giving/gateways

Pinamamahalaan ang mga configuration ng payment gateway (Stripe, PayPal, atbp.). Walang naka-enable na base CRUD route; lahat ng endpoint ay custom. Naka-encrypt habang naka-imbak ang mga secret ng gateway.

MethodPathAuthPermisoPaglalarawan
GET/JWT—Ilista ang lahat ng gateway ng simbahan
GET/:idJWTSettings.EditKunin ang gateway ayon sa ID
GET/churchId/:churchIdPublic—Kunin ang mga gateway ng isang simbahan (public key lang)
GET/configured/:churchIdPublic—Tingnan kung may naka-configure na payment gateway ang isang simbahan
POST/JWTSettings.EditGumawa o mag-update ng mga gateway (nag-e-encrypt ng mga key, nag-p-provision ng mga webhook at product)
PATCH/:idJWTSettings.EditI-update nang bahagya ang isang gateway
DELETE/:idJWTSettings.EditBurahin ang gateway (inaalis din ang mga webhook nito)

Halimbawa: Suriin ang Configuration ng Gateway​

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

Mga Customer​

Base path: /giving/customers

Nagmamana mula sa GenericCrudController na may mga CRUD route: getAll, delete. Nag-uugnay ng mga tao sa kanilang customer record sa payment gateway.

MethodPathAuthPermisoPaglalarawan
GET/JWTDonations.ViewSummaryIlista ang lahat ng customer
GET/:idJWTDonations.ViewSummary o sariling recordKunin ang customer ayon sa ID
GET/:id/subscriptionsJWTDonations.ViewSummary o sariling recordKunin ang mga gateway subscription ng isang customer
DELETE/:idJWTDonations.EditBurahin ang customer

Mga Subscription​

Base path: /giving/subscriptions

Pinamamahalaan ang mga paulit-ulit na donasyong subscription. Walang naka-enable na base CRUD route; lahat ng endpoint ay custom.

MethodPathAuthPermisoPaglalarawan
GET/JWTDonations.ViewSummaryIlista ang lahat ng subscription
GET/:idJWTDonations.ViewSummaryKunin ang subscription ayon sa ID
POST/JWTDonations.Edit o sariling subscriptionI-update ang mga subscription sa payment gateway
DELETE/:idJWTDonations.Edit o sariling subscriptionKanselahin ang subscription at alisin sa database. Body: { provider, reason }

Mga Subscription Fund​

Base path: /giving/subscriptionfunds

Sinusubaybayan ang mga paglalaan ng fund para sa mga paulit-ulit na subscription. Walang naka-enable na base CRUD route; lahat ng endpoint ay custom.

MethodPathAuthPermisoPaglalarawan
GET/JWTDonations.View o sariling subscriptionIlista ang mga subscription fund. I-filter gamit ang ?subscriptionId=
GET/:idJWTDonations.ViewSummaryKunin ang subscription fund ayon sa ID
DELETE/:idJWTDonations.EditBurahin ang subscription fund
DELETE/subscription/:idJWTDonations.Edit o sariling subscriptionBurahin ang lahat ng fund ng isang subscription

Mga Paraan ng Pagbabayad​

Base path: /giving/paymentmethods

Pinamamahalaan ang mga naka-imbak na paraan ng pagbabayad (card, bank account) sa pamamagitan ng API ng payment gateway. Walang naka-enable na base CRUD route; lahat ng endpoint ay custom.

MethodPathAuthPermisoPaglalarawan
GET/personid/:idJWTDonations.View o sariling personIdKunin ang lahat ng naka-imbak na paraan ng pagbabayad ng isang tao (card, bank account)
POST/addcardJWT—Magdagdag ng card na paraan ng pagbabayad. Body: { id, personId, customerId, email, name, churchId, provider }
POST/updatecardJWTDonations.Edit o sariling personIdI-update ang detalye ng card. Body: { personId, paymentMethodId, cardData, provider }
POST/ach-setup-intentJWTDonations.Edit o sariling personIdGumawa ng Stripe ACH SetupIntent para sa pag-link ng bank account. Body: { personId, customerId, email, name, churchId }
POST/ach-setup-intent-anonPublic—Gumawa ng anonymous na ACH SetupIntent para sa mga donasyon ng guest. Body: { email, name, churchId, gatewayId }
POST/addbankaccountJWTDonations.Edit o sariling personIdMagdagdag ng bank account sa pamamagitan ng token (deprecated; gamitin ang ach-setup-intent). Body: { id, personId, customerId, email, name }
POST/updatebankJWTDonations.Edit o sariling personIdI-update ang detalye ng bank account. Body: { paymentMethodId, personId, bankData, customerId }
POST/verifybankJWTDonations.Edit o sariling customerI-verify ang bank account gamit ang micro-deposit. Body: { paymentMethodId, customerId, amountData }
DELETE/:id/:customeridJWTDonations.Edit o sariling customerBurahin ang paraan ng pagbabayad (card o bank account)

Event Log​

Base path: /giving/eventLog

Nagmamana mula sa GenericCrudController na may mga CRUD route: getById, getAll, post, delete. Sinusubaybayan ang mga event ng webhook ng payment gateway para sa auditing at deduplication.

MethodPathAuthPermisoPaglalarawan
GET/JWTDonations.ViewSummaryIlista ang lahat ng event log
GET/:idJWTDonations.ViewSummaryKunin ang event log ayon sa ID
GET/type/:typeJWTDonations.ViewSummaryKunin ang mga event log na sinala ayon sa uri ng event
POST/JWTDonations.EditGumawa o mag-update ng mga event log
DELETE/:idJWTDonations.EditBurahin ang event log

Mga Kaugnay na Pahina​