Create a donation

• campaignId#stringrequiredUUID

  Id of the campaign

• amount#integer (int64)requiredminimum 1

  Donation amount in minor currency unit i.e cents.

• externalId#string

  An optional internal id of your system e.g orderId or customerId. Can be used to link a donation to an entity in your system.

• uniqueExternalId#string

  Similar to externalId but should be unique across all donations. Can be used to prevent duplicate donations.

• donor#PartialDonor

  Only required for EMAIL, SLACK or POSTAL campaigns. Attach useful user data to donations for a better usage tracking. POSTAL campaigns require firstName, lastName, street, zip, city and country (FR only): the card is posted to this address.

  19 child fields

  • streetstring

    Address line 1

  • streetAdditionstring

    Address line 2

  • citystring

    City

  • countrystring

    Country alpha 2 ISO code

  • zipstring

    Zip code

  • firstNamestring

    Donor's first name

  • lastNamestring

    Donor's last name

  • emailstringemail address

    Donor's email.

  • companyNamestring

    Donor's company name.

  • phonestring

    Donor's phone number.

  • birthdatestring (date)

  • pictureUrlstringURL

    Donor's phone number.

  • titlestring

    Donor's job title.

  • personalEmailstringemail address

    Donor's personal email.

  • personastring

    Persona of the donor.

    CSRMARKETINGHRSALESCOMMUNICATIONPRODUCTSMBOTHER

  • extraInfostring

    Additional information about the donor.

  • externalIdstring

    Optional id to link this donor to an entity on your side.

  • uniqueExternalIdstring

    Similar to externalId but should be unique across all donors. Can be used to prevent duplicate donors

  • slackIdstring

    Donor's slack id. Required for SLACK campaigns.

• language#string

  Locale to be used to communicate with the donor. Default to the campaign's language value.

  fren

• hasBeenCharged#boolean

  Restricted to B2C use cases. True if the donor has been charged for this donation. In this case, the fiscal receipt will be issued to the donor. Fiscal receipt issuance requires the donor property to be provided including all fiscal information such as names, address etc. This property is commonly used in a B2C scenario where your customers are charged for the donation.

• withFiscalReceipt#boolean

  Restricted to B2C use cases. False if the donor has opted out of the fiscal receipt issuance. It's mostly used in a B2C scenario when the donor has been charged for a donation but doesn't want to provide their fiscal information. Default is campaign.withFiscalReceipt which default is true

• charityId#stringUUID

  Id of the Charity to which the donation will be made. Optional can be set on claim after getting the user's choice.

• parentDonationId#stringUUID

  Restricted to B2C use cases. Id of a claimed donation you funded on the same campaign, when the beneficiary tops it up with their own money. Requires hasBeenCharged and the charityId of that donation. The top-up is created claimed and is not sent.

• sendingDate#string (date-time)

  Required for EMAIL and SLACK campaigns, when Charitips sends it to the donor. For POSTAL campaigns, the day the card is handed to La Poste (Paris time): a business day, from the next posting batch (16:00 Paris) up to a year ahead, defaults to the next posting batch. Delivery takes 2 to 3 business days.

• hideAmount#boolean

  Hide the donation amount from the donor. Defaults to the campaign's defaultHideAmount value.

No field is described in the spec.

• donationId#stringalways returned

• amount#integer (int64)

• externalId#string

• uniqueExternalId#string

• status#DonationStatusalways returned

  PENDINGDONEPROCESSEDCANCELED

• secret#stringalways returned

• withFiscalReceipt#booleanalways returned

• hasBeenCharged#booleanalways returned

• claimedAt#string (date-time)

• validatedAt#string (date-time)

• processedAt#string (date-time)

• billingStatus#BillingStatusalways returned

  PENDINGBILLEDPAID

• hideAmount#booleanalways returned

• billedOn#DonationBilledOnalways returned

  CREATIONCLAIM

• autoAssigned#boolean

• expiryDate#string (date-time)

• sendingMode#CampaignSendingModealways returned

  MANUALEMAILPHYSICALSLACKPOSTAL

• sendingDate#string (date-time)

• sendingStatus#DonationSendingStatusalways returned

  PENDINGFAILEDDONE

• externalSendingId#string

• lastReminderId#string

• message#string

• reminderMessage#string

• from#string

• language#Languagealways returned

  fren

• sharedOn#SocialNetwork

  LINKEDININSTAGRAMFACEBOOKTWITTERWHATSAPP

• ptoType#PaidTimeOffTypealways returned

  NONEPAID_TIME_OFFWORKING_TIME_REDUCTION

• accountId#stringalways returned

• campaignId#stringalways returned

• charityId#string

• recurringDonationId#string

• transactionId#string

• donorId#string

• orderPlatformUserId#string

• usageId#string

• parentDonationId#string

• parentVoteId#string

• parentRecurringDonationId#string

• createdAt#string (date-time)always returned

• updatedAt#string (date-time)always returned

Errors

• 400 Bad Request
• Campaign is a DISTRIBUTION one. Only votes can be created

  {
    "statusCode": 400,
    "message": "Campaign is a DISTRIBUTION one. Only votes can be created",
    "error": "Bad Request"
  }

• donor is required for EMAIL campaigns.

  {
    "statusCode": 400,
    "message": "donor is required for EMAIL campaigns.",
    "error": "Bad Request"
  }

• Both donor.email and donor.firstName are required for email campaigns

  {
    "statusCode": 400,
    "message": "Both donor.email and donor.firstName are required for email campaigns",
    "error": "Bad Request"
  }

• donor is required for SLACK campaigns.

  {
    "statusCode": 400,
    "message": "donor is required for SLACK campaigns.",
    "error": "Bad Request"
  }

• Both donor.slackId and donor.firstName are required for slack campaigns

  {
    "statusCode": 400,
    "message": "Both donor.slackId and donor.firstName are required for slack campaigns",
    "error": "Bad Request"
  }

• Donations of an order campaign cannot be created through the API.

  {
    "statusCode": 400,
    "message": "Donations of an order campaign cannot be created through the API.",
    "error": "Bad Request"
  }

• Bad Request

  {
    "message": "Bad Request",
    "code": "INVALID_POSTAL_ADDRESS"
  }

• charityId cannot be set for POSTAL campaigns: the recipient chooses the charity with the card.

  {
    "statusCode": 400,
    "message": "charityId cannot be set for POSTAL campaigns: the recipient chooses the charity with the card.",
    "error": "Bad Request"
  }

• Invalid parentDonationId

  {
    "statusCode": 400,
    "message": "Invalid parentDonationId",
    "error": "Bad Request"
  }

• Insufficient campaign budget.

  {
    "message": "Insufficient campaign budget.",
    "code": "INSUFFICIENT_CAMPAIGN_BUDGET"
  }

• A field is missing, has the wrong type, or is not part of the request schema.

  Every request with a body or query is validated.

  {
    "statusCode": 400,
    "message": [
      "amount must not be less than 1",
      "property foo should not exist"
    ],
    "error": "Bad Request"
  }

• 401 Unauthorized
• Unauthorized

  Missing, expired or invalid access token.

  {
    "statusCode": 401,
    "message": "Unauthorized"
  }

• 402 Payment Required
• Missing payment method

  {
    "message": "Missing payment method",
    "code": "MISSING_PAYMENT_METHOD"
  }

• 403 Forbidden
• Campaign has ended.

  {
    "statusCode": 403,
    "message": "Campaign has ended.",
    "error": "Forbidden"
  }

• Campaign has to be activated first.

  {
    "statusCode": 403,
    "message": "Campaign has to be activated first.",
    "error": "Forbidden"
  }

• Only recurring donations can be created for recurring campaigns.

  {
    "statusCode": 403,
    "message": "Only recurring donations can be created for recurring campaigns.",
    "error": "Forbidden"
  }

• Account not validated

  {
    "statusCode": 403,
    "message": "Account not validated",
    "error": "Forbidden"
  }

• Account closed

  {
    "message": "Account closed",
    "code": "ACCOUNT_CLOSED"
  }

• 409 Conflict
• Unique constraint failed on uniqueExternalId

  {
    "statusCode": 409,
    "message": "Unique constraint failed on uniqueExternalId"
  }