Payments

Connect Lemon Squeezy

Create licenses automatically from Lemon Squeezy orders and subscriptions, with offline certificates.

Lemon Squeezy can issue its own license keys, validated online through its API. Connecting it to Keyrail instead gives you signed certificates verified offline, per-product machine fingerprints, the same SDKs and API as with Paddle, and a single place for all your licenses.

1. Create the integration#

In the dashboard, open Integrations in the sidebar and click Connect provider. Choose Lemon Squeezy, the product, and the Environment (Sandbox (test payments) for test mode, Live for real sales), then Connect. The integration shows its Webhook URL; once you have created the webhook in Lemon Squeezy (step 2), paste the same signing secret in Webhook secret and click Save secret, then map each variant in the Price map (Add price, then Save price map). See the dashboard guide. Or with the vendor API, where you can send the secret right away:

bash

curl https://api.keyrail.tech/v1/integrations \
  -H "Authorization: Bearer $KEYRAIL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "lemonsqueezy",
    "product": "prd_7k2m9q4x1c8d3f6h0j5n",
    "priceMap": { "412345": "pro", "412346": "lifetime" },
    "webhookSecret": "a-long-random-string-you-choose"
  }'

priceMap keys are Lemon Squeezy variant IDs, values are plan codes. The response contains the webhookUrl: https://api.keyrail.tech/v1/webhooks/lemonsqueezy/int_….

2. Add the webhook in Lemon Squeezy#

In Lemon Squeezy, Settings → Webhooks → +:

Callback URL: the webhookUrl.
Signing secret: the same webhookSecret you sent to Keyrail.
Events: order_created, order_refunded, subscription_created, subscription_updated, subscription_payment_success.

3. Test#

Enable test mode in Lemon Squeezy and buy with a test card. The license appears in Licenses, the webhook in Events, and the customer receives the key. Nothing happened? See no license after a payment.

Test-mode events (meta.test_mode: true) are only processed by an integration whose environment is sandbox; a live integration acknowledges them and ignores them (the audit log says test mode event on a live integration), so test orders never create real licenses. Likewise a sandbox integration ignores live events. Create one integration per environment, each with the signing secret of the matching webhook.

What each event does#

Lemon Squeezy event	Effect on the license
`order_created` with a non-subscription variant	A `perpetual` license.
`subscription_created`, `subscription_payment_success`	`paidUntil` = `renews_at`; status `active`.
`subscription_updated`	Status mapped from the subscription status (below).
`order_refunded`	Status `refunded`.

Lemon Squeezy subscription status	License status
`active`, `on_trial`	`active`
`past_due`, `unpaid`	`past_due`
`cancelled`	`canceled`
`expired`	`expired`
`paused`	`suspended`

The customer is matched by email, or created. One customer with one subscription to a plan has one license, reused if they subscribe again later.

Signature verification#

The X-Signature header must be the hex HMAC-SHA256 of the raw request body with your signing secret. Otherwise Keyrail answers 401. See webhooks.

View as Markdown

Need help? See Troubleshooting or write to support@keyrail.tech.