Skip to content
Aller au contenu
Charitips

Use cases · Engagement

A reward validated later

The donation is created when the person submits; your team validates it, with its final amount, once the fact is checked.

  • Who paysYour company
  • Starts withA customer action
  • Tax receiptIn your company's name

Needs API access on a validated account. Plans

Device
Charities shown as
Outline widget
security.your-saas.example

security.your-saas.example

Step by step

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

  2. 1When the report is sent

    To come

    Your customer does…

    Clicks “Send the report”.

    Your server sends…

    Creates a 500 € donation for report #412 on the campaign “Your security portal”.

    POSTcreate-donation

    Charitips answers…

    Charitips records the donation and returns its id: it waits for your customer to pick a charity.

    Charitips will then tell your server the donation was created.

  3. 2When the charity is chosen

    To come

    Your customer does…

    Clicks “Choose the charity”.

    Your server sends…

    Assigns that donation to the charity your customer picks.

    POSTclaim-donation

    Charitips answers…

    The donation now goes to the charity your customer picks.

    Charitips will then tell your server the donation was updated.

  4. 3When the vulnerability is reviewed

    To come

    Your customer does…

    Clicks “Validate: 500 €”.

    Your server sends…

    Calls validate donation.

    POSTvalidate-donation

    Charitips answers…

    Charitips answers the call.

    Charitips will then tell your server the donation was updated.

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.

Scenarios this flow covers The same calls cover each of these.

One flow, 6 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 appsBug bountyA SaaS pays its bug bounty in donations: 5 € to 5 000 € by severity. The researcher submits a report and picks the charity; the security team sets the amount at validation.5 € to 5 000 € by severity, set at validationOpen its page
Professional servicesEmployee referral bonusA company adds 50 € for a charity on top of each employee referral bonus. The employee picks the charity when the hire is made; HR validates after the probation period.50 € once the hire passes the trial periodOpen its page
Health and sportBottles returned by postA beauty brand gives 0,50 € for each empty bottle sent back with a prepaid label. The customer declares the parcel and picks the charity; the workshop validates each bottle.0,50 € per bottle received and checkedOpen its page
Banking and insuranceHealth goal validatedA health insurer gives 20 € when a member declares a health goal with proof. The member picks the charity when declaring; the insurer checks the proof and validates the donation.20 € per goal validated by a doctorOpen its page
Software and appsAppointment keptA medical practice gives 0,20 € when a patient confirms a reminder, 50 % more if they arrive on time. The patient picks the charity when confirming; reception validates arrival.0,20 € per confirmed reminder, +50 % if on timeOpen its page
Professional servicesReal-world mission validatedA field missions app turns a mission's 5 € reward into a donation. The worker completes the mission and picks the charity; the ops team validates the report, the app pays.5 € per mission validated by the ops teamOpen its page

Build it

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

Callscreate-charities-selectioncreate-campaignactivate-campaigncreate-donationclaim-donationvalidate-donation
Webhooksdonation_createdonation_update

Before you start

  • A campaign created with withDonationsValidation.

  1. Create a campaign with validation

    Once, create the campaign with withDonationsValidation, after its charities selection, then activate it. With donationsBilledOn set to CLAIM, a donation is billed when you validate it, at its final amount.

    POST /v1/campaigns
    curl -X POST https://api.sandbox.charitips.com/v1/campaigns \  -H "Authorization: Bearer $CHARITIPS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "name": "Bug bounty",    "charitiesSelectionId": "<charitiesSelectionId>",    "withDonationsValidation": true,    "donationsBilledOn": "CLAIM"  }'
    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.

  2. Give when the person submits

    A bug report, a hiring referral or bottles sent back by post: when the person submits, create the donation with the amount you expect.

    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": 500,    "uniqueExternalId": "bug_report_4410",    "externalId": "researcher_207"  }'
    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. Let the person pick a charity

    The person picks the charity when they submit. Claim the donation with their choice.

    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.

  4. Validate once the fact is checked

    Once your team has checked the fact, validate the donation. Validation needs a claimed donation: the API answers 400 Donation not claimed yet otherwise, and 409 Donation already validated the second time.

    POST /v1/donations/<donationId>/validate
    curl -X POST https://api.sandbox.charitips.com/v1/donations/<donationId>/validate \  -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.

  5. Set the amount at validation

    When the amount depends on the review, a severity or a count of items received, send the final amount with the validation. Without amount, the donation keeps the amount it was created with.

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

  • The fact is not confirmed. Delete the donation instead of validating it.
  • The review takes more than a week. In production, a donation not validated and not billed 7 days after its creation is deleted automatically.
  • Personal data. Health goals, appointments and hires stay in your product: never put them in externalId, uniqueExternalId or the donor fields.
  • Fiscal receipts. You fund the donations, so the receipt goes to your company.

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