Integrate
Charity selection widget
Show your campaign's charities in your product and let people choose one, with or without an amount, before or after the donation is created.
The charity selection widget shows the charities of a campaign, with their profiles and what a donation funds, and lets the person choose one. It opens with the campaign's publicKey, so it can run in any browser or app.
In short
- Pick a
type: show the charities only, let the person choose a charity, a charity and an amount, a charity for later, or claim a donation you already created. - When the person chooses,
onCharitySelectedcalls your server, which creates and claims the donation with the API. Your credentials never reach the browser. - The widget shows amounts in euros, or in your own unit with
currencySymbolandcurrencyValue. - Install the libraries first: see Widgets.
Pick a type
type | The person | You set |
|---|---|---|
presentation (default) | browses the charities, without choosing | nothing more |
charity_and_amount_selection | chooses a charity and an amount | onCharitySelected, and balance for a maximum |
charity_selection | chooses a charity for an amount you know | amount in cents and onCharitySelected |
charity_preselection | chooses a charity to keep for later | onCharityPreselected |
claim | chooses the charity of a donation you created | donationSecret, or voteSecret for a vote |
charity_and_amount_selection and charity_selection create the donation and claim it in one go, when the person chooses: no donation is left waiting. Prefer them to claim.
Choose a charity and an amount
When the person confirms, the widget calls onCharitySelected with the charityId and the amount chosen, in euros, and shows a loader until the promise resolves. Call your server there: it creates the donation, already claimed, with Create a donation and the charityId, converts the amount to cents, and passes your own id as uniqueExternalId. Return the donation: the widget then shows its thank-you screen.
import { CharitySelectionWidget } from '@charitips/embed-react'; export function GiveScreen({ publicKey, orderId }: { publicKey: string; orderId: string }) { const onCharitySelected = async ({ charityId, amount }: { charityId: string; amount?: number }) => { // Your server calls POST /v1/donations with the charityId, the amount in cents and orderId as uniqueExternalId. const response = await fetch('/api/donations', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ charityId, amount, orderId }), }); return response.json(); // { donationId } }; return ( <CharitySelectionWidget publicKey={publicKey} type="charity_and_amount_selection" balance={100} size="fitContent" onCharitySelected={onCharitySelected} /> );}On your server, the call it makes:
curl -X POST https://api.sandbox.charitips.com/v1/donations \ -H "Authorization: Bearer $CHARITIPS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "campaignId": "<campaignId>", "amount": 2000, "charityId": "<charityId>", "uniqueExternalId": "order_1042" }'Request bodies are written for this docs and checked against the API's validation; ids in angle brackets are placeholders. Response values are placeholders built from the schema.
balance is the most the person can give, in euros, 100 by default. For a vote campaign, create a vote and cast it, and return { voteId }.
In your own unit
To show points, credits or coins instead of euros, add currencySymbol (the name of your unit) and currencyValue (how many units make 1 €). balance and the amount received are then in your unit: convert to cents on your server. See Your own currency.
Choose a charity for a known amount
With charity_selection, the amount is yours to set, in cents: the widget shows what it funds at each charity, and onCharitySelected receives the charityId only.
createWidget({ baseUrl: 'https://embed.sandbox.charitips.com', container: document.querySelector('#charities'), publicKey: '<campaign publicKey>', type: 'charity_selection', amount: 2000, onCharitySelected: async ({ charityId }) => createDonationOnYourServer(charityId),});Keep a charity for later
With charity_preselection, the person picks a charity, for example in their profile settings, and nothing is created: onCharityPreselected gives you the charityId to store. Show the stored one with preselectedCharityId, and pass it as charityId when you create a donation later.
createWidget({ baseUrl: 'https://embed.sandbox.charitips.com', container: document.querySelector('#favourite-charity'), publicKey: '<campaign publicKey>', type: 'charity_preselection', layout: 'row', preselectedCharityId: '<stored charityId>', onCharityPreselected: ({ charityId }) => saveOnYourServer(charityId),});Claim a donation you created
Your server creates the donation first, without a charity, with Create a donation. Its response holds the donation's secret: pass it as donationSecret, and the widget claims the donation when the person chooses. For a vote, pass the vote's secret as voteSecret.
createWidget({ baseUrl: 'https://embed.sandbox.charitips.com', container: document.querySelector('#charities'), publicKey: '<campaign publicKey>', type: 'claim', donationSecret: '<donation secret>',});A person who leaves without choosing leaves the donation waiting until it expires. Reuse the same donation when they come back, by finding it with your uniqueExternalId, and delete the ones you no longer need before they are invoiced. See Donation lifecycle.
Options
| Option | Type | What it does |
|---|---|---|
publicKey | string | the campaign whose charities are shown, required |
type | string | one of the types above, presentation by default |
amount | number | with charity_selection, the amount in cents |
balance | number | with charity_and_amount_selection, the most the person can give, in euros or in your unit |
currencySymbol, currencyValue | string, number | your own unit and how many of it make 1 € |
donationSecret, voteSecret | string | with claim, the secret of the donation or the vote |
preselectedCharityId | string | with charity_preselection, the charity shown as chosen |
onCharitySelected | ({ charityId, amount }) => Promise | creates the donation on your server and resolves with { donationId } or { voteId } |
onCharityPreselected | ({ charityId }) => void | receives the charity chosen with charity_preselection |
onDonationClaimed | ({ charityId }) => void | called once the donation is claimed |
onCloseSuccess | () => void | called when the person closes the thank-you screen |
disableSuccessModal | boolean | skips the thank-you screen: your product takes over, and the button keeps loading |
layout | grid, row or list | how the charities are laid out, grid by default |
hideSearch | boolean | hides the search bar and its filters |
withInstructions, withDescription, withDiscoverButton | boolean | show the instructions, the campaign's title and description, and a button to see the charities |
termsOfServiceLink, termsOfSalesLink, privacyPolicyLink | string | adds a checkbox to accept your terms before choosing |
size, locale, id | see Options every widget shares |
Related
Charities and selections, A donation with every order, Your own currency, Donor widgets.