Payment Provider Integrations

Connect Square, Paddle, Lemon Squeezy, or another payment provider to Keymint using server-side webhooks and the REST API.

Keymint can work with payment providers that do not have a native Keymint connector. Your payment provider remains the source of truth for payment state, while Keymint manages customers, license keys, activations, and access.

Is there a native Square integration?

Keymint does not currently document a native Square connector. You can still integrate Square through a small server-side webhook handler that translates verified Square payment or subscription changes into Keymint API calls.

The same pattern works for Paddle, Lemon Squeezy, FastSpring, PayPal, and other providers with signed webhooks. Consult the payment provider's official documentation for its current event names, payload fields, and signature-verification procedure.

Integration architecture

1. Receive the payment provider's webhook on your backend.
2. Verify its signature before trusting the payload.
3. Deduplicate retries using the provider's event ID.
4. Map the buyer and purchased plan to a Keymint customer, product, license policy, and optional expiration date.
5. Call POST /customer and POST /key, or create the key with newCustomer when appropriate.
6. Store the provider's customer, order, or subscription identifier in your own database so later events can find the correct Keymint customer or license.
7. When payment state changes, use Keymint's documented license endpoints to update, block, or unblock access according to your policy.

Keep an admin API key only on your server. Never expose it in a browser, desktop application, mobile application, or payment-provider metadata.

Server-side Keymint request

After verifying and normalizing a successful payment event, your backend can create the customer and license together:

const response = await fetch("https://api.keymint.dev/key", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KEYMINT_ADMIN_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": providerEventId,
  },
  body: JSON.stringify({
    productId: process.env.KEYMINT_PRODUCT_ID,
    maxActivations: "1",
    newCustomer: {
      name: buyerName,
      email: buyerEmail,
    },
    metadata: {
      features: purchasedFeatures,
    },
  }),
});

if (!response.ok) {
  throw new Error(`Keymint request failed with HTTP ${response.status}`);
}

Use a stable, unique idempotency key derived from the verified provider event so webhook retries do not repeat the mutation. Do not use an order ID if the provider can legitimately send several different lifecycle events for the same order.

Lifecycle mapping

Define the policy explicitly in your backend rather than assuming every billing event should immediately revoke access.

Provider behavior differs, so treat this table as an integration design pattern—not a claim about any provider's events.

Reliability checklist

• Verify the payment provider's webhook signature against the raw request body.
• Return a successful webhook response only after the event is durably recorded.
• Process duplicate and out-of-order events safely.
• Keep payment-provider IDs mapped to Keymint customer and license IDs in your database.
• Use Keymint idempotency keys for retryable mutations.
• Log identifiers and outcomes, but never log raw Keymint API keys or license keys.
• Reconcile active subscriptions periodically in case a webhook is missed.

For Keymint request shapes and authentication, see API Authentication, Create Customer, and Create Key. For Keymint-to-your-app notifications, see Webhooks & Events.