Skip to content
Aller au contenu
Charitips

Get started

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 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:

Shell
export CHARITIPS_CLIENT_ID="<your test_ client id>"export CHARITIPS_CLIENT_SECRET="<your test_ 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. 01

    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.

    POST /v1/authenticationReference

    POST /v1/authentication
    curl -X POST https://api.sandbox.charitips.com/v1/authentication \  -u "$CHARITIPS_CLIENT_ID:$CHARITIPS_CLIENT_SECRET"
    Built from the spec and the API code

  2. 02

    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.

    GET /v1/charitiesReference

    GET /v1/charities
    curl -X GET https://api.sandbox.charitips.com/v1/charities \  -H "Authorization: Bearer $CHARITIPS_TOKEN"
    Built from the spec and the API code

  3. 03

    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.

    POST /v1/charities-selectionsReference

    POST /v1/charities-selections
    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": [      "<charityId>"    ]  }'
    Built from the spec and the API code

  4. 04

    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.

    POST /v1/campaignsReference

    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": "Checkout donations",    "charitiesSelectionId": "<charitiesSelectionId>"  }'
    Built from the spec and the API code

  5. 05

    Activate the campaign

    Once the campaign has its selection, activate it with $CAMPAIGN_ID in the path to start registering donations.

    POST /v1/campaigns/<campaignId>/activateReference

    POST /v1/campaigns/<campaignId>/activate
    curl -X POST https://api.sandbox.charitips.com/v1/campaigns/<campaignId>/activate \  -H "Authorization: Bearer $CHARITIPS_TOKEN"
    Built from the spec and the API code

  6. 06

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

    POST /v1/donationsReference

    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": 2000,    "uniqueExternalId": "<orderId>"  }'
    Built from the spec and the API code

  7. 07

    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.

    POST /v1/donations/<donationId>/claimReference

    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
POST /v1/authentication
curl -X POST https://api.sandbox.charitips.com/v1/authentication \  -u "$CHARITIPS_CLIENT_ID:$CHARITIPS_CLIENT_SECRET"
Built from the spec and the API code

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.

Shell
API=https://api.sandbox.charitips.com/v1AUTH="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, and listen for donation events with Webhooks instead of polling.