Donation Mode

Accept donations with preset amount buttons and custom input.

Enable Donation Mode

Set checkoutMode to "donation" when creating a session.

Tax Exempt: Donation mode is automatically tax-exempt. No tax will be calculated or charged on donations—this is standard for charitable contributions.

{
  "merchantId": "your_merchant_id",
  "merchantName": "My Charity",
  "successUrl": "https://mycharity.org/thank-you",
  "cancelUrl": "https://mycharity.org/donate",
  "errorUrl": "https://mycharity.org/error",
  "checkoutMode": "donation",
  "donationConfig": {
    "presets": [10, 25, 50, 100],
    "defaultAmount": 25,
    "allowCustomAmount": true
  }
}

Note: You don’t need to specify amount – the donor chooses the amount on the checkout page.

Donation mode cannot be combined with items array. The API will reject requests that include both checkoutMode: "donation" and an items array.

Donation Config Options

Field	Type	Default	Description
`presets`	array	— (UI shows `[5, 15, 25, 50]` if omitted)	Suggested donation amounts (buttons). Alias: `suggestedAmounts`
`defaultAmount`	number	— (first preset if omitted)	Pre-selected amount
`allowCustomAmount`	boolean	`true`	Allow donors to enter custom amount
`minAmount`	number	`1`	Minimum donation amount
`maxAmount`	number	`999999`	Maximum donation amount

Validation:

presets must be within the minAmount-maxAmount range
defaultAmount must be within the minAmount-maxAmount range
Custom input is limited to 9 characters

Styling

Use the same appearance object as standard checkout (colors, fonts, radius, etc.); values apply via shared CSS variables on the page. See Customize Appearance.

What the Donor Sees

Preset buttons for quick selection (e.g., $10, $25, $50, $100)
“Other” option to enter a custom amount (if enabled)
Standard payment form
“Donate” button

Example: Simple Preset

{
  "checkoutMode": "donation",
  "donationConfig": {
    "presets": [5, 10, 25]
  }
}

Donor sees three buttons: $5, $10, $25

Example: Monthly Campaign

{
  "checkoutMode": "donation",
  "donationConfig": {
    "presets": [25, 50, 100, 250],
    "defaultAmount": 50,
    "allowCustomAmount": true
  }
}

Donor sees $25, $50 (pre-selected), $100, $250, and “Other” option.

Example: With Min/Max Limits

{
  "checkoutMode": "donation",
  "donationConfig": {
    "presets": [10, 25, 50, 100],
    "minAmount": 5,
    "maxAmount": 10000,
    "allowCustomAmount": true
  }
}

Donors can enter any custom amount between $5 and $10,000
If they try to enter less than $5, they see: "Donation must be at least $5.00”
If they try to enter more than $10,000, they see: "Donation cannot exceed $10,000.00”

Combine with Payment Links

Create a shareable donation link via POST /api/payment-links/create:

{
  "merchantId": "your_merchant_id",
  "merchantName": "My Charity",
  "successUrl": "https://mycharity.org/thank-you",
  "cancelUrl": "https://mycharity.org/donate", 
  "errorUrl": "https://mycharity.org/error",
  "checkoutMode": "donation",
  "donationConfig": {
    "presets": [10, 25, 50, 100]
  }
}

Share the resulting url on social media, email campaigns, or your website. See Payment Links for full details.

Getting Started

Vault

Payments

Donation Mode

Enable Donation Mode

Donation Config Options

Styling

What the Donor Sees

Example: Simple Preset

Example: Monthly Campaign

Example: With Min/Max Limits

Combine with Payment Links

​Enable Donation Mode

​Donation Config Options

​Styling

​What the Donor Sees

​Example: Simple Preset

​Example: Monthly Campaign

​Example: With Min/Max Limits

​Combine with Payment Links

Enable Donation Mode

Donation Config Options

Styling

What the Donor Sees

Example: Simple Preset

Example: Monthly Campaign

Example: With Min/Max Limits

Combine with Payment Links