Concepts

Donation lifecycle

How a donation goes from created to claimed for a charity, then paid to it, what happens when nobody chooses, and what you can still change or delete.

A donation is created with an amount, gets its charity when someone chooses one (the claim), then Charitips pays it to that charity. Its status tells you where it stands, and a webhook tells your server each time it moves.

In short

PENDING: created, no charity yet (or waiting for your approval).
DONE: the charity is chosen and the donation counts.
PROCESSED: Charitips has transferred the money to the charity.
A donation nobody claims is not lost: it is assigned to a charity automatically when its campaign ends, or, on most permanent campaigns, once it has expired.
You can change the amount only while a donation is neither claimed nor billed, and delete it until it is invoiced.

The steps

Created, PENDING. Your server calls Create a donation with the campaign, the amount in cents and your own id in uniqueExternalId. If you already know the charity, pass charityId and the donation is DONE at once (on a campaign without validation).
Claimed, DONE. The person picks a charity and your server calls Claim a donation with its charityId. They can also pick it on a Charitips page: the donation's page (its link comes with includeUrl on Get a donation), the email sent on an EMAIL campaign, or the charity selection widget.
Validated, only on a campaign with withDonationsValidation. After the claim the donation stays PENDING until you call Validate a donation, which may set the final amount. Then it is DONE.
Processed, PROCESSED. Once the donation is paid and its charity known, Charitips transfers the money to the charity and records the date in processedAt.

POST /v1/donations/<donationId>/claim

1curl -X POST https://api.sandbox.charitips.com/v1/donations/<donationId>/claim \2  -H "Authorization: Bearer $CHARITIPS_TOKEN" \3  -H "Content-Type: application/json" \4  -d '{5    "charityId": "<charityId>"6  }'

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.

Each step sends a webhook: donation_create when the donation is created, then donation_update on every change of status, with the donation and the fields that changed. See Webhooks configuration.

When nobody chooses

Every donation gets an expiryDate when it is created, from the campaign's donationValidityPeriod (2 months by default, one year at most). Once it has passed, Charitips may choose for the person.

On a permanent campaign billed on creation, without a fixed budget, votes or validation, a donation still unclaimed after its expiry date, and already paid, is assigned to a charity automatically.
When a campaign closes, by you or after its end date, every donation still waiting for a charity is assigned the same way (on a campaign billed on claim, only those already billed).

An assigned donation has autoAssigned set to true. The money always reaches a charity of the campaign.

Changing or removing a donation

Amount: Update a donation changes it while the donation is PENDING and not billed. Your externalId and uniqueExternalId can change at any time.
Delete: Delete a donation works until the donation is invoiced. Use it when an order is cancelled before your next invoice.
Not validated: on a campaign with withDonationsValidation, a donation still PENDING and not billed seven days after its creation is deleted by a daily job.
Cancelled: CANCELED is set, on a campaign with validation, for a donation you refuse before it is billed.

What can stop a donation from being created

403 Campaign has to be activated first. or 403 Campaign has ended.: check the campaign status. See Campaigns.
400 Insufficient campaign budget. (INSUFFICIENT_CAMPAIGN_BUDGET): a FIXED_AMOUNT campaign has no budget left for this amount.
400 Campaign is a DISTRIBUTION one. Only votes can be created: this campaign takes votes.
402 Missing payment method (MISSING_PAYMENT_METHOD), in production: the account billed for the donations has no payment method.
403 Providing hasBeenCharged and withFiscalReceipt is only enabled for customers with a B2C use case.: see Your users give their own money.
409: a donation with the same uniqueExternalId already exists in this account. Your retry is safe: find the existing one with the uniqueExternalId filter of List donations.

The full list, per call, is on Errors.

Donations linked to another one

A donation can have child donations, linked by their parentDonationId:

the part your company adds on a campaign with donation matching, created when the user's donation becomes DONE;
the top-up a person pays with their own money after claiming a donation you funded, on a Charitips page.

List donations leaves them out unless you pass includeMatchedDonations; Get a donation returns them with includeChildDonations.

Billing and receipts along the way

A donation is billed when it is created, or when it is claimed if the campaign has donationsBilledOn: CLAIM. On a FIXED_AMOUNT campaign the budget is billed instead, at activation. Its billingStatus goes from PENDING to BILLED, then PAID.
A donation your company funds is part of the company's fiscal receipt. A donation the user paid (hasBeenCharged: true) has its own receipt in the donor's name: Create a donation fiscal receipt works once it is PROCESSED, and fiscalreceipt_generated tells you when a receipt is ready.

See Billing and fiscal receipts.

Votes follow the same path

On a DISTRIBUTION campaign, Create a vote, then Cast a vote for a charity (409 Vote already casted the second time), and Validate a vote when the campaign validates them. The budget is shared between charities in proportion to the votes. See Customers vote on a budget.

Campaigns, Billing and fiscal receipts, Your first donation, Errors.