[![Actions Status](https://github.com/librasteve/Air-Plugin-Donate/actions/workflows/test.yml/badge.svg)](https://github.com/librasteve/Air-Plugin-Donate/actions)

# Air::Plugin::Donate

A plugin for the Raku [Air](https://raku.land/zef:librasteve/Air) web framework that renders a donation panel linking to a Stripe-hosted payment page.

## Synopsis

```raku
#!/usr/bin/env raku

use Air::Functional :BASE;
use Air::Base;
use Air::Plugin::Donate;

my $site =
site
    page
        main [
            donate(:key<abc123XYZ>);
        ]
;

$site.serve;
```

## Description

`Air::Plugin::Donate` renders a small Pico-styled donation panel — heading, Stripe wordmark, and a donate link. The link goes straight to a Stripe-hosted [Payment Link](https://stripe.com/payments/payment-links) page at `https://donate.stripe.com/<key>`.

No card data, API calls, or webhooks touch this plugin or your server. Stripe's own hosted page handles the payment, and the Stripe Dashboard handles receipts and reporting. The `:key` is just the public URL slug of your Payment Link — it is not a secret, so it is safe to commit in source (the same convention as the Umami website id in Air's `Analytics` tool).

The panel is fully customizable:

```raku
donate
    :key<abc123XYZ>,
    :heading('Credit Card and others'),
    :label('Donate via Stripe'),
    :methods[
        'Credit Card', 'Klarna', 'Revolut Pay', 'SOFORT', 'Przelewy24',
        'Bancontact', 'MobilePay', 'eps-Überweisung', 'iDEAL',
    ],
    :note('This costs us some fees, but works worldwide in all currencies.');
```

| Attribute | Default | Rendered as |
|-----------|---------|-------------|
| `:key` | *(required)* | `href="https://donate.stripe.com/<key>"` on the link |
| `:heading` | `Support this project` | `<h3>` |
| `:blurb` | *(omitted)* | `<p>` above the link |
| `:logo` | `True` | inline Stripe wordmark SVG above the link text (`:!logo` to disable) |
| `:label` | `Donate` | link text |
| `:methods` | *(omitted)* | **Payment Methods:** `<ul>` below the link |
| `:note` | *(omitted)* | `<p><em>` footnote |

Since the plugin registers no routes, it needs no `site :register[...]` entry — just use `donate(...)` inline anywhere in a page tree.

## Stripe Account Setup

1. Create a free account at [dashboard.stripe.com/register](https://dashboard.stripe.com/register).
2. In the Dashboard, go to **Payment Links → + New**. Configure the donation — a fixed amount, a preset list, or "customer chooses amount" — then create it.
3. Stripe gives you a URL like `https://donate.stripe.com/abc123XYZ` (while your account is unactivated, test mode gives a `https://donate.stripe.com/test/...`-style link). Copy the part after `https://donate.stripe.com/`.
4. Pass that as `:key<...>`, e.g. `donate(:key<abc123XYZ>)`.
5. To go live: complete Stripe's business/tax/bank-account verification under **Settings → Business settings**, switch the Dashboard to **Live mode**, and create a live Payment Link (this is a new key — update your `:key` accordingly).
6. Optional: under **Settings → Emails**, enable "Successful payments" so donors automatically receive an email receipt — no code needed.

## Installation

If you already have [Air](https://raku.land/zef:librasteve/Air) working, then:

 - `zef install Air::Plugin::Donate`

Otherwise, follow the Air::Examples [Getting Started](https://github.com/librasteve/Air-Examples/blob/main/README.md#getting-started)

## Author

librasteve <librasteve@furnival.net>

## Copyright and License

Copyright 2026 Stephen Roe.

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.
