Siirry pääsisällölle

Lahjoitusrajapinnat

Lahjoitus-moduuli hallinnoi lahjoituksia, rahastoja, maksujen käsittelyä, tilauksia ja muita talousasioita. Se tukee useita maksuyhdyskäytäviä (Stripe, PayPal), käsittelee kertaluonteisia ja toistuvia lahjoituksia, seuraa lahjoituserien tietoja ja käsittelee webhook-tapahtumia asynkronisille maksutapahtumille.

Perus-polku: /giving

Lahjoitukset​

Perus-polku: /giving/donations

MenetelmäPolkuTodennusOikeusKuvaus
GET/JWTDonations.View tai oma personIdListaa kaikki lahjoitukset. Suodata ?batchId=- tai ?personId=-parametrilla. ?personId=-parametrilla lahjoituksia rahastoihin, jotka eivät ole vähennyskelpoisia, ei sisällytetä (kuten lahjoitustodistuksissa), ellei Donations.View-oikeuden käyttäjä lisää &includeNonDeductible=1-parametria, minkä B1Admin-henkilötietosivu tekee
GET/:idJWTDonations.ViewHae lahjoitus tunnuksella
GET/myJWT—Hae nykyisen käyttäjän lahjoitukset
GET/my/summary?year=JWT—Nykyisen käyttäjän lahjoitussumma vuodelta (oletuksena tämä vuosi): { year, total, count, currency, isConverted }. Summat muunnetaan seurakunnan valuuttaan. Tämä tukee lahjoitusten esikatselua jäsenen etusivulla
GET/?startDate=&endDate=JWTDonations.ViewHae aikavälille (mukaan lukien) päivätyt lahjoitukset. Molemmat päivämäärät vaaditaan muodossa YYYY-MM-DD, muuten vastauksena on 400. B1Admin-lahjoitustodistussivut pyytävät yhden kalenterivuoden tiedot tällä tavalla koko seurakunnan historian sijaan
GET/summaryJWTDonations.ViewSummaryHae lahjoitusyhteenveto. Suodata ?startDate=&endDate=&type=. Käytä type=person saadaksesi erittelyn henkilöittäin
GET/testEmailJulkinen—Lähetä testisähköposti (kehitystä ja vianetsintää varten)
POST/JWTDonations.Edit tai Donations.EnterLuo tai päivitä lahjoituksia (erä). Pelkällä Donations.Enter-oikeudella sekä kohde-erän että (päivityksessä) lahjoituksen nykyisen erän on oltava auki, eikä yhdyskäytävän kautta tehtyjä lahjoituksia (joilla on transactionId) voi muuttaa. Muussa tapauksessa vastauksena on 403 { "error": "This batch is closed." }
DELETE/:idJWTDonations.Edit tai Donations.EnterPoista lahjoitus. Pelkällä Donations.Enter-oikeudella lahjoituksen on oltava avoimessa erässä, eikä se saa olla yhdyskäytävän kautta tehty lahjoitus. Muuten vastauksena on 403

Esimerkki: Listaa lahjoitukset erän mukaan​

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

Esimerkki: Hae lahjoitusyhteenveto​

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

Lahjoituserät​

Perus-polku: /giving/donationbatches

Laajentaa GenericCrudController-luokkaa CRUD-reitityksillä: getById, getAll, post, delete. Poisto poistaa myös erään kuuluvat lahjoitukset.

MenetelmäPolkuTodennusOikeusKuvaus
GET/JWTDonations.ViewSummary tai Donations.EnterListaa kaikki lahjoituserät
GET/:idJWTDonations.ViewSummary tai Donations.EnterHae lahjoituserä tunnuksella
POST/JWTDonations.Edit tai Donations.EnterLuo tai päivitä lahjoituseriä. Pelkällä Donations.Enter-oikeudella olemassa olevan erän päivitys edellyttää, että erä on auki. Muuten vastauksena on 403 { "error": "This batch is closed." }. status-kenttä jätetään tässä huomiotta, joten erän tallentaminen ei voi avata sitä uudelleen
POST/:id/closeJWTDonations.EditSulje erä: asettaa status-kentän arvoksi closed, closedDate-kentän nykyhetkeen ja closedBy-kentän kutsujan käyttäjätunnukseksi. Palauttaa erän
POST/:id/reopenJWTDonations.EditAvaa erä uudelleen: asettaa status-kentän arvoksi open ja tyhjentää closedDate- ja closedBy-kentät. Palauttaa erän
DELETE/:idJWTDonations.EditPoista erä ja kaikki sen lahjoitukset

Jokaisessa erässä on status (open tai closed; uudet ja olemassa olevat erät ovat open), closedDate ja closedBy. Donations.Edit-oikeudella voi muuttaa lahjoituksia missä tahansa erässä. Donations.Enter-oikeudella (näkyy roolieditorissa nimellä Enter Donations) voi lisätä, muuttaa tai poistaa lahjoituksia ja rahastojakoja vain, kun niiden erä on auki.

Lahjoita​

Perus-polku: /giving/donate

Käsittelee julkisen lahjoitusvirran, mukaan lukien veloitukset, tilaukset, webhookit ja kulujen laskennan. Perus-CRUD-reittejä ei ole käytössä, ja kaikki päätepisteet ovat mukautettuja.

MenetelmäPolkuTodennusOikeusKuvaus
GET/gateways/:churchIdJulkinen—Hae seurakunnan käytettävissä olevat maksuyhdyskäytävät (vain julkiset avaimet)
POST/client-tokenJWT—Luo asiakastunnus yhdyskäytävän alustamista varten
POST/create-orderJWT—Luo maksutilaus (PayPal-tyylinen kassa)
POST/chargeJWT—Käsittele kertaluonteinen lahjoitusveloitus
POST/subscribeJWT—Luo toistuva lahjoitustilaus
POST/logJulkinen—Kirjaa lahjoitus. Runko: { donation, fundData }
POST/webhook/:providerJulkinen—Vastaanota maksun webhook-tapahtumia (Stripe, PayPal). Vaatii ?churchId=-parametrin
POST/replay-stripe-eventsJWTDonations.EditToista Stripe-tapahtumat aikavälille. Runko: { startDate, endDate, dryRun }
POST/feeJulkinen—Laske tapahtumamaksut. Runko: { type, provider, gatewayId, amount, currency }. Vaatii ?churchId=-parametrin
POST/captcha-verifyJulkinen—Vahvista reCAPTCHA-tunniste. Runko: { token, churchId? }. Ihmisvastaus palauttaa { response: "human", pass }, missä pass on allekirjoitettu vieraslahjoituspassi, joka on voimassa 10 minuuttia (ja vain churchId-kentän seurakunnalle, jos se on lähetetty)

Kun Api käynnistetään CAPTCHA_ENFORCE=true-asetuksella, vieraskutsujen (eli kirjautumattomien käyttäjien) pyyntöihin /giving/donate/create-order, /charge, /subscribe, /giving/paymentmethods/addcard ja /giving/paymentmethods/ach-setup-intent-anon sekä maksullisiin vierasrekisteröintipyyntöihin POST /content/registrations/register on sisällytettävä captchaPass pyyntörunkoon. Muuten vastauksena on 403 Captcha verification required. Passia voi käyttää uudelleen, kunnes se vanhenee, koska Stripen vierasvirrassa tehdään kaksi kutsua (kortin lisäys ja veloitus). Kirjautuneiden käyttäjien kutsuihin tämä ei vaikuta. CAPTCHA_ENFORCE on oletuksena false. @churchapps/apphelper-kirjaston vieraslahjoituslomakkeet lähettävät passin automaattisesti.

Esimerkki: Käsittele lahjoitusveloitus​

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

Esimerkki: Luo toistuva tilaus​

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

Rahastot​

Perus-polku: /giving/funds

Laajentaa GenericCrudController-luokkaa CRUD-reitityksillä: getById, getAll, post, delete. view-oikeus on null, eli rahastojen katseluun ei vaadita oikeutta.

MenetelmäPolkuTodennusOikeusKuvaus
GET/JWT—Listaa kaikki rahastot
GET/:idJWT—Hae rahasto tunnuksella
GET/churchId/:churchIdJulkinen—Hae kaikki tietyn seurakunnan rahastot (julkinen)
GET/public/:churchId/:fundId/total?startDate=&endDate=Julkinen—Hae rahaston lahjoitussumma: { fundId, totalAmount, donationCount }. Tukee verkkosivurakentajan campaignProgress-elementtiä
POST/JWTDonations.EditLuo tai päivitä rahastoja
DELETE/:idJWTDonations.EditPoista rahasto

Rahastolahjoitukset​

Perus-polku: /giving/funddonations

Seuraa, miten yksittäiset lahjoitukset kohdistetaan rahastoihin. Perus-CRUD-reittejä ei ole käytössä, ja kaikki päätepisteet ovat mukautettuja.

MenetelmäPolkuTodennusOikeusKuvaus
GET/JWTDonations.ViewListaa rahastolahjoitukset. Suodata ?donationId=, ?personId=, ?fundId= tai ?fundName= -parametrilla. Voit lisätä myös ?startDate=&endDate= päivämääräsuodatukseen
GET/:idJWTDonations.ViewHae rahastolahjoitus tunnuksella
GET/myJWT—Hae nykyisen käyttäjän rahastolahjoitukset
POST/JWTDonations.Edit tai Donations.EnterLuo tai päivitä rahastolahjoituksia (erä). Pelkällä Donations.Enter-oikeudella emolahjoituksen on oltava avoimessa erässä eikä yhdyskäytävän kautta tehty lahjoitus. Muuten vastauksena on 403
DELETE/:idJWTDonations.Edit tai Donations.EnterPoista rahastolahjoitus. Sama avoimen erän sääntö koskee Donations.Enter-oikeutta

Yhdyskäytävät​

Perus-polku: /giving/gateways

Hallinnoi maksuyhdyskäytävien asetuksia (Stripe, PayPal jne.). Perus-CRUD-reittejä ei ole käytössä, ja kaikki päätepisteet ovat mukautettuja. Yhdyskäytävien salaisuudet salataan levossa.

MenetelmäPolkuTodennusOikeusKuvaus
GET/JWT—Listaa seurakunnan kaikki yhdyskäytävät
GET/:idJWTSettings.EditHae yhdyskäytävä tunnuksella
GET/churchId/:churchIdJulkinen—Hae seurakunnan yhdyskäytävät (vain julkiset avaimet)
GET/configured/:churchIdJulkinen—Tarkista, onko seurakunnalla määritetty maksuyhdyskäytävä
POST/JWTSettings.EditLuo tai päivitä yhdyskäytäviä (salaa avaimet, luo webhookit ja tuotteet)
PATCH/:idJWTSettings.EditPäivitä yhdyskäytävä osittain
DELETE/:idJWTSettings.EditPoista yhdyskäytävä (poistaa myös sen webhookit)

Esimerkki: Tarkista yhdyskäytävän asetukset​

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

Asiakkaat​

Perus-polku: /giving/customers

Laajentaa GenericCrudController-luokkaa CRUD-reitityksillä: getAll, delete. Linkittää henkilöt heidän maksuyhdyskäytävän asiakastietueisiinsa.

MenetelmäPolkuTodennusOikeusKuvaus
GET/JWTDonations.ViewSummaryListaa kaikki asiakkaat
GET/:idJWTDonations.ViewSummary tai oma tietueHae asiakas tunnuksella
GET/:id/subscriptionsJWTDonations.ViewSummary tai oma tietueHae asiakkaan yhdyskäytävätilaukset
DELETE/:idJWTDonations.EditPoista asiakas

Tilaukset​

Perus-polku: /giving/subscriptions

Hallinnoi toistuvia lahjoitustilauksia. Perus-CRUD-reittejä ei ole käytössä, ja kaikki päätepisteet ovat mukautettuja.

MenetelmäPolkuTodennusOikeusKuvaus
GET/JWTDonations.ViewSummaryListaa kaikki tilaukset
GET/:idJWTDonations.ViewSummaryHae tilaus tunnuksella
POST/JWTDonations.Edit tai oma tilausPäivitä tilauksia maksuyhdyskäytävässä
DELETE/:idJWTDonations.Edit tai oma tilausPeruuta tilaus ja poista se tietokannasta. Runko: { provider, reason }

Tilausrahastot​

Perus-polku: /giving/subscriptionfunds

Seuraa toistuvien tilausten rahastokohdistuksia. Perus-CRUD-reittejä ei ole käytössä, ja kaikki päätepisteet ovat mukautettuja.

MenetelmäPolkuTodennusOikeusKuvaus
GET/JWTDonations.View tai oma tilausListaa tilausrahastot. Suodata ?subscriptionId=-parametrilla
GET/:idJWTDonations.ViewSummaryHae tilausrahasto tunnuksella
DELETE/:idJWTDonations.EditPoista tilausrahasto
DELETE/subscription/:idJWTDonations.Edit tai oma tilausPoista kaikki tilauksen rahastot

Maksutavat​

Perus-polku: /giving/paymentmethods

Hallinnoi tallennettuja maksutapoja (kortit, pankkitilit) maksuyhdyskäytävien rajapintojen kautta. Perus-CRUD-reittejä ei ole käytössä, ja kaikki päätepisteet ovat mukautettuja.

MenetelmäPolkuTodennusOikeusKuvaus
GET/personid/:idJWTDonations.View tai oma personIdHae kaikki henkilön tallennetut maksutavat (kortit, pankkitilit)
POST/addcardJWT—Liitä korttimaksutapa. Runko: { id, personId, customerId, email, name, churchId, provider }
POST/updatecardJWTDonations.Edit tai oma personIdPäivitä kortin tiedot. Runko: { personId, paymentMethodId, cardData, provider }
POST/ach-setup-intentJWTDonations.Edit tai oma personIdLuo Stripe ACH SetupIntent pankkitilin liittämistä varten. Runko: { personId, customerId, email, name, churchId }
POST/ach-setup-intent-anonJulkinen—Luo anonyymi ACH SetupIntent vieraslahjoituksia varten. Runko: { email, name, churchId, gatewayId }
POST/addbankaccountJWTDonations.Edit tai oma personIdLisää pankkitili tunnuksen kautta (vanhentunut; käytä ach-setup-intent-reittiä). Runko: { id, personId, customerId, email, name }
POST/updatebankJWTDonations.Edit tai oma personIdPäivitä pankkitilin tiedot. Runko: { paymentMethodId, personId, bankData, customerId }
POST/verifybankJWTDonations.Edit tai oma asiakastietueVahvista pankkitili pienillä tilisiirroilla. Runko: { paymentMethodId, customerId, amountData }
DELETE/:id/:customeridJWTDonations.Edit tai oma asiakastietuePoista maksutapa (kortti tai pankkitili)

Tapahtumaloki​

Perus-polku: /giving/eventLog

Laajentaa GenericCrudController-luokkaa CRUD-reitityksillä: getById, getAll, post, delete. Seuraa maksuyhdyskäytävän webhook-tapahtumia tarkastusta ja kaksoiskappaleiden poistoa varten.

MenetelmäPolkuTodennusOikeusKuvaus
GET/JWTDonations.ViewSummaryListaa kaikki tapahtumalokit
GET/:idJWTDonations.ViewSummaryHae tapahtumaloki tunnuksella
GET/type/:typeJWTDonations.ViewSummaryHae tapahtumalokit tapahtumatyypin mukaan suodatettuina
POST/JWTDonations.EditLuo tai päivitä tapahtumalokeja
DELETE/:idJWTDonations.EditPoista tapahtumaloki

Aiheeseen liittyvät sivut​