Create Donation

Create a donation and initiate payment processing.

POST /api/donations

Create Donation

cURL

curl --request POST \
  --url https://api.example.com/api/donations \
  --header 'Content-Type: application/json' \
  --data '
{
  "campaignId": "<string>",
  "amount": 123,
  "currency": "<string>",
  "frequency": "<string>",
  "paymentMethod": "<string>",
  "coverFees": true,
  "donor": {
    "email": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "anonymous": true
  },
  "dedication": {
    "type": "<string>",
    "name": "<string>",
    "message": "<string>",
    "notifyName": "<string>",
    "notifyEmail": "<string>"
  },
  "publicMessage": "<string>",
  "emailOptIn": true,
  "customFieldResponses": [
    {
      "customFieldId": "<string>",
      "value": "<string>"
    }
  ],
  "givingLevelId": "<string>",
  "ticketCount": 123,
  "utmSource": "<string>",
  "utmMedium": "<string>",
  "utmCampaign": "<string>",
  "referrerUrl": "<string>"
}
'

200

{
  "donation": {
    "id": "<string>",
    "amountCents": 123,
    "status": "<string>",
    "frequency": "<string>"
  },
  "clientSecret": "<string>",
  "fees": {
    "donationAmount": 123,
    "processingFee": 123,
    "platformFee": 123,
    "totalCharged": 123,
    "netToOrg": 123
  }
}

Create Donation

Creates a donation record, calculates fees, and returns a Stripe PaymentIntent client secret for completing the payment on the frontend.

The campaign must be in ACTIVE status. The org must have completed Stripe Connect onboarding before donations can be processed.

Request Body

campaignId · string · required

The ID of the campaign to attribute this donation to.

amount · integer · required

Donation amount in cents. Minimum 100 ($1.00). For event campaigns with a fixed ticket price, this is the per-ticket amount multiplied by ticketCount.

currency · string · default: "usd"

Three-letter ISO currency code. Currently only "usd" is supported.

frequency · string · required

Giving frequency. One of: "one_time", "monthly", "quarterly", "annual".

paymentMethod · string · required

Payment method type. One of: "card", "ach", "apple_pay", "google_pay".

coverFees · boolean · required

Whether the donor is covering processing and platform fees. When true, the total charged to the donor is grossed up so the nonprofit receives the full amount.

donor · object · required

Donor contact information.

Show Donor fields

email · string · required

Donor email address. Used for receipt delivery and donor record matching.

firstName · string · required

Donor first name.

lastName · string · required

Donor last name.

anonymous · boolean · default: "false"

When true, the donor’s name is hidden from the public donor roll on the campaign page.

dedication · object

Optional tribute dedication. If provided, type and name are required.

Show Dedication fields

type · string · required

Either "in_honor" or "in_memory".

name · string · required

Name of the person being honored or remembered. Max 200 characters.

message · string

Optional tribute message. Max 500 characters.

notifyName · string

Name of a person to notify about this tribute (e.g., a family member). Max 200 characters.

notifyEmail · string

Email address to send a tribute notification to. A notification email is sent when the donation succeeds.

publicMessage · string

A public message from the donor, shown on the campaign’s donor roll. Max 280 characters.

emailOptIn · boolean · default: "false"

Whether the donor opts in to future email communications from the organization.

customFieldResponses · array

Responses to campaign-specific custom fields.

Show Custom field response object

customFieldId · string · required

The ID of the custom field being answered.

value · string · required

The donor’s response value.

givingLevelId · string

The ID of a pre-configured giving level to associate with this donation. Optional.

ticketCount · integer

For event campaigns with a fixed ticket price, the number of tickets being purchased (1–20). The total amount is derived from ticketCount × campaign.ticketPriceCents.

utmSource · string

UTM source parameter for attribution tracking (e.g., "email", "facebook"). Max 100 characters.

utmMedium · string

UTM medium parameter (e.g., "newsletter", "cpc"). Max 100 characters.

utmCampaign · string

UTM campaign parameter (e.g., "year-end-2026"). Max 100 characters.

referrerUrl · string

The full URL of the referring page. Max 500 characters.

Response

donation · object

The created donation record.

Show Donation fields

id · string

Unique donation ID.

amountCents · integer

Donation amount in cents (the intended gift, before fee adjustment).

status · string

Always "PENDING" on creation. Updated to "SUCCEEDED" or "FAILED" via Stripe webhook.

frequency · string

One of "ONE_TIME", "MONTHLY", "QUARTERLY", "ANNUAL".

clientSecret · string

The Stripe PaymentIntent client secret. Pass this to Stripe Elements or the Stripe.js confirmPayment() method on the frontend to complete payment collection.

fees · object

The calculated fee breakdown for this donation.

Show Fee fields

donationAmount · integer

The intended donation amount in cents.

processingFee · integer

Stripe processing fee in cents (2.2% + $0.30 for cards; 0.8$5 for ACH).

platformFee · integer

GiveLink platform fee in cents (1% of donation; waived for the first $10,000 raised).

totalCharged · integer

Total amount charged to the donor’s card in cents. Equals donationAmount when coverFees is false; grossed up when true.

netToOrg · integer

Amount the nonprofit receives in cents after all fees.

Example

curl -X POST https://givelink-api-production.up.railway.app/api/donations \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "clx9876543210",
    "amount": 5000,
    "currency": "usd",
    "frequency": "monthly",
    "paymentMethod": "card",
    "coverFees": true,
    "donor": {
      "email": "[e-mail]",
      "firstName": "Jane",
      "lastName": "Smith",
      "anonymous": false
    },
    "publicMessage": "Happy to support this cause!",
    "emailOptIn": true,
    "utmSource": "email",
    "utmMedium": "newsletter",
    "utmCampaign": "spring-2026"
  }'

{
  "donation": {
    "id": "clx1111111111",
    "amountCents": 5000,
    "status": "PENDING",
    "frequency": "MONTHLY"
  },
  "clientSecret": "pi_1234_secret_5678",
  "fees": {
    "donationAmount": 5000,
    "processingFee": 142,
    "platformFee": 51,
    "totalCharged": 5193,
    "netToOrg": 5000
  }
}

Use the clientSecret with Stripe Elements on the frontend to collect payment details and confirm the PaymentIntent. The donation status remains PENDING until Stripe confirms payment via webhook.

Error Responses

Status	Error	Description
400	Campaign not found	The campaignId does not exist.
400	Campaign is not active	The campaign must be in ACTIVE status.
400	Minimum donation is $X	The amount is below the campaign’s minimum.
400	Organization has not completed payment setup	Stripe Connect onboarding is incomplete.
400	Sorry, not enough tickets available	Event is sold out or insufficient capacity.
400	Validation failed	One or more fields failed schema validation.