# Demo: Donation matching

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

One variant of **Your users give their own money**, in Professional services: The user gives 20 €, the company adds 20 €.

A made-up site, your-app.example/give, walked through screen by screen with the Charitips API calls the product makes at each step. Rebuild it in your own project to start from a working flow.

The charity choice in this demo is the Charitips [charity selection widget](https://www.charitips.com/docs/widgets/charity_selection.md), a ready-made proposal. Use it whole, use parts of it, or build your own experience from scratch with the API: [List charities](https://www.charitips.com/docs/api-reference/list-charities.md) gives the charities to show, and the calls below carry the chosen `charityId`.

Charitips widget: the charity cards and their profiles. Your own UI, built with the API: the amount, the matching budget, the payment form and the confirmation.

The full guide, with edge cases: https://www.charitips.com/docs/use-cases/donation-matching.md.

The full guide, with edge cases: https://www.charitips.com/docs/use-cases/donation-matching.md.

**Once, before the first customer:**

- [`POST /v1/charities-selections`](https://www.charitips.com/docs/api-reference/create-charities-selection.md) Create a charities selection: once: the charities you offer, from the catalog

  ```json
  {
    "name": "Matched charities",
    "charityIds": [
      "<charityId>"
    ]
  }
  ```
- [`POST /v1/campaigns`](https://www.charitips.com/docs/api-reference/create-campaign.md) Create a campaign: once: the campaign the donations go to

  ```json
  {
    "name": "Matched giving",
    "charitiesSelectionId": "<charitiesSelectionId>"
  }
  ```
- [`POST /v1/campaigns/{campaignId}/activate`](https://www.charitips.com/docs/api-reference/activate-campaign.md) Activate a campaign: once: the campaign starts taking donations
- [`PATCH /v1/campaigns/{campaignId}/donation-matching`](https://www.charitips.com/docs/api-reference/update-donation-matching.md) Update a donation matching: once: the rate and the budgets, in cents

  ```json
  {
    "status": "ENABLED",
    "rate": "1",
    "maximumBudget": 500000,
    "maximumDonorBudget": 10000
  }
  ```

## Screens and calls

### 1. Give to a cause, we add the same

The user picks the charity, then the amount, and pays you. With a fiscal receipt, 20 € costs them 6,80 € after tax. Two receipts: the user's for their part, the company's for the part it adds.

- Your gift: 20,00 €
- We add: 20,00 €
- **Total donation: 40,00 €**
- The customer picks a charity from your selection.
- Button: Give 20 € to the charity

**Your server calls:**

- [`POST /v1/donations`](https://www.charitips.com/docs/api-reference/create-donation.md) Create a donation: after your payment succeeds; with charityId the matched part is created at once

  ```json
  {
    "campaignId": "<campaignId>",
    "amount": 2000,
    "uniqueExternalId": "payment_6610",
    "hasBeenCharged": true,
    "withFiscalReceipt": true,
    "charityId": "<charityId>",
    "donor": {
      "firstName": "Camille",
      "lastName": "Martin",
      "email": "camille.martin@example.com",
      "street": "12 rue des Lilas",
      "zip": "75011",
      "city": "Paris",
      "country": "FR"
    }
  }
  ```

Charitips then sends the `donation_create` webhook to your endpoint.

### 2. Your receipt is ready

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

- Button: Simulate the processing

No call: this screen only shows the result.

Charitips then sends the `fiscalreceipt_generated` webhook to your endpoint.

### 3. Download my receipt

Your server reads the receipt of the donation, then asks for a download link.

- Button: Download my receipt

**Your server calls:**

- [`GET /v1/donations/{donationId}/fiscal-receipt`](https://www.charitips.com/docs/api-reference/get-donation-fiscal-receipt.md) Get a donation fiscal receipt: donationId from the create-donation response
- [`GET /v1/fiscal-receipts/{fiscalReceiptId}/download-url`](https://www.charitips.com/docs/api-reference/generate-fiscal-receipt-download-url.md) Generate a fiscal receipt download url: fiscalReceiptId from the receipt; the link expires, ask for it when the user clicks

## Clone it with a coding agent

```prompt
Clone the Charitips demo "Donation matching" into this project. Read https://www.charitips.com/docs/demos/matching.md: it lists each screen and the Charitips API calls behind it. Build the same flow in this codebase, on the sandbox (https://api.sandbox.charitips.com), with my client id and secret read from environment variables, and follow the rules of https://www.charitips.com/docs/skill.md. Make every API call from the server, never from the browser. When it works, show me each call and its response.
```