> For the complete documentation index, see [llms.txt](https://developers.coincircuit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.coincircuit.io/promp-library/donation-and-tip-page.md).

# Donation and tip page

Launch hosted or custom donation flows with CoinCircuit.

Use this prompt to create a hosted payment page or a fully custom donation flow.

`Payment Pages` `Payments` `Frontend`

### What this prompt covers

* Create hosted payment pages with open amounts
* Build a custom branded donation experience
* Track donation completion from webhooks

{% code title="donation-tip-page.prompt.md" expandable="true" collapsedlinecount="20" %}

````markdown
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
````

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.coincircuit.io/promp-library/donation-and-tip-page.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.