Skip to content
Aller au contenu
Charitips

Use cases · Community

Your users give their own money

You collect the funds, the fiscal receipt goes to the donor.

  • Who paysYour users
  • Starts withYour users choose to give
  • Tax receiptIn the user's name

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

Device
Charities shown as
Outline widget
your-app.example/donate

your-app.example/donate

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 50 € to the charity”.

    Your server sends…

    Creates a 50 € donation for payment #9031 on the campaign “Donations”, 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 “Donation processed”.

    Your server sends…

    Asks for the fiscal receipt of that donation.

    POSTcreate-donation-fiscal-receipt

    Charitips answers…

    Charitips issues the fiscal receipt.

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

  4. 3Receipt downloaded

    To come

    Your customer does…

    Clicks “Download the PDF”.

    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. Users donate their own money, receipt to them: that is the case the demo plays. The same flow also covers:

One flow, 8 variants

Each card is this flow in another sector or use case. Pick one: the demo above plays it, with its site, its amounts and its charities. The API calls stay the same.

Software and appsUsers give their own moneyAn app lets users give their own money: they pick a charity and an amount, then pay the app. The server records the donation after payment; the receipt is in the donor's name.A one-off gift, the receipt in the donor's nameOpen its page
Professional servicesDonation matchingA user gives 20 € and the company adds 20 €. The user picks the charity, pays and gets the receipt for their part; the company gets its own receipt for the matched part.The user gives 20 €, the company adds 20 €Open its page
Banking and insuranceAn extra on a group potOn a group pot, a contributor chips in for the gift and can add a donation in their own name on top. They pick the charity; the receipt is theirs, next to the platform's fee share.A contributor's extra, next to the platform's fee shareOpen its page
Banking and insuranceSavings interest, matchedA bank proposes to give 10 % of the interest just credited on a savings account, and matches it euro for euro. The customer picks the charity and confirms; two receipts, one each.10 % of the interest, matched by the bankOpen its page
Software and appsBadge unlocked by a giftA community platform sells a supporter badge for a 2 € donation. The member picks the charity and pays; the badge shows on their profile and the receipt is in their name.2 € to unlock a profile badgeOpen its page
RetailSecond-hand seller's shareOn a second-hand marketplace, a seller gives 10 % of a sale from their payout, in their own name. A badge shows on their listings and buyers see where the share goes.10 % of a sale, given by the seller in their nameOpen its page
RetailPart of a buyback payoutA buyback service offers 182 € for a used smartphone. Before accepting, the seller can give part of the payout to a charity they pick; the receipt is in their name.A platform buys a used smartphone for 182 €, the seller gives part of the payout in their nameOpen its page
RetailPart of a clothes buybackA fashion store buys back clothes dropped off in store, 26,40 € for seven pieces. The customer can give part of the buyback to a charity they pick; the receipt is theirs.Clothes dropped off in store, 26,40 € bought back, part of it given in the person's nameOpen its page

Build it

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

Callscreate-charities-selectioncreate-campaignactivate-campaigncreate-donationcreate-donation-fiscal-receiptget-donation-fiscal-receiptgenerate-fiscal-receipt-download-urlupdate-donation-matching
Webhooksdonation_createfiscalreceipt_generated

Before you start

  • The B2C use case.

  1. Request B2C access

    The B2C use case lets you create donations on behalf of individual users and issue their fiscal receipts. Ask for it at contact@charitips.com: our team approves it on your account.

  2. Create a charities selection

    The charities offered to your users come from a charities selection, created with Create a charities selection. Get the charity ids from List charities.

    POST /v1/charities-selections
    curl -X POST https://api.sandbox.charitips.com/v1/charities-selections \  -H "Authorization: Bearer $CHARITIPS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "name": "Hero Corp selection",    "charityIds": [      "ca68f22c-2fdf-48b1-b8f6-43c3073e83bb",      "1cccaa7c-cc5e-4dc8-9978-fc2de5f5d7b3",      "0d65b4e6-f663-4ec7-b69d-0da5e7e8b2ee"    ],    "accountId": "<accountId>"  }'
    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. Create and activate the campaign

    Every donation belongs to a campaign, which holds the configuration of the donation flow. Create it with Create a campaign, then activate it with Activate a campaign: campaigns are created PENDING. Create one campaign per use case if you have several, and write to contact@charitips.com for help with the first one.

    POST /v1/campaigns
    curl -X POST https://api.sandbox.charitips.com/v1/campaigns \  -H "Authorization: Bearer $CHARITIPS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "accountId": "<accountId>",    "charitiesSelectionId": "<charitiesSelectionId>",    "name": "Hero Corp Campaign"  }'
    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. Create a donor for each user

    A Donor stands for one of your users. Create it with Create a donor and link it to your user with uniqueExternalId. A donor lets a logged-in user give through authenticated widgets, with a donation history, recurring donations and consolidated fiscal receipts.

    POST /v1/donors
    curl -X POST https://api.sandbox.charitips.com/v1/donors \  -H "Authorization: Bearer $CHARITIPS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "firstName": "John",    "lastName": "Doe",    "email": "john@doe.com",    "street": "8 rue de la Paix",    "zip": "75002",    "city": "Paris",    "country": "FR",    "uniqueExternalId": "<userId>"  }'
    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.

  5. Show a donor widget

    The donor widgets take the donation in your product. The charity selection and payment widget collects the donor's fiscal information and the payment, creates and claims the donation, issues the fiscal receipt and can save the payment method. The payment only widget takes the charityId from your own charity selection UI, so show enough about each charity for users to choose. An authenticated widget needs a token from Create a donor widget token; an unauthenticated one needs none and creates a new donor with each donation, for guests and one-off donations.

    POST /v1/authentication/donor/widget
    curl -X POST https://api.sandbox.charitips.com/v1/authentication/donor/widget \  -H "Authorization: Bearer $CHARITIPS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "donorId": "<donorId>"  }'
    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. Create the donation you charged

    When you collect the funds yourself, for example in your own checkout, create the donation from your backend once the charity is chosen. Set hasBeenCharged: true and pass the donor's name and postal address in donor, for the receipt in their name. Only a charity whose fiscalReceiptsSupport is ENABLED issues one: offer those when your users want a receipt. When the user opts out of the receipt, set withFiscalReceipt: false and leave donor out.

    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>",    "externalId": "<externalId>",    "uniqueExternalId": "<uniqueExternalId>",    "amount": 2000,    "hasBeenCharged": true,    "donor": {      "firstName": "John",      "lastName": "Doe",      "email": "john@doe.com",      "street": "8 rue de la Paix",      "zip": "75002",      "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.

  7. Claim the donation

    Link the donation to the chosen charity with Claim a donation. You can also pass charityId when you create the donation, which claims it at once.

    POST /v1/donations/<donationId>/claim
    curl -X POST https://api.sandbox.charitips.com/v1/donations/<donationId>/claim \  -H "Authorization: Bearer $CHARITIPS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "charityId": "<charityId>"  }'
    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.

  8. Issue a receipt on demand

    To issue a receipt before the yearly one, call Create a donation fiscal receipt with the donationId. The donation must be paid and carry the donor's fiscal information.

    POST /v1/donations/<donationId>/fiscal-receipts
    curl -X POST https://api.sandbox.charitips.com/v1/donations/<donationId>/fiscal-receipts \  -H "Authorization: Bearer $CHARITIPS_TOKEN"
    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.

  9. Download the receipt

    Get the PDF link with Generate a fiscal receipt download url. The PDF is generated asynchronously and can take a few seconds, so retry when the link is not ready yet.

    GET /v1/fiscal-receipts/<fiscalReceiptId>/download-url
    curl -X GET https://api.sandbox.charitips.com/v1/fiscal-receipts/<fiscalReceiptId>/download-url \  -H "Authorization: Bearer $CHARITIPS_TOKEN"
    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.

  10. Offer monthly giving

    Authenticated donors can give every month through the recurring donations widget, charged on their saved payment method. To let users stop it from your product, call Cancel a recurring donation.

    POST /v1/recurring-donations/<recurringDonationId>/cancel
    curl -X POST https://api.sandbox.charitips.com/v1/recurring-donations/<recurringDonationId>/cancel \  -H "Authorization: Bearer $CHARITIPS_TOKEN" \  -H "Content-Type: application/json" \  -d '{}'
    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.

  11. Manage donor profiles

    Read and update donors with List donors, Get a donor and Update a donor. Show their saved cards with List donor payment methods, their receipts with List donor fiscal receipts, their donations with List donations filtered on donorId, and their recurring donations with List recurring donations.

  12. Billing and receipts

    Donations paid in the donor widgets are charged on the user's card at once, never on your invoice. Donations you create with hasBeenCharged: true after your own checkout are billed to you monthly. Either way, Charitips transfers the funds to the chosen charities. Fiscal receipts are issued yearly by default, which suits users who give several times. With unauthenticated widgets, the receipt is issued right after each payment.

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