latestOpenAPI 3.0.02026-08-1535120202.6 KB

f59881dadecd

Donations

Create a donation

This request allows you to create either a one-time donation or a recurring plan.

To create a recurring plan, you must include a recurring_plan object with the frequency parameter. If the object is not provided, a one-time donation will be created.

All fields and values must meet the requirements of your campaign. Otherwise, an error will be returned.

We do not format or verify addresses and emails that were sent through the API.

<p class="callout callout--warning">A Stripe payment method ID is required. For more details on how to create a payment method, refer to the <a href="https://docs.stripe.com/api/payment_methods" target="_blank">Stripe Payment Methods documentation</a>.</p>

Prerequisites

Make sure you have:

A Stripe account that is connected to your Fundraise Up account and activated.
An active campaign with a money-based payment method.
An API key with permission to create new donations.
Access to the Stripe API for the same Stripe account used as the Fundraise Up payment method, with the ability to create Payment Methods.

Nonprofit organizations must meet PCI compliance requirements to ensure the secure processing of payment card data. Fundraise Up complies with these standards, but if an organization or its vendor uses direct API integration with Stripe to send raw card data (such as card numbers, expiration dates, and CVV codes), that organization or vendor is responsible for meeting broader PCI DSS requirements, such as SAQ D for merchants or higher.

When using Stripe Elements, organizations remain responsible for PCI compliance, but the scope is reduced, typically to SAQ A, due to Stripe handling sensitive card data processing. If a third-party vendor manages card details (for example, in face-to-face or direct mail solutions), they must maintain their own PCI compliance (SAQ D or applicable), and the organization should document them as their third-party service provider.

post/v1/donations

Request body

amountstring required

Donation amount in the selected currency. Must be a decimal string in the format {NNN}[.nn]. Examples: 9.99 (for USD), 200 (for JPY).

The amount must be greater than $1 or its equivalent in other currencies. If a minimum amount is set for the campaign, the donation must meet or exceed that value.

campaignstring required

Campaign ID. Must belong to the account that owns the API key, otherwise an error will occur. Must be active and accept money-based donations, otherwise an error will occur.

currency'shp' | 'eur' | 'aed' | 'afn' | 'xcd' | 'all' | 'amd' | 'aoa' | 'ars' | 'usd' | 'aud' | 'ang' | 'xcg' | 'awg' | 'azn' | 'bam' | 'bbd' | 'inr' | 'pkr' | 'bdt' | 'xof' | 'bhd' | 'bif' | 'bmd' | 'myr' | 'bnd' | 'bob' | 'brl' | 'bsd' | 'btn' | 'nok' | 'zar' | 'bwp' | 'byn' | 'bzd' | 'cad' | 'cdf' | 'xaf' | 'chf' | 'nzd' | 'clp' | 'cny' | 'cop' | 'crc' | 'cve' | 'czk' | 'djf' | 'dkk' | 'dop' | 'dzd' | 'egp' | 'mad' | 'etb' | 'fjd' | 'fkp' | 'jpy' | 'gbp' | 'gel' | 'ghs' | 'gip' | 'gmd' | 'gnf' | 'gtq' | 'gyd' | 'hkd' | 'hnl' | 'htg' | 'huf' | 'idr' | 'ils' | 'isk' | 'jmd' | 'jod' | 'kes' | 'kgs' | 'khr' | 'kmf' | 'krw' | 'kwd' | 'kyd' | 'kzt' | 'lak' | 'lbp' | 'lkr' | 'lrd' | 'lsl' | 'mdl' | 'mga' | 'mkd' | 'mmk' | 'mnt' | 'mop' | 'mur' | 'mvr' | 'mwk' | 'mxn' | 'mzn' | 'nad' | 'xpf' | 'ngn' | 'nio' | 'sek' | 'npr' | 'omr' | 'pab' | 'pen' | 'pgk' | 'php' | 'pln' | 'pyg' | 'qar' | 'ron' | 'rsd' | 'rub' | 'rwf' | 'sar' | 'sbd' | 'scr' | 'sgd' | 'sle' | 'sos' | 'srd' | 'szl' | 'thb' | 'tjs' | 'tnd' | 'top' | 'try' | 'ttd' | 'twd' | 'tzs' | 'uah' | 'uyu' | 'uzs' | 'vnd' | 'vuv' | 'wst' | 'yer' | 'zmw' required

Three-letter ISO currency code, in lowercase.

designationstring required

The ID of the fund, program, or initiative the donation goes to. You can use the ID of any designation created in your account, whether or not it is linked to a campaign. Only one designation can be set for a single donation. To create multiple donations with different designations, make separate API calls. You can find the ID in the Designations section of the Dashboard.

commentstring nullable

Optional comment, maximum 256 characters.

fee_amountstring

Optional amount of fees covered by the supporter. Must be a positive decimal string in the format {NNN}[.nn]. Use GET /v1/donations/fee to retrieve the calculated fee to pass here.

livemodeboolean

Specifies whether the request is executed in live or test mode. Required for API keys created after 30th January 2026.

skip_thank_you_emailboolean

false (default) will send a donation receipt email for the first installment.

true will prevent the donation receipt email from being sent for the first installment.

Available for recurring plans only.

To use this parameter, you must also include the email parameter.

Sending this parameter for a one-time donation will return an error.

Example request

{
  "amount": "99.99",
  "campaign": "FUNXXXXXXXX",
  "currency": "usd",
  "designation": "EXXXXXXX",
  "payment_method": {
    "stripe": {
      "id": "pm_card_visa",
      "setup_intent_id": "seti_1OsI2pHUtU5Pnu8bXXXXXXXX"
    }
  },
  "supporter": {
    "first_name": "Alex",
    "last_name": "Garcia",
    "address": {
      "city": "Nashville",
      "line1": "123 Main St",
      "postal_code": "111111",
      "country": "us",
      "line2": "Apt 1",
      "region": "TN"
    },
    "email": "example@example.com",
    "employer": {
      "name": "Fundraise Up Inc."
    },
    "employment_status": "employed",
    "occupation": "Software Engineer",
    "phone": "+1 (111) 111-1111",
    "title": "mr"
  },
  "custom_fields": [
    {
      "name": "Field1",
      "value": "Value1"
    }
  ],
  "fee_amount": "5.00",
  "livemode": true,
  "questions": [
    {
      "id": "QXXXXXXX",
      "checked": true,
      "date": "1990-05-15",
      "options": [
        "Option 1",
        "Option 2"
      ],
      "text": "Example answer"
    }
  ],
  "recurring_plan": {
    "frequency": "monthly"
  }
}

Response

On success, the API returns the donation object. If the parameters are invalid, the call will return an error.

amountstring required

Donation amount in the transaction currency.

amount_before_fees_coveredstring required

Amount before fees were covered by supporter.

amount_before_fees_covered_in_default_currencystring required

Donation amount before any fees were covered by the supporter. Displayed in the organization's default currency at the time of donation.

amount_in_default_currencystring required

Donation amount converted to the organization's default currency.

anonymousboolean required

Indicates if the donation was made anonymously (true) or not (false).

commentstring nullable required

Optional comment provided by the supporter at the time of donation.

created_atstring required

Timestamp in ISO 8601 format, indicating when the donation was created in UTC.

currency'shp' | 'eur' | 'aed' | 'afn' | 'xcd' | 'all' | 'amd' | 'aoa' | 'ars' | 'usd' | 'aud' | 'ang' | 'xcg' | 'awg' | 'azn' | 'bam' | 'bbd' | 'inr' | 'pkr' | 'bdt' | 'xof' | 'bgn' | 'bhd' | 'bif' | 'bmd' | 'myr' | 'bnd' | 'bob' | 'brl' | 'bsd' | 'btn' | 'nok' | 'zar' | 'bwp' | 'byn' | 'bzd' | 'cad' | 'cdf' | 'xaf' | 'chf' | 'nzd' | 'clp' | 'cny' | 'cop' | 'crc' | 'cve' | 'czk' | 'djf' | 'dkk' | 'dop' | 'dzd' | 'egp' | 'mad' | 'etb' | 'fjd' | 'fkp' | 'jpy' | 'gbp' | 'gel' | 'ghs' | 'gip' | 'gmd' | 'gnf' | 'gtq' | 'gyd' | 'hkd' | 'hnl' | 'hrk' | 'htg' | 'huf' | 'idr' | 'ils' | 'isk' | 'jmd' | 'jod' | 'kes' | 'kgs' | 'khr' | 'kmf' | 'krw' | 'kwd' | 'kyd' | 'kzt' | 'lak' | 'lbp' | 'lkr' | 'lrd' | 'lsl' | 'mdl' | 'mga' | 'mkd' | 'mmk' | 'mnt' | 'mop' | 'mro' | 'mur' | 'mvr' | 'mwk' | 'mxn' | 'mzn' | 'nad' | 'xpf' | 'ngn' | 'nio' | 'sek' | 'npr' | 'omr' | 'pab' | 'pen' | 'pgk' | 'php' | 'pln' | 'pyg' | 'qar' | 'ron' | 'rsd' | 'rub' | 'rwf' | 'sar' | 'sbd' | 'scr' | 'sgd' | 'sll' | 'sle' | 'sos' | 'srd' | 'std' | 'svc' | 'szl' | 'thb' | 'tjs' | 'tnd' | 'top' | 'try' | 'ttd' | 'twd' | 'tzs' | 'uah' | 'uyu' | 'uzs' | 'vnd' | 'vuv' | 'wst' | 'yer' | 'zmw' | 'btc' | 'eth' | 'usdt' | 'usdc' | 'sol' | 'dot' | 'doge' | 'shib' | 'ltc' | 'bch' | 'xtz' | 'fil' | 'ftm' | 'gala' | 'paxg' | 'zec' required

Three-letter ISO currency code, in lowercase.

failed_atstring nullable required

Timestamp in ISO 8601 format, indicating when the donation failed in UTC.

idstring required

Unique identifier for the donation.

installmentstring nullable required

Indicates the installment number for recurring donations. Returns null for one-time donations.

livemodeboolean required

Test mode indicator. true for live mode donations, false for test mode donations.

on_behalf_ofstring nullable required

Name of the organization the donation was made on behalf of.

receipt_idstring nullable required

Unique identifier for the donation receipt.

refunded_atstring nullable required

Timestamp in ISO 8601 format, indicating when the donation was refunded in UTC.

Indicates the source of the donation.

source_of_funds'own_money' | 'on_behalf_of' | 'fundraising_or_collection' nullable required

Indicates the source of funds for the donation in the context of Gift Aid eligibility.

Current status of the donation.

succeeded_atstring nullable required

Timestamp in ISO 8601 format, indicating when the donation succeeded in UTC.

supporter_covered_feestring required

Amount of fees covered by the supporter.

supporter_covered_fee_in_default_currencystring required

Amount of fees covered by the supporter and converted to the organization's default currency.

urlstring nullable required

URL from which the donation was made.

one_time_to_recurring_upgrade_linkstring nullable

A permanent, pre-authenticated link that the supporter can use to upgrade this donation to a recurring plan. Returned only when the request includes include=upgrade_link and the donation is eligible.

Example response

{
  "account": {
    "code": "Code-1",
    "id": "AXXXXXXX",
    "name": "Example Account"
  },
  "amount": "99.99",
  "amount_before_fees_covered": "99.99",
  "amount_before_fees_covered_in_default_currency": "59.99",
  "amount_in_default_currency": "59.99",
  "benefit": {
    "code": "TSHIRT-001",
    "fair_market_value": "25.99",
    "fair_market_value_currency": "usd",
    "id": "GXXXXXXX",
    "name": "T-shirt",
    "option": {
      "code": "SIZE-M",
      "name": "Size",
      "value": "M"
    },
    "shipping": {
      "address": {
        "city": "Nashville",
        "country": "us",
        "line1": "123 Example St.",
        "line2": "Apt. 1",
        "postal_code": "111111",
        "region": "Tennessee"
      },
      "recipient_first_name": "Alex",
      "recipient_last_name": "Garcia"
    }
  },
  "campaign": {
    "code": "Code-1",
    "id": "FUNXXXXXXXX",
    "name": "My Campaign"
  },
  "comment": "Comment example.",
  "consent": {
    "customized": {
      "email": "opted_in",
      "phone_calls": "opted_out",
      "postal_mail": "opted_in",
      "sms": "opted_in",
      "social_media": "opted_out"
    },
    "general": "opted_in"
  },
  "created_at": "2024-12-20T00:00:00.000Z",
  "currency": "usd",
  "custom_fields": [
    {
      "name": "Field1",
      "value": "Value1"
    }
  ],
  "designation": {
    "code": "Code-1",
    "id": "EXXXXXXX",
    "name": "My Designation"
  },
  "device": {
    "browser": "Chrome",
    "ip": {
      "address": "111.111.111.111",
      "city": "Nashville",
      "country_name": "United States",
      "region": "Tennessee"
    },
    "os": "MacOS",
    "type": "desktop",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
  },
  "element": {
    "id": "XXXXXXXX",
    "name": "My Element",
    "type": "donationForm"
  },
  "failed_at": "2024-12-20T00:00:00.000Z",
  "fundraiser": {
    "id": "NXXXXXXX",
    "name": "Run for hope"
  },
  "gift_aid": {
    "claimed": true,
    "legal_text": "I am a UK taxpayer and want to claim Gift Aid."
  },
  "id": "DXXXXXXX",
  "installment": "3",
  "livemode": true,
  "on_behalf_of": "Example Inc.",
  "payment": {
    "bank_account": {
      "last4": "1234"
    },
    "credit_card": {
      "exp_month": "12",
      "exp_year": "2023",
      "last4": "1234",
      "type": "Visa"
    },
    "daf_external_id": "010c5aa7-28f5-426f-b31f-9ba77754055f",
    "daf_sponsor_fund": "Fidelity Charitable",
    "daf_tracking_id": "1e60800e-849b-43d1-870e-57afc8d75473",
    "email": "example@example.com",
    "error_message": "Something went wrong",
    "id": "ch_1I9nHHHUtU5Pnu8b93DuxyzE",
    "method": "paypal",
    "processor": "stripe"
  },
  "payout": {
    "amount": "99.99",
    "amount_in_default_currency": "59.99",
    "currency": "usd"
  },
  "platform_fee": {
    "amount": "99.99",
    "amount_in_default_currency": "59.99",
    "currency": "usd"
  },
  "processing_fee": {
    "amount": "99.99",
    "amount_in_default_currency": "59.99",
    "currency": "usd"
  },
  "questions": [
    {
      "code": "Code-1",
      "id": "QXXXXXXX",
      "checked": true,
      "options": [
        "OK",
        "Good"
      ],
      "text": "Example answer"
    }
  ],
  "recurring_plan": {
    "created_at": "2024-12-20T00:00:00.000Z",
    "ended_at": "2024-12-20T00:00:00.000Z",
    "frequency": "monthly",
    "id": "RXXXXXXX",
    "next_installment_at": "2024-12-20T00:00:00.000Z",
    "status": "active"
  },
  "refunded_at": "2024-12-20T00:00:00.000Z",
  "source": "website",
  "status": "succeeded",
  "succeeded_at": "2024-12-20T00:00:00.000Z",
  "supporter": {
    "address": {
      "city": "Nashville",
      "country": "us",
      "line1": "123 Example St.",
      "line2": "Apt. 1",
      "postal_code": "111111",
      "region": "Tennessee"
    },
    "email": "example@example.com",
    "employer": {
      "name": "Fundraise Up Inc."
    },
    "employment_status": "employed",
    "first_name": "Alex",
    "id": "SXXXXXXXX",
    "language": "en-CA",
    "last_name": "Garcia",
    "occupation": "Software Engineer",
    "phone": "+1 (111) 111111",
    "title": "mr"
  },
  "supporter_covered_fee": "99.9",
  "supporter_covered_fee_in_default_currency": "99.9",
  "tribute": {
    "honoree": "Zhang Wei",
    "id": "TXXXXXXX",
    "sharing": {
      "from": "Alex Garcia",
      "message": "In loving memory of Jordan",
      "recipient": {
        "address": {
          "city": "Nashville",
          "country": "us",
          "line1": "123 Example St.",
          "line2": "Apt. 1",
          "postal_code": "111111",
          "region": "Tennessee"
        },
        "email": "example@example.com",
        "first_name": "Sidney",
        "last_name": "Jones",
        "title": "mr"
      },
      "type": "email"
    },
    "type": "in_honor"
  },
  "url": "https://example.com/DXXXXXXX",
  "utm": {
    "campaign": "giving_tuesday",
    "content": "textlink",
    "medium": "email",
    "source": "google",
    "term": "how_to_support_penguins"
  }
}