Skip to content
Aller au contenu
Charitips

Use cases · Community

Donation matching

Your users give, you add to it. The rate and the budget are set once on the campaign.

  • Who paysYour users and your company
  • Starts withYour users choose to give
  • Tax receiptIn each giver's name

Needs API access and the B2C use case on a validated account. Plans

One variant of Your users give their own money

The family page plays this case next to the other sectors that run the same calls.

See every variant
Device
Charities shown as
Outline widget
Matching rate
your-app.example/give

your-app.example/give

Step by step

Click through the site. Each step shows what your customer does, what your server sends and what Charitips answers.

  2. 1Donation paid

    To come

    Your customer does…

    Clicks “Give 20 € to the charity”.

    Your server sends…

    Creates a 20 € donation for payment #6610 on the campaign “Matched giving”, for the charity your customer picks, paid by Camille Martin with a fiscal receipt in their name.

    POSTcreate-donation

    Charitips answers…

    Charitips records the donation and returns its id: it goes to the charity your customer picks at once, and the fiscal receipt will be in Camille Martin's name.

    Charitips will then tell your server the donation was created.

  3. 2Receipt issued

    To come

    Your customer does…

    Clicks “Simulate the processing”.

    Your server sends…

    Once the donation is processed, Charitips issues the fiscal receipt of the user's part, in the donor's name, and tells your server.

    Charitips answers…

    Charitips will then tell your server the fiscal receipt is ready.

  4. 3Receipt downloaded

    To come

    Your customer does…

    Clicks “Download my receipt”.

    Your server sends…

    Reads the fiscal receipt of that donation.

    GETget-donation-fiscal-receipt

    Asks for a download link to that receipt.

    GETgenerate-fiscal-receipt-download-url

    Charitips answers…

    Charitips returns the receipt and its id.

    Charitips returns a download link that expires soon.

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.

Build spec

The site is made up and nothing is sent. The endpoints, fields and webhook events are the real ones, and so are the charities.

This demo is one example. User gives 20 €, company adds 20 €: that is the case the demo plays. The same flow also covers:

Build it

The calls behind the demo, in order. Each step shows the request your server sends.

Callscreate-charities-selectioncreate-campaignactivate-campaignupdate-donation-matchingcreate-donationget-donation-fiscal-receiptgenerate-fiscal-receipt-download-urlclaim-donation
Webhooksdonation_createfiscalreceipt_generated

Before you start

  • The B2C use case (hasBeenCharged: true).
  • Each donation claimed for a charity.

  1. Set up the campaign

    Set up the campaign as in steps 3 to 5 of Your first donation: 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.

  2. 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.

    PATCH /v1/campaigns/<campaignId>/donation-matching
    curl -X PATCH https://api.sandbox.charitips.com/v1/campaigns/<campaignId>/donation-matching \  -H "Authorization: Bearer $CHARITIPS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "status": "ENABLED",    "rate": 1,    "maximumBudget": 500000,    "maximumDonorBudget": 10000  }'
    Built from the spec and the API code

    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.

  3. 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.

    POST /v1/donations
    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,    "uniqueExternalId": "gift_7731",    "hasBeenCharged": true,    "charityId": "<charityId>",    "donor": {      "firstName": "Camille",      "lastName": "Martin",      "email": "camille@example.com",      "street": "12 rue des Lilas",      "zip": "75011",      "city": "Paris",      "country": "FR"    }  }'
    Built from the spec and the API code

    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.

  4. 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 returns it with includeChildDonations, and List donations 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.

  5. 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), the email Charitips sends on an EMAIL campaign, or the charity selection widget 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.

    POST /v1/donations
    curl -X POST https://api.sandbox.charitips.com/v1/donations \  -H "Authorization: Bearer $CHARITIPS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "campaignId": "<campaignId>",    "amount": 2500,    "uniqueExternalId": "thank_you_5521",    "externalId": "thank_you_5521"  }'
    Built from the spec and the API code

    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.

  6. 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, or pass includeMatchedDonations to List donations.

  7. 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.

    POST /v1/donations
    curl -X POST https://api.sandbox.charitips.com/v1/donations \  -H "Authorization: Bearer $CHARITIPS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "campaignId": "<campaignId>",    "amount": 1000,    "uniqueExternalId": "thank_you_5521_top_up",    "externalId": "thank_you_5521",    "hasBeenCharged": true,    "charityId": "<charityId>",    "parentDonationId": "<donationId>",    "donor": {      "firstName": "Camille",      "lastName": "Martin",      "email": "camille@example.com",      "street": "12 rue des Lilas",      "zip": "75011",      "city": "Paris",      "country": "FR"    }  }'
    Built from the spec and the API code

    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.

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.

The memo

Send the memo to your team

Already written for this flow

  • What it does and who pays, in a few sentences
  • What you need: plan, API calls and webhooks
  • What you can report: donations, charities, impact and receipts

To paste in an email, a document or a note.

Email it

Related pages