--- title: "Your first donation" description: "Seven calls on the sandbox, from credentials to a donation linked to a charity." canonical: https://www.charitips.com/docs/get-started/first-donation --- # Your first donation > Seven calls on the sandbox, from credentials to a donation linked to a charity. ## Before you start You need a sandbox account and its credentials: a client id and a client secret that start with `test_`. [Open one on your own](https://www.charitips.com/docs/get-started/sandbox.md) if your team has none, then find them in the dashboard under Settings, API. Activating a campaign needs an active monthly subscription on the account that is billed for it (your account or the child account when billed directly), on the sandbox as well. A sandbox account opened on its own starts with one. If the activate call answers `402 NO_ACTIVE_SUBSCRIPTION`, contact us. The samples read your credentials and your token from environment variables. Set them once in your shell. Then either run the script at the end of this page, which passes each id to the next call, or paste the steps one by one and replace each `<…>` value with the id the previous step returned: ```bash export CHARITIPS_CLIENT_ID="" export CHARITIPS_CLIENT_SECRET="" export CHARITIPS_TOKEN=$(curl -s -X POST https://api.sandbox.charitips.com/v1/authentication \ -u "$CHARITIPS_CLIENT_ID:$CHARITIPS_CLIENT_SECRET" | jq -r .accessToken) ``` The last line is step 1. It needs `jq`; without it, copy `accessToken` from the response by hand. Run it again when the token expires, after an hour. ### 1. Create an access token Exchange your sandbox client id and secret for a token. It is valid for one hour, so cache it. The export above keeps it in CHARITIPS_TOKEN. ```bash curl -X POST https://api.sandbox.charitips.com/v1/authentication \ -u "$CHARITIPS_CLIENT_ID:$CHARITIPS_CLIENT_SECRET" ``` ### 2. List charities See the charities your users will choose from, and keep the id of one in CHARITY_ID with jq -r '.[0].charityId'. The script below the steps does it for you. ```bash curl -X GET https://api.sandbox.charitips.com/v1/charities \ -H "Authorization: Bearer $CHARITIPS_TOKEN" ``` ### 3. Pick your charities Group the charities your users will choose from: send a name (2 to 100 characters) and their ids in charityIds, here $CHARITY_ID. Keep the response's charitiesSelectionId in SELECTION_ID (jq -r .charitiesSelectionId): a campaign cannot be activated without one. ```bash curl -X POST https://api.sandbox.charitips.com/v1/charities-selections \ -H "Authorization: Bearer $CHARITIPS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Checkout charities", "charityIds": [ "" ] }' ``` ### 4. Create a campaign A campaign holds the settings of your donations. Send a name and $SELECTION_ID as charitiesSelectionId, and keep the response's campaignId in CAMPAIGN_ID (jq -r .campaignId). The campaign is created with status PENDING and has to be activated before it accepts donations. ```bash curl -X POST https://api.sandbox.charitips.com/v1/campaigns \ -H "Authorization: Bearer $CHARITIPS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Checkout donations", "charitiesSelectionId": "" }' ``` ### 5. Activate the campaign Once the campaign has its selection, activate it with $CAMPAIGN_ID in the path to start registering donations. ```bash curl -X POST https://api.sandbox.charitips.com/v1/campaigns//activate \ -H "Authorization: Bearer $CHARITIPS_TOKEN" ``` ### 6. Create a donation Send $CAMPAIGN_ID as campaignId, the amount in cents, and your own order id in uniqueExternalId: a retried call then fails with 409 instead of creating a second donation. Keep the response's donationId in DONATION_ID (jq -r .donationId). ```bash curl -X POST https://api.sandbox.charitips.com/v1/donations \ -H "Authorization: Bearer $CHARITIPS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "campaignId": "", "amount": 2000, "uniqueExternalId": "" }' ``` ### 7. Claim it for a charity Claiming links the donation to the charity your user picked: call it with $DONATION_ID in the path and $CHARITY_ID as charityId. ```bash curl -X POST https://api.sandbox.charitips.com/v1/donations//claim \ -H "Authorization: Bearer $CHARITIPS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "charityId": "" }' ``` ## Run it in one go The same calls as one script, after the export block above. Each id goes into a variable for the next call. The order id comes from the clock, because `uniqueExternalId` must be new on every run: a fixed one answers `409` from the second run on. ```bash API=https://api.sandbox.charitips.com/v1 AUTH="Authorization: Bearer $CHARITIPS_TOKEN" export CHARITY_ID=$(curl -s "$API/charities" -H "$AUTH" | jq -r '.[0].charityId') export SELECTION_ID=$(curl -s -X POST "$API/charities-selections" -H "$AUTH" \ -H "Content-Type: application/json" \ -d "{\"name\": \"Checkout charities\", \"charityIds\": [\"$CHARITY_ID\"]}" \ | jq -r .charitiesSelectionId) export CAMPAIGN_ID=$(curl -s -X POST "$API/campaigns" -H "$AUTH" \ -H "Content-Type: application/json" \ -d "{\"name\": \"Checkout donations\", \"charitiesSelectionId\": \"$SELECTION_ID\"}" \ | jq -r .campaignId) curl -s -X POST "$API/campaigns/$CAMPAIGN_ID/activate" -H "$AUTH" | jq . export DONATION_ID=$(curl -s -X POST "$API/donations" -H "$AUTH" \ -H "Content-Type: application/json" \ -d "{\"campaignId\": \"$CAMPAIGN_ID\", \"amount\": 2000, \"uniqueExternalId\": \"order_$(date +%s)\"}" \ | jq -r .donationId) curl -s -X POST "$API/donations/$DONATION_ID/claim" -H "$AUTH" \ -H "Content-Type: application/json" \ -d "{\"charityId\": \"$CHARITY_ID\"}" | jq . ``` If a variable reads `null`, the call before it failed: run that call alone without the `jq` part to see its error `message`. ## What's next Pick the guide that matches your product in [What you can build](https://www.charitips.com/docs/use-cases.md), and listen for donation events with [Webhooks](https://www.charitips.com/docs/webhooks/configuration.md) instead of polling.