Skip to content
Aller au contenu
Charitips

Concepts

Donations in your own currency

Show donations in your product's own virtual currency, fully abstracted if you want, while the API works in euro cents, and always show the real impact with the charity's impact indicators.

Your users never have to see a euro amount. Any product can show donations in its own virtual currency: credits in an app, points in a rewards program, coins on a marketplace, miles, tokens. The unit is yours, in any sector. Charitips only needs the amount in euro cents on each call for billing.

In short

  • The API takes and returns amounts in euro cents. Converting from your unit is done on your side, at a rate you set.
  • What you show your users is up to you: your unit only, the euro value, or both. A donation can stay fully behind your currency.
  • The charity selection widget shows your unit too: its amounts, the user's balance and each charity's impact.
  • The abstraction lives only in your product's interface and the widgets in it: the fiscal receipt, your invoices and your Charitips dashboard statistics are always in euros.
  • Always show what it funds: the real impact, computed from the amount and the charity's impact indicators ("200 credits: 1 meal").

How it works

  1. Pick a fixed rate in your product, for example 1,000 credits = 1 €. Keep it in your code or your configuration: the API never sees your unit.
  2. When your product gives, convert to cents and create the donation: 200 credits at that rate is "amount": 20.
  3. Show the gift in your unit wherever your users are, with the impact it funds. Showing the euro value is your choice. Say who pays: your company funds it, nothing is taken from the user's own balance unless that is your mechanic.
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": 20,    "charityId": "<charityId>",    "uniqueExternalId": "milestone_204118_6",    "externalId": "player_204118"  }'
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.

Use the id of the event in your product (a milestone, a purchase, a redemption) as uniqueExternalId, so a retry never gives twice.

With the Charitips widgets

When the choice of the charity happens in the charity selection widget rather than in your own interface, the widget shows your unit for you. Set three options:

  • currencySymbol: the name of your unit, shown next to every amount ("points", "credits").
  • currencyValue: how many of your units make 1 €, a whole number: 2 for 2 points = 1 €. The widget uses it to compute what each charity funds with the amount chosen ("40 points: 1 meal").
  • balance: with the charity_and_amount_selection type, the most the user can give, in your unit, usually their balance.
tsx
<CharitySelectionWidget publicKey={publicKey} type="charity_and_amount_selection" currencySymbol="points" currencyValue={2} balance={200} onCharitySelected={onCharitySelected} />

onCharitySelected receives the charity and the amount in your unit. Your server converts it to cents and creates the donation as above: 40 points at 2 points = 1 € is "amount": 2000.

Always show the real impact

Whatever unit you show, show what the donation really funds. Each charity of the catalog can publish impact indicators: what a set amount funds there. Get a charity and List charities return them in profile.impactIndicators, each with baseAmount (in cents), singularLabel and pluralLabel.

  • Divide your amount by an indicator's baseAmount to know how many it funds: 20 cents with a baseAmount of 20 is "1 meal".
  • Below one full unit, say the donation helps fund one ("helps fund 1 meal") rather than showing a fraction.
  • A charity without indicators has its purpose: show that instead.
  • To make a small gift speak, offer the charities whose smallest indicator your amount reaches, or set your rate so that one gift funds at least one unit.

Edge cases

  • Your rate changes. Donations already created keep their amount in cents. Show past gifts from your own records or from the donations' amount, never by applying the new rate to old units.
  • Your dashboard and invoices. Your team follows the donations in euros in the Charitips dashboard and on your invoices, whatever unit your users see.
  • Receipts. Whatever your product shows, the fiscal receipt always states the real amount in euros, issued to whoever funds the donation: your company when it gives, your user when they pay with their own money (see Billing and fiscal receipts).
  • The user pays. When users give their own money, it is a payment: they see the euro amount before they confirm, and you need the B2C use case on your account: see Your users give their own money. The abstraction is for donations your company funds.

Where it is used

Loyalty points turned into donations (points, miles, any reward currency), Progress and tiers (milestones in an app or a game), Gift card balance.

Reference

Create a donation, Get a charity, List charities, Charity selection widget.