# Donation / Tip Page

> Accept crypto donations or tips with a shareable page.

Section: Build with AI
Source: https://coincircuit.io/docs/guides/donation-page/
Interactive version: https://coincircuit.io/api-reference?tab=guides&guide=donation-page

Tags: Payment Pages, Payments, Frontend

Paste this prompt into Claude, ChatGPT, or any AI tool. It works best with the CoinCircuit MCP server connected: https://mcp.coincircuit.io

---

You are helping me add a crypto donation/tip page to my existing site using CoinCircuit. I have the CoinCircuit MCP server connected.

**If you have access to the CoinCircuit MCP server, call these tools for the most accurate and detailed schema outputs:**
- Call `get_endpoint` with method `post` and path `/api/v1/payments/pages` in the CoinCircuit MCP for the full payment page creation schema.
- Call `get_endpoint` with method `post` and path `/api/v1/payments` for the checkout session creation schema (needed for Option B).
- Call `search_api` with feature `Payment Pages` to see all available payment page endpoints (create, update, delete, list).
- Call `get_schema` with name `PaymentCompletedWebhookDto` for the payment.completed webhook payload.

Use the live MCP data as your source of truth. The details below are a guide, but if the MCP returns something different, trust the MCP.

## API Basics

- **Base URL:** `https://api.coincircuit.io`
- **Auth:** `x-api-key` header on every request.

## Project Context

I have a site and I'm adding a public page where supporters can donate any amount in crypto.

## What I Need You to Implement

### Option A: Payment Page (zero backend, simplest approach)

CoinCircuit has hosted payment pages with open-amount input. One API call and you get a shareable URL.

**Endpoint:** `POST /api/v1/payments/pages`
*(Call `get_endpoint` with method `post`, path `/api/v1/payments/pages`, section `request` in the CoinCircuit MCP for the exact request body with all field types and validations.)*

**Required fields:**
- `title` (string, 1-100 chars) - e.g. "Support My Project"
- `isActive` (boolean) - set to `true`
- `currency` (string) - `"NGN"` or `"USD"`

**Optional fields:**
- `description` (string) - displayed on the page
- `minAmount` (number) - minimum donation amount
- `bankAccountIds` (array of strings) - associate bank accounts for fiat settlement

**Example request:**
```json
{
  "title": "Support My Project",
  "description": "Help me keep building open source tools",
  "isActive": true,
  "currency": "USD",
  "minAmount": 1
}
```

**Response (201):** Returns the payment page object:
- `data.reference` - page reference
- `data.url` - the hosted page URL (e.g. `https://checkout.coincircuit.io/static/1234567890`). Share this anywhere.

*(Call `get_endpoint` with method `post`, path `/api/v1/payments/pages`, section `success` in the CoinCircuit MCP for the full response schema.)*

No backend required. Share the URL on social media, your website, or anywhere. Donors enter any amount they choose.

### Option B: Custom branded donation page (full UI control)

For full control over the design:

1. Build a frontend with an open amount input field
2. On "Donate" click, your backend creates a checkout session:

   **Endpoint:** `POST /api/v1/payments`
   *(Call `get_endpoint` with method `post`, path `/api/v1/payments`, section `example` in the CoinCircuit MCP for a sample request.)*

   Required fields: `title`, `description`, `amount` (string), `currency`, `customer` (with at least `email`).

   Store donor info in `metadata`:
   ```json
   {
     "title": "Donation",
     "description": "Donation from Jane",
     "amount": "25.00",
     "currency": "USD",
     "customer": { "email": "jane@example.com" },
     "metadata": {
       "donorName": "Jane",
       "message": "Keep up the great work!"
     },
     "successUrl": "https://mysite.com/thanks"
   }
   ```

3. Open the checkout SDK modal with the session `reference`, or redirect to `data.url`

### Webhook handler

Listen for `payment.completed` to:
- Display the donor on a public wall (read `data.session.metadata.donorName` and `data.session.metadata.message`)
- Update a running donation total (read `data.session.amount` and `data.session.currency`)
- Send a thank-you email (read `data.session.customer.email`)

*(Call `get_schema` with name `PaymentCompletedWebhookDto` in the CoinCircuit MCP for every field available in the webhook payload.)*

### Updating or deleting a payment page

*(Call `search_api` with feature `Payment Pages` in the CoinCircuit MCP to see all available endpoints: create, update, delete, list, and get by reference.)*

- `PUT /api/v1/payments/pages/{reference}` - update title, description, or deactivate the page
- `DELETE /api/v1/payments/pages/{reference}` - delete the page

*(Call `get_endpoint` with method `put`, path `/api/v1/payments/pages/{reference}` in the CoinCircuit MCP for the update request schema.)*

## Constraints

- Payment pages are the zero-code option for basic donation pages
- For custom amounts, validate minimum amount server-side
- Session `amount` is a string in fiat (e.g. `"25.00"`)
- Use `metadata` to store donor info without needing CoinCircuit customer records
- Supported currencies: NGN, USD