> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payglue.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Ko-fi

> Connect Ko-fi as a payment provider in PayGlue.

Ko-fi is a fully supported payment provider in PayGlue. When a supporter sends a tip, starts a membership, or buys from your Ko-fi Shop, PayGlue automatically creates or updates the matching Ghost member — no manual webhook registration required.

<Warning>
  Ko-fi's webhook API only tells PayGlue when a membership **starts** — it never sends an event when a membership ends or is cancelled. If a supporter cancels their Ko-fi membership, you have to revoke their Ghost access manually. Ko-fi has stated it plans to expand its webhook events in the future.
</Warning>

## Prerequisites

* A Ko-fi account at [ko-fi.com](https://ko-fi.com)
* A Ghost blog connected in PayGlue ([Connect Ghost](/ghost/connect))

## Steps

<Steps>
  <Step title="Open Ko-fi's Webhooks settings">
    In your Ko-fi account, go to **Settings → Webhooks** (under the API section).

    > \[Screenshot — Ko-fi Settings → Webhooks page]
  </Step>

  <Step title="Copy the Webhook URL from PayGlue">
    In your PayGlue dashboard, go to **Providers** and click **Connect Ko-fi**. Copy the **Webhook URL** shown there.

    > \[Screenshot — PayGlue dashboard: Ko-fi connection page with Webhook URL field and Copy button]
  </Step>

  <Step title="Paste the Webhook URL into Ko-fi">
    Paste the URL into Ko-fi's **Webhook URL** field and save.

    > \[Screenshot — Ko-fi Webhooks settings with the PayGlue webhook URL pasted in]
  </Step>

  <Step title="Copy the Verification Token">
    Ko-fi shows a **Verification Token** on the same page. Copy it into the **Verification Token** field on the PayGlue Ko-fi connection page, then click **Save credentials**.

    > \[Screenshot — PayGlue dashboard: Ko-fi connection page with Verification Token field]

    <Note>
      The verification token is the only credential Ko-fi requires. Ko-fi has no API for PayGlue to call directly — the token is only ever checked passively, when Ko-fi sends a webhook.
    </Note>
  </Step>

  <Step title="Run a health check">
    Click **Run health check** to confirm the verification token is saved. Because Ko-fi has no API endpoint to call, this only confirms PayGlue is configured — it does not confirm delivery. Trigger a test webhook from Ko-fi's dashboard to confirm end-to-end delivery.
  </Step>

  <Step title="Create a mapping">
    Ko-fi has no API to fetch your tiers or shop items, so **Buy Button**, **Paywall**, and **Pricing Table** all use a manual text field instead of a product dropdown:

    * For a membership tier, type the exact tier name as it appears on your Ko-fi page (e.g. `Gold Tier`).
    * For a Shop item, paste the item's share link (**Share → Copy link** on Ko-fi, e.g. `https://ko-fi.com/s/c0e30e5fcf`) — PayGlue extracts the product code automatically and fills the checkout/button URL for you. Ko-fi's webhook never includes the item's name, only this code, so the share link is the only reliable way to identify a specific Shop item.
    * For plain tips, use `kofi-support`.

    Choose which Ghost newsletter to subscribe the supporter to and which welcome email to send, then save.

    From this point on, every Ko-fi tip, membership payment, or shop order triggers automatic Ghost member creation.
  </Step>

  <Step title="Test your setup">
    Use Ko-fi's **Send Test** button on the Webhooks settings page, or make a real test payment. Then open **Analytics → Webhook Events** in your PayGlue dashboard — the event should appear with status **Processed** and the supporter's email should appear as a new member in Ghost Admin.
  </Step>
</Steps>

## Supported events

Ko-fi's API is webhook-only and event-driven — it has no endpoints to fetch products, shop contents, or a supporter's current membership status. Every payment type Ko-fi sends a webhook for represents money actually received, so PayGlue maps all of them to a single "purchase completed" action:

| Ko-fi event type                                                  | PayGlue action                        |
| ----------------------------------------------------------------- | ------------------------------------- |
| `Tip` (also sent as `Donation` by Ko-fi's own "Send Test" button) | Create Ghost member                   |
| `Subscription` (membership payment)                               | Create or confirm active Ghost member |
| `Shop Order`                                                      | Create Ghost member                   |
| `Commission`                                                      | Create Ghost member                   |

There is no Ko-fi event for a cancelled or ended membership — see the warning above.

<Note>
  A `Shop Order` webhook never includes the purchased item's name — only an opaque `direct_link_code` per item (the code at the end of that item's Ko-fi share link). This is why Shop item mappings are keyed on that code rather than a product title; see the mapping step above. A single order can contain several items, and PayGlue grants an entitlement for each one independently.
</Note>

## Troubleshooting

**Connection stays "Not connected" after saving**

A Ko-fi connection requires only a Verification Token. If the status still shows "Not connected — a verification token is required" after saving, re-copy the token from Ko-fi's Webhooks settings page and save again — trailing spaces or a partial copy are the most common cause.

**Health check passes but no events arrive**

The health check only confirms the token is saved, not that Ko-fi is delivering webhooks. Use Ko-fi's **Send Test** button on its Webhooks settings page, then check **Analytics → Webhook Events** in PayGlue.

**Test webhook from Ko-fi's dashboard is not processed**

Ko-fi's "Send Test" button sends the legacy type `Donation` instead of the current `Tip`. PayGlue accepts both — if a test event still fails, check **Analytics → Webhook Events** for the actual error rather than assuming the type is unsupported.

**Ghost member is not created after a payment**

Open the event in **Analytics → Webhook Events** and check the error message. The most common cause is a missing mapping — PayGlue receives the event but takes no action unless there is an active mapping for that Ko-fi product.

**A cancelled Ko-fi member still has Ghost access**

This is expected, not a bug. Ko-fi never sends a membership-ended webhook, so PayGlue cannot detect cancellations automatically. Revoke the Ghost member's access manually in Ghost Admin.

***

## Webhook signature verification

Ko-fi does not sign its webhook payloads with a cryptographic signature. Instead, every payload includes the Verification Token you configured in Ko-fi's dashboard, and PayGlue checks it against the token stored for your account before processing the event. Keep this token private — anyone who has it can send PayGlue fake Ko-fi events for your tenant.