--- title: "Donation matching" description: "Matching works both ways. Your users give and you add to it, or you give first and the person tops up your donation with their own money." canonical: https://www.charitips.com/docs/use-cases/donation-matching --- # Donation matching > Matching works both ways. Your users give and you add to it, or you give first and the person tops up your donation with their own money. This use case is one variant of **Your users give their own money**: https://www.charitips.com/docs/use-cases/b2c.md - **Who pays**: Your users and your company - **Starts with**: Your users choose to give - **Tax receipt**: In each giver's name - Needs [API access](https://www.charitips.com/docs/overview/plans.md#api-access-for-webhooks-and-credentials), [The B2C use case](https://www.charitips.com/docs/overview/plans.md#the-b2c-use-case-when-your-users-pay) on a validated account. [Plans](https://www.charitips.com/docs/overview/plans.md#what-every-flow-needs) Interactive demo on the page. The same flow as a build spec: https://www.charitips.com/docs/demos/matching.md **This demo is one example**: User gives 20 €, company adds 20 €. The same flow also covers: - [You give first, they top up](https://www.charitips.com/docs/use-cases/donation-matching.md#or-let-them-top-up-your-gift): Your company gives a donation, such as a gift card or a donation page, and the person who receives it adds their own money. - [Employer matching](https://www.charitips.com/docs/use-cases/employee-giving.md): Employees give their own money, and the employer matches each donation. - [Half matching](https://www.charitips.com/docs/use-cases/donation-matching.md#set-the-matching-rate): You add 50 cents for every euro given, instead of doubling it. - [A cap per person](https://www.charitips.com/docs/use-cases/donation-matching.md#set-the-matching-rate): Matching stops at a limit per donation, per donor and for the whole campaign. - [Monthly gifts, matched](https://www.charitips.com/docs/use-cases/donation-matching.md#then-create-the-users-donations): Users give the same amount every month: your server charges them, creates each month's donation with hasBeenCharged, and the campaign matches it. ## Build it - **Calls**: [`create-charities-selection`](https://www.charitips.com/docs/api-reference/create-charities-selection.md), [`create-campaign`](https://www.charitips.com/docs/api-reference/create-campaign.md), [`activate-campaign`](https://www.charitips.com/docs/api-reference/activate-campaign.md), [`update-donation-matching`](https://www.charitips.com/docs/api-reference/update-donation-matching.md), [`create-donation`](https://www.charitips.com/docs/api-reference/create-donation.md), [`get-donation-fiscal-receipt`](https://www.charitips.com/docs/api-reference/get-donation-fiscal-receipt.md), [`generate-fiscal-receipt-download-url`](https://www.charitips.com/docs/api-reference/generate-fiscal-receipt-download-url.md), [`claim-donation`](https://www.charitips.com/docs/api-reference/claim-donation.md) - **Webhooks**: `donation_create`, `fiscalreceipt_generated` - **Before you start**: The B2C use case (`hasBeenCharged: true`). - **Before you start**: Each donation claimed for a charity. ### Set up the campaign Set up the campaign as in [steps 3 to 5 of Your first donation](https://www.charitips.com/docs/get-started/first-donation.md#3-pick-your-charities): a charities selection, a campaign created with its `charitiesSelectionId`, then activated. Matching puts two payers on one gift, in either order: your users give and you top up, which is what the demo shows, or you give and they top up. ### Set the matching rate When your users give and you top up, set the matching once on the campaign. `rate` multiplies each donation: `1` matches it euro for euro, `0.5` adds half, and it goes from 0.5 to 5. `maximumBudget` caps what you add over the whole campaign, `maximumDonorBudget` per person and `maximumDonationBudget` per donation, all in cents. ```bash curl -X PATCH https://api.sandbox.charitips.com/v1/campaigns//donation-matching \ -H "Authorization: Bearer $CHARITIPS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "status": "ENABLED", "rate": 1, "maximumBudget": 500000, "maximumDonorBudget": 10000 }' ``` ### Then create the users' donations Only a donation the user paid for is matched: create it with `hasBeenCharged` set to `true`, which needs the B2C use case on your account, and either pass `charityId` or claim it afterwards. Pass the user in `donor`: the matched part is attached to the same donor, and the fiscal receipt of the user's donation needs their name and postal address. The matched part is created when the donation reaches the `DONE` status: at creation with `charityId`, otherwise at the claim, or at the validation on a campaign that validates its donations. A canceled donation is never matched. ```bash curl -X POST https://api.sandbox.charitips.com/v1/donations \ -H "Authorization: Bearer $CHARITIPS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "campaignId": "", "amount": 2000, "uniqueExternalId": "gift_7731", "hasBeenCharged": true, "charityId": "", "donor": { "firstName": "Camille", "lastName": "Martin", "email": "camille@example.com", "street": "12 rue des Lilas", "zip": "75011", "city": "Paris", "country": "FR" } }' ``` ### Read the matched part The matched part is a donation of its own, created by Charitips on the same campaign and for the same charity, linked to the user's by its `parentDonationId`. [Get a donation](https://www.charitips.com/docs/api-reference/get-donation.md) returns it with `includeChildDonations`, and [List donations](https://www.charitips.com/docs/api-reference/list-donations.md) returns it when you pass `includeMatchedDonations`. It is billed to you, and it counts on your company's fiscal receipt, not on the user's. Read the matching settings at any time with [Get a donation matching](https://www.charitips.com/docs/api-reference/get-donation-matching.md). ### Or let them top up your gift When you give first, fund a donation as usual, without `hasBeenCharged`: the value of a gift card, a thank-you to a customer or an employee. The person picks the charity on a Charitips page: the donation's own page (its link comes with `includeUrl` on [Get a donation](https://www.charitips.com/docs/api-reference/get-donation.md)), the email Charitips sends on an `EMAIL` campaign, or the [charity selection widget](https://www.charitips.com/docs/widgets/charity_selection.md) in your product, which claims an existing donation with its `secret`. Right after the claim, the confirmation offers to add their own money to the same charity, paid by card on Charitips. ```bash curl -X POST https://api.sandbox.charitips.com/v1/donations \ -H "Authorization: Bearer $CHARITIPS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "campaignId": "", "amount": 2500, "uniqueExternalId": "thank_you_5521", "externalId": "thank_you_5521" }' ``` ### Read the top-ups The top-up is a donation of its own on the same campaign, paid by the person, linked to yours by its `parentDonationId`. When they ask for a fiscal receipt, Charitips emails it to them in their name once the top-up is processed. To see the top-ups, read your donation with `includeChildDonations` on [Get a donation](https://www.charitips.com/docs/api-reference/get-donation.md), or pass `includeMatchedDonations` to [List donations](https://www.charitips.com/docs/api-reference/list-donations.md). ### Or collect the top-up yourself In an interface you build yourself, collect the top-up with your own payment provider. Then create a second donation with `hasBeenCharged: true`, the person in `donor`, the same `charityId` and your donation's id in `parentDonationId`, which needs the B2C use case. Your donation must be claimed already, on the same campaign: otherwise the API answers `400`. The top-up is created claimed and nothing is sent; it shows with your donation like a top-up made on a Charitips page. ```bash curl -X POST https://api.sandbox.charitips.com/v1/donations \ -H "Authorization: Bearer $CHARITIPS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "campaignId": "", "amount": 1000, "uniqueExternalId": "thank_you_5521_top_up", "externalId": "thank_you_5521", "hasBeenCharged": true, "charityId": "", "parentDonationId": "", "donor": { "firstName": "Camille", "lastName": "Martin", "email": "camille@example.com", "street": "12 rue des Lilas", "zip": "75011", "city": "Paris", "country": "FR" } }' ``` ## Edge cases - **A budget runs out.** Donations are still accepted: the matched part is cut to what is left of the budget, then there is none. - **Pause the matching.** Set `status` to `DISABLED`; the campaign keeps running. - **Both directions on one campaign.** A top-up is a donation the person paid, so if the campaign also has matching enabled, your company matches the top-up too. Use a campaign without matching for top-ups, unless that is what you want. - **A campaign without the top-up offer.** The offer shows after a donation, a vote or a recurring donation the person did not pay themselves, on every campaign by default. To turn it off, set the campaign's `postDonationWidgets` without `DONATION_MATCHING`, for example `["SOCIAL_SHARING", "CHARITY_NEWSLETTER_SUBSCRIPTION"]`, with [Update a campaign](https://www.charitips.com/docs/api-reference/update-campaign.md). ## Related pages - [Your users give their own money](https://www.charitips.com/docs/use-cases/b2c.md) - [Billing and fiscal receipts](https://www.charitips.com/docs/concepts/billing-and-receipts.md) - [Campaigns](https://www.charitips.com/docs/concepts/campaigns.md)