ImpactAPI Documentation
    • Introduction
    • Quick Start
    • Authentication
    • Donation Sessions
    • Error Handling
    • Pagination
    • Metadata
    • Endpoints
    • Customers
    • Donation Intents
    • Donation Sessions
    • Vendors
    • Campaigns
API Version: v1.0
Back to dashboard
ImpactAPI Documentation

Understanding Donation Sessions

Learn how donation sessions work, the different types, and how to implement them effectively.

What are Donation Sessions?

Donation sessions are temporary containers that manage the donation allocation process. They have a customizable expiration (15 minutes to 24 hours, default 24 hours) and can be either interactive (customer chooses campaign) or non-interactive (pre-allocated donations).

Key Characteristics
  • Sessions expire after a customizable time (15 min to 24 hours, default 24 hours)
  • Sessions can be interactive or non-interactive
  • Interactive sessions return a session_secret for client-side use
  • Non-interactive sessions require API key authentication for allocation

Session Types

There are three types of donation sessions, each serving different use cases:

add_onInteractive
Customer chooses campaign for an add-on donation at checkout

Use this type when you want to give customers the option to add a donation to their purchase. The customer selects which campaign to support.

Example: "Would you like to add $1 to support environmental causes?"

portion_of_sales_choiceInteractive
Customer chooses which campaign receives a portion of their purchase

Use this type when you're committing a portion of the sale to charity and want the customer to choose which campaign to support.

Example: "We're donating 2% of this purchase. Which cause would you like to support?"

portion_of_salesNon-interactive
Pre-allocated donations with no user interaction required

Use this type when you want to automatically split donations across multiple campaigns without customer input.

Example: "1% of this purchase will be split equally between environmental and educational causes."

Interactive vs Non-Interactive Sessions

Interactive Sessions
add_on, portion_of_sales_choice
Returns session_secret
Customer chooses campaign
Requires available_campaigns
Uses /choose_campaign endpoint
Non-Interactive Sessions
portion_of_sales
No session_secret
Pre-allocated by merchant
Uses allocations array
Uses /allocations endpoint

Session Lifecycle

Understanding the session lifecycle helps you implement the donation flow correctly:

Interactive Session Flow
1

Create Session

POST /sessions with type: "add_on" or "portion_of_sales_choice"

2

Customer Chooses Campaign

POST /sessions/:id/choose-campaign using session_secret

3

Process Session (Optional)

POST /sessions/:id/process to lock customer interactions during payment processing

4

Confirm Session

POST /sessions/:id/confirm to convert to donation intents

Non-Interactive Session Flow
1

Create Session

POST /sessions with type: "portion_of_sales"

2

Save Allocations

PUT /sessions/:id/allocations with campaign splits

3

Confirm Session

POST /sessions/:id/confirm to convert to donation intents

Session Status Values
Sessions track their state through a status field
active

The session has been created and is ready for campaign selection (interactive) or allocations (non-interactive). Sessions remain active until they are confirmed or expire.

processing

The session is being processed for payment. Customer interactions are locked, but the session remains modifiable via API key authentication. The session can still be confirmed or allowed to expire.

confirmed

The session has been confirmed and converted into donation intents. Once confirmed, sessions cannot be modified. Attempting to confirm again is idempotent and returns the same result.

expired

The session has passed its expiration time without being confirmed. Expired sessions cannot be confirmed and will return a 410 Gone error. The session remains readable for audit purposes.

Status Permissions
Authentication and modification permissions by session status
StatusCustomer AuthAPI Key AuthModifiable
active
processing
confirmedmetadata only
expired

Session Secret Security

Safe for Client-Side Use

The session_secret returned for interactive sessions is safe to expose in client-side code (e.g., browser JavaScript). It has limited permissions:

  • Only grants permission to choose a campaign for that specific session
  • Cannot be used for other API operations
  • Automatically expires with the session
  • Cannot access other sessions or organization data

Note: Never expose your API key client-side. Only the session_secret is safe for browser use.

Session Expiration

Customizable Expiration Window

By default, sessions expire 24 hours after creation. You can customize this using the expires_in parameter when creating a session (15 minutes to 24 hours). The expires_at timestamp indicates when the session will expire.

expires_in: 15 to 1440 minutes (default: 1440 / 24 hours)
The /process endpoint can extend expiration by up to 30 days (43200 minutes)
Sessions can be confirmed multiple times (idempotent operation)
Attempting to use an expired session returns a 410 Gone error
Create a new session if the previous one expired

Best Practices

Session Management
  • Create sessions as close to the transaction time as possible
  • Store the session ID with your order/transaction record
  • Confirm sessions only after payment is successful
  • Allow customers to opt-out of interactive sessions
Error Handling
  • Check expires_at before using a session
  • Handle 410 Gone errors by creating a new session
  • Validate campaign identifiers before creating sessions
  • Use the metadata field to store order/transaction references
Payment Processing
  • Call /process when the customer clicks "Place Order" before capturing payment
  • This prevents the customer from modifying their campaign selection during checkout
  • The /process endpoint extends expiration to allow time for payment processing
  • Remember to call /confirm after successful payment capture

Next Steps

Explore Session Endpoints

Check out the detailed API reference for session endpoints with code examples.

Session Endpoints →
View Available Campaigns

See all available campaigns and their identifiers for use in sessions.

Available Campaigns →