Giving for business customers: donations with the Charitips API
A SaaS offers giving to its business customers: each gets its own Charitips account, campaign and dashboard, created and billed by the SaaS or by them.
- Who paysYour business customers
- Starts withEach business customer's own campaigns
- Tax receiptIn each business customer's name
Needs API access and the account hierarchy feature on a validated account. Plans
One variant of Donations for your business customers · Software and apps
Each business customer runs its own campaigns
See every variantyour-platform.example/settings/giving
Step by step
Click through the site. Each step shows what your customer does, what your server sends and what Charitips answers.
1Giving set up
To comeYour customer does…
Clicks “Turn on giving”.
Your server sends…
Creates an account for your customer “Blue Fern Studio”.
Saves the charities you offer, as “Team charities”, on your customer's account.
Creates the campaign “Team kudos”, on your customer's account.
POSTcreate-campaign
Asks for a link to your customer's billing page.
Charitips answers…
Charitips creates the account and returns its id.
Charitips saves the selection and returns its id.
Charitips creates the campaign and returns its id.
Charitips returns the link to send.
Charitips will then tell your server the campaign was created.
2Campaign live
To comeYour customer does…
Clicks “Card saved”.
Your server sends…
Starts the campaign.
Charitips answers…
The campaign is live and takes donations.
Charitips will then tell your server the campaign changed.
3Colleague thanked
To comeYour customer does…
Clicks “Send kudos with 10 €”.
Your server sends…
Creates a 10 € donation for kudos #5120 on your campaign.
POSTcreate-donation
Charitips answers…
Charitips records the donation and returns its id: it waits for your customer to pick a charity.
Charitips will then tell your server the donation was created.
4Colleague chose a charity
To comeYour customer does…
Clicks “Give 10 €”.
Your server sends…
Assigns that donation to the charity your customer picks.
POSTclaim-donation
Charitips answers…
The donation now goes to the charity your customer picks.
Charitips will then tell your server the donation was updated.
5Dashboard opened
To comeYour customer does…
Clicks “Open the giving dashboard”.
Your server sends…
Looks up the dashboard user of your customer's account.
GETlist-users
Asks for a sign-in link for that user.
Charitips answers…
Charitips returns the user created with the account, and its id.
Charitips returns a one-time sign-in link.
How to read this demo: the site shows what your customer does, and the panel what your server sends and what Charitips answers, step by step.
The site is made up and nothing is sent. The endpoints, fields and webhook events are the real ones, and so are the charities.
How it works
The screens of the demo in order, with the calls your server makes at each one. Its build spec
campaign_createcampaign_updatedonation_createdonation_update01
Turn on giving for your team
Your platform creates the customer's own Charitips account, its selection and its campaign from the details it already has, then a link to the Charitips billing page of that account.
- Company: Blue Fern Studio
- Billing address: Lyon, France
The customer picks a charity from your selection. Button: Turn on giving
Your server calls:
- POST /v1/accounts/{accountId}/child-accountsCreate a child account: your accountId in the path; returns the customer's accountId, to store on your side
- POST /v1/charities-selectionsCreate a charities selection: the charities the admin ticked, on the customer's account
- POST /v1/campaignsCreate a campaign: on the customer's account; claimed donations are billed monthly
- POST /v1/accounts/{accountId}/billing-linkCreate a shareable billing link: the customer's accountId in the path; a link to their Charitips billing page
Charitips then sends the
campaign_createwebhook to your endpoint.02
Send the billing link to whoever pays
The admin forwards the Charitips billing link to whoever pays, who saves a card or a SEPA mandate. The paymentmethod_create webhook tells your server, which activates the campaign and updates the page; your platform reminds the payer after three days.
Button: Card saved
Your server calls:
- POST /v1/campaigns/{campaignId}/activateActivate a campaign: the customer's campaign, once paymentmethod_create arrives for their account
Charitips then sends the
campaign_updatewebhook to your endpoint.03
Thank a colleague with 10 €
The sender writes the kudos and picks the amount, within the monthly budget your platform enforces per person. The donation goes out without a charity: the colleague who is thanked chooses it.
Button: Send kudos with 10 €
Your server calls:
- POST /v1/donationsCreate a donation: on the customer's campaign, without charityId: the colleague chooses; amount in cents
Charitips then sends the
donation_createwebhook to your endpoint.04
Nora chooses where the 10 € go
The thanked colleague opens the kudos and picks the charity: two people engaged by one kudos. Without a choice, the donation still goes to one of the team's charities.
The customer picks a charity from your selection. Button: Give 10 €
Your server calls:
- POST /v1/donations/{donationId}/claimClaim a donation: donationId from the create-donation response
Charitips then sends the
donation_updatewebhook to your endpoint.05
Your giving dashboard
The admin lands in the Charitips dashboard of their own account, signed in by the link. Creating the child account also created a dashboard user for its contact, so your server only reads that user's id.
Button: Open the giving dashboard
Your server calls:
- GET /v1/usersList users: once: accountId=<customerAccountId> in the query; the user created with the account, store its userId
- POST /v1/authentication/magic-links/users/{userId}Create a user magic link: userId in the path; redirect the admin to the returned link