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

# PayPal IPN Relay

> Receive PayPal payment notifications through a private relay in your own Cloudflare account

PayPal tells Komerza about each payment with an **IPN** (Instant Payment Notification). We've moved PayPal notifications to a **private relay in your own Cloudflare account**: PayPal sends every notification to your relay, which checks it came from PayPal and passes it on to Komerza. Komerza sets the relay up for you in a couple of clicks.

* **Your own address** - the relay runs in your Cloudflare account, on your own `workers.dev` address.
* **Only PayPal gets through** - it accepts notifications only from PayPal's IPN servers, and signs everything it passes on with a secret unique to your account.
* **Free** - it runs on Cloudflare's free plan.
* **Hands-off** - Komerza deploys and updates it. You never touch any code.

## Who needs the relay

| Your PayPal setup | Uses the relay | What you do |
| - | - | - |
| PayPal Friends & Family - **IPN** | Yes | Set up the relay, then paste its URL into PayPal. |
| PayPal Business - **Links and Buttons** | Yes | Set up the relay. Nothing to change in PayPal - Links and Buttons stays hidden from checkout until your relay is live. |
| PayPal Friends & Family - **Email Forwarding** | No | Nothing. |
| PayPal Business - **Smart Buttons** | No | Nothing - PayPal's webhooks confirm these payments. |

## Prerequisites

* A **Cloudflare account**. The free plan is enough - [sign up](https://dash.cloudflare.com/sign-up) if you don't have one.
* Permission to approve apps on that account. If you're a member of someone else's Cloudflare account, ask its administrator.

## Set up the relay

<Steps>
  <Step title="Open the IPN relay settings">
    In your dashboard, open **Settings** under **Online Store**, then go to **PayPal** and scroll to **IPN relay**.

    You'll also find the same **Cloudflare relay** card in the Friends & Family setup (at the IPN step), and in **Configure PayPal** when you choose **Links and Buttons**.

    <Note>
      The **PayPal** section only appears in Settings once PayPal Business or Friends & Family is set up.
    </Note>
  </Step>

  <Step title="Click Connect Cloudflare">
    On the **Cloudflare relay** card, click **Connect Cloudflare**. You're taken to Cloudflare to approve Komerza.

    If you start from **Configure PayPal** or the Friends & Family settings, Komerza saves what you've entered there first, so nothing is lost when you leave for Cloudflare.
  </Step>

  <Step title="Approve Komerza on Cloudflare">
    Choose the Cloudflare account the relay should run in, then click **Authorize**.

    Komerza asks for:

    * **Workers Admin** - to create the relay in your account and keep it up to date. Cloudflare only lets apps create a Worker with account-wide Workers access; Komerza only ever touches its own relay Worker, named `ipn-relay-` followed by a short code.
    * **Ongoing access** - so Komerza can update or remove the relay later without asking you to approve it again.
  </Step>

  <Step title="Copy your relay URL">
    You're brought back to Komerza, which deploys the relay and shows **Your PayPal relay is live** with its **IPN URL**.

    * Using **Friends & Family on IPN**? Copy the URL and continue to the next step.
    * Only using **Links and Buttons**? You're done - Links and Buttons is back at checkout. Skip ahead to the last step to test it.

    <Note>
      If your Cloudflare account has never used Workers, it has no `workers.dev` address yet. Komerza creates one for you.
    </Note>
  </Step>

  <Step title="Paste the URL into PayPal (Friends & Family only)">
    1. Open PayPal's [IPN settings](https://www.paypal.com/merchantnotification/ipn/preference/edit).
    2. Paste your relay URL into the **Notification URL** field.
    3. Select **Receive IPN messages (Enabled)**.
    4. Click **Save**.
  </Step>

  <Step title="Test it">
    Make a **\$1 test payment** on your store with the PayPal method you set up. Once the order is marked as paid, the relay card shows when the **Last notification** arrived.
  </Step>
</Steps>

## Moving from the old address

If you set up PayPal IPN before the relay existed, PayPal still sends your notifications to the old Komerza address. Set up your relay, then **replace the old Komerza address in PayPal's [IPN settings](https://www.paypal.com/merchantnotification/ipn/preference/edit) with your relay URL**.

Until you've set up the relay, **Payment Methods** shows a **Move PayPal to your own relay** notice with a **Set up relay** button.

Using **Links and Buttons**? There's nothing to replace in PayPal - Komerza sends your relay's address with each payment - but Links and Buttons stays hidden from checkout until your relay is live.

## Relay status

The badge on the **Cloudflare relay** card tells you where things stand:

| Status | What it means | What to do |
| - | - | - |
| Live | The relay is deployed and ready. | Nothing. |
| Not connected | No Cloudflare account is connected. | Click **Connect Cloudflare**. |
| Not deployed | Cloudflare is connected, but setting up the relay didn't finish. | Click **Deploy**. If it fails again, click **Reconnect** and approve every permission Komerza asks for. |
| Update available | A newer version of the relay is ready. | Click **Update**. The URL stays the same, so nothing changes in PayPal. |
| Access removed | Komerza's access was revoked in Cloudflare. The relay keeps working, but can't be updated. | Click **Reconnect**. |

Below the badge, a live relay also shows its **IPN URL**, the **Last notification** it passed on, which of your PayPal setups use it, and when it was deployed.

## Managing the relay

* **Redeploy** installs the relay again with the same URL and secret. Use it if notifications stop arriving.
* **Disconnect** removes the relay Worker from your Cloudflare account and ends Komerza's access. Notifications sent to the relay after that are refused, so **point PayPal somewhere else first** - for example, switch Friends & Family to Email Forwarding. Links and Buttons is hidden from checkout again.
* You can also **revoke Komerza's access** at any time from your Cloudflare profile, under **Manage OAuth authorizations**. The relay keeps working; click **Reconnect** in Komerza when you want to manage it again.

<Note>
  If Komerza can no longer reach your Cloudflare account when you disconnect, it tells you so. Delete the `ipn-relay-` Worker yourself in Cloudflare under **Workers & Pages**.
</Note>

## Troubleshooting

| Problem | Fix |
| - | - |
| My Cloudflare account doesn't appear when approving Komerza | An administrator of that account may have turned off access for third-party apps. Ask them, or use a Cloudflare account you own. |
| Cloudflare refused the Worker | Komerza needs **Workers Admin** to create the relay. Click **Reconnect** and approve every permission Komerza asks for. |
| Cloudflare would not set up a workers.dev address | Open **Workers & Pages** in your Cloudflare dashboard once so Cloudflare creates your `workers.dev` address, then click **Deploy**. |
| Friends & Family payments aren't being confirmed | Check **Last notification** on the relay card. If it says **None yet**, PayPal isn't sending to the relay - check the **Notification URL** in PayPal's IPN settings and that **Receive IPN messages** is enabled. Also make sure the buyer included the payment note. |
| PayPal Links and Buttons isn't showing at checkout | It stays hidden until your relay is **Live**. Set up the relay, or switch to **Smart Buttons** in **Configure PayPal**. |
| I changed my mind and want to stop using the relay | Switch Friends & Family to **Email Forwarding**, or PayPal Business to **Smart Buttons**, then **Disconnect** the relay. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.