The Complete Guide to Payment Provider Integration

One of the most powerful features of Holdify is automatic entitlement sync with your payment provider. When a customer subscribes, upgrades, or cancels, their API access updates instantly. No webhooks to maintain, no sync jobs to debug.

Prerequisites

Step 1: Connect Your Payment Provider

Log into your Holdify dashboard and navigate to Settings → Integrations. Click Connect next to Polar. You'll be redirected to authorize the connection.

This grants Holdify read access to your subscriptions and webhook access for real-time updates. Once connected, you'll see a green "Connected" badge.

Step 2: Map Products to Plans

Go to Settings → Plans and create your plan tiers. For each plan, configure:

The product mapping is key. When Holdify sees a subscription to a Polar product, it looks up which plan that product maps to and applies those limits.

Step 3: Issue API Keys

With plans configured, you can start issuing API keys. For most use cases, create keys programmatically when users sign up:

POST /v1/keys
{
  "externalId": "user_123",
  "name": "Production API Key"
}

Holdify will look up the customer's subscription (matching on external ID) and assign the appropriate plan automatically.

Step 4: Verify Keys at Request Time

In your API middleware, call the verify endpoint:

const result = await holdify.verify(apiKey, {
  resource: 'api-calls',
  units: 1,
});

if (!result.valid) {
  return res.status(401).json({ error: 'Invalid API key' });
}

if (result.remaining <= 0) {
  return res.status(429).json({
    error: 'Rate limit exceeded',
    resetAt: result.reset
  });
}

The verify response tells you everything you need:

Step 5: Subscription Changes

Here's where the integration shines. When a customer:

All of this happens automatically through webhooks. You don't need to write any webhook handlers. Holdify receives the events directly from your payment provider.

Next Steps