Skip to content
Aller au contenu
Charitips

Use cases · Platforms

A sale split between seller and buyer

On a marketplace, a listing marked for charity gives a share paid by the seller and an extra paid by the buyer, each on its own account.

  • Who paysYour business customers
  • Starts withA purchase
  • Tax receiptIn each business customer's name

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

Device
Charities shown as
Outline widget
listings.your-marketplace.example

listings.your-marketplace.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 listing goes live

    To come

    Your customer does…

    Clicks “Publish the listing”.

    Your server sends…

    No call: your side saves it.

    Charitips answers…

    Nothing: Charitips is not called at this step.

  3. 2When the order is paid: the seller's part

    To come

    Your customer does…

    Clicks “Pay 65,80 €”.

    Your server sends…

    Creates a 0,90 € donation for order 20931 seller on the campaign “Charity sales”.

    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.

  4. 3When the order is paid: the buyer's extra

    To come

    Your customer does…

    Clicks “Pay 65,80 €”.

    Your server sends…

    Creates a 0,90 € donation for order 20931 buyer on the campaign “Charity sales”, paid by Camille Martin with a fiscal receipt in their name.

    POSTcreate-donation

    Charitips answers…

    Charitips records the donation and returns its id: it waits for your customer to pick a charity, and the fiscal receipt will be in Camille Martin's name.

    Charitips will then tell your server the donation was created.

  5. 4When 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.

  6. 5The buyer's extra follows the same choice

    To come

    Your customer does…

    Sees “The buyer's extra follows the same choice”.

    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.

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

RetailSolidarity saleA marketplace seller marks a listing as a charity sale and gives 3 % of the price. The buyer picks the charity after paying and can add an extra; each pays on their own account.3 % of the sale, split between seller and buyerOpen its page
RetailIndependent maker's saleAn independent maker on a marketplace gives 5 % of a piece's price from their studio. The buyer picks the charity at checkout and can add their own extra, on a separate account.5 % of the price from the studio, plus the buyer's extraOpen its page

Build it

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

Callscreate-charities-selectioncreate-campaignactivate-campaigncreate-child-accountcreate-donationclaim-donation
Webhooksdonation_createdonation_update

Before you start

  • Each seller who marks a listing for charity has its own Charitips account under yours, with its own campaign and receipts.

  1. Give each seller an account

    Once per seller, when they turn the option on, create their own account under yours with Create a child account. Keep the accountId from the response with the seller's record. See Account hierarchy for the details it needs.

    POST /v1/accounts/<accountId>/child-accounts
    curl -X POST https://api.sandbox.charitips.com/v1/accounts/<accountId>/child-accounts \  -H "Authorization: Bearer $CHARITIPS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "name": "Seller A",    "firstName": "Jane",    "lastName": "Doe",    "email": "jane.doe@example.com",    "legalRegistrationNumber": "<SIREN or VAT number>",    "street": "8 rue de la Paix",    "city": "Paris",    "zip": "75002",    "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.

  2. Create the seller's campaign

    On the seller's account, create a charities selection and a campaign, both with the seller's accountId, then activate the campaign. It takes the seller's share of each charity sale.

    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": "Solidarity sales",    "accountId": "<seller accountId>",    "charitiesSelectionId": "<charitiesSelectionId>"  }'
    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 the campaign for extras

    Once, on your own account, create and activate the campaign that takes the buyers' extras. Your users pay them with their own money.

    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": "Buyer extras",    "charitiesSelectionId": "<charitiesSelectionId>"  }'
    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. Give the seller's share

    When the order is paid, create the seller's share on the seller's campaign: it exists on every charity sale. Each payer gets its own donation, with its own uniqueExternalId built from the order.

    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": "<seller campaignId>",    "amount": 300,    "uniqueExternalId": "order_1042_seller"  }'
    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. Add the buyer's extra

    When the buyer added the extra at checkout, create a second donation on your campaign, with hasBeenCharged, withFiscalReceipt and the buyer's address in donor.

    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": 96,    "uniqueExternalId": "order_1042_buyer",    "hasBeenCharged": true,    "withFiscalReceipt": true,    "donor": {      "firstName": "Camille",      "lastName": "Martin",      "email": "camille.martin@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.

  6. Claim both for the buyer's charity

    The buyer picks one charity on the confirmation page. Claim the seller's share with it, then the extra when there is one.

    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.

Edge cases

  • Only one side gives. Without the extra, the seller's share is the only donation and the buyer still chooses its charity. Create donations only for listings marked for charity.
  • Receipts. The buyer's receipt is issued in their name; the seller's goes to the seller's account, where they find their donations and their dashboard.
  • Prerequisites. The buyers' own money needs the B2C use case, and the accounts per seller the account hierarchy feature: see Plans and prerequisites.

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