Get started with the CharityStack API

This guide walks you through making your first request to the CharityStack API. By the end you will have retrieved a list of live payment records from your merchant account and understand the structure of the response.

Before you begin

You need an active CharityStack merchant account and an API key provisioned by your account administrator. If you do not have a key yet, see Authentication for how keys are issued and what permissions they grant.

Step-by-step

Confirm your API key

Your API key starts with the cs_live_ prefix. It was shown to you exactly once when it was created. If you no longer have it, ask your administrator to provision a new one — issuing a new key automatically revokes the previous one.Store your key in an environment variable so you never have to hard-code it:

export CHARITYSTACK_API_KEY="cs_live_your_key_here"

Make your first request

Call GET /v1/payments to retrieve a list of recent payments from your account. Pass your API key in the Authorization header as a Bearer token:

curl https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/payments \
  -H "Authorization: Bearer $CHARITYSTACK_API_KEY"

The endpoint returns up to 50 results by default. You can request fewer with the limit query parameter (maximum is 100):

curl "https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/payments?limit=10" \
  -H "Authorization: Bearer $CHARITYSTACK_API_KEY"

Interpret the response

A successful response returns a JSON object containing an array of payment records and pagination metadata:

{
  "payments": [
    {
      "paymentID": "pay_a1b2c3d4e5f6",
      "email": "jane.doe@example.org",
      "firstName": "Jane",
      "lastName": "Doe",
      "amount": 100.00,
      "currency": "USD",
      "status": "COMPLETED",
      "fund": "General Fund",
      "form": "Year-End Campaign",
      "frequency": "ONE_TIME",
      "date": "2026-04-15T18:32:00Z",
      "paymentMethod": "card",
      "coverFees": false,
      "anonymous": false
    }
  ],
  "count": 1,
  "hasMore": true,
  "lastEvaluatedKey": "eyJwYXltZW50SUQiOiJwYXlfYTFiMmMzZDRlNWY2In0="
}

Each entry in payments is a payment object. The key fields to understand:

Field	Description
`paymentID`	Unique identifier for this payment
`amount`	Payment amount in US dollars
`status`	`COMPLETED`, `PENDING`, `FAILED`, or `REFUNDED`
`frequency`	`ONE_TIME`, `MONTHLY`, `ANNUALLY`, etc.
`date`	ISO 8601 timestamp of the payment

Paginate through results

When hasMore is true, there are additional records beyond the current page. Pass the lastEvaluatedKey value from the response as a query parameter to fetch the next page:

curl "https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/payments?lastEvaluatedKey=eyJwYXltZW50SUQiOiJwYXlfYTFiMmMzZDRlNWY2In0=" \
  -H "Authorization: Bearer $CHARITYSTACK_API_KEY"

Repeat this until hasMore is false or the key is absent, indicating you have reached the last page.

Check API health

The /health endpoint requires no authentication and confirms the API is operational:

curl https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/health

{
  "status": "healthy"
}

Next steps

Authentication

Understand API key permissions, the Bearer token format, and rate limit headers.

API Reference

Explore all available endpoints for payments, subscriptions, contacts, forms, and more.

If your request returns 401 Unauthorized, verify that your Authorization header is formatted exactly as Bearer cs_live_your_key_here with no extra spaces or characters.

Get Started

Core Concepts

Guides

Get started with the CharityStack API

Before you begin

Step-by-step

Check API health

Next steps

Authentication

API Reference

​Before you begin

​Step-by-step

​Check API health

​Next steps

Authentication

API Reference

Before you begin

Step-by-step

Check API health

Next steps