Docs

Integrating with an AI agent

Point your coding agent at this page (or paste the spec below into its context) before it wires up ReliPay. These are the rules agents get wrong on the first try — the model is operator-configured, so an agent that assumes the wrong shape hits dead ends.

Copy this into your agent

The full ruleset, plain text — paste it into your agent's system prompt or a CLAUDE.md / rules file.

# ReliPay integration rules (for AI agents)

## Keys & SDKs
- @relipay/node = server SDK, uses the SECRET key (rp_live_… / rp_test_…). Server-to-server ONLY.
- @relipay/react = browser SDK, uses the PUBLIC key (rp_pub_…). Safe in the browser.
- NEVER ship the secret key to the browser. The browser reads entitlements via YOUR server (which calls @relipay/node), never directly.

## Read the Application's config before billing
- Call applications.me() (GET /api/v1/me/, secret key). It returns authConfig.organizationsEnabled and billingConfig.billingSubject.
- billingSubject is OPERATOR-configured, not a user choice. Branch on it:

### billingSubject = "user" (default)
- Checkout/subscriptions are per end-user. Pass the user's access token; no organizationId needed.

### billingSubject = "org"
- An individual CANNOT hold a subscription. Checkout MUST target an organization the user OWNS or ADMINS.
- Create or switch to a team first: organizations.create() then organizations.switch() (the switch returns a NEW token pair carrying the active org — store both), OR pass organizationId explicitly to createCheckout.
- Omitting the org → RelipayError code "BILLING_ORGANIZATION_REQUIRED". Surface it; don't retry without an org.

### organizationsEnabled = false
- Org routes are off. Don't call organizations.* — they return "ORGANIZATIONS_NOT_ENABLED".

## Entitlements are resolved SERVER-SIDE
- Gate features on billing.getEntitlements(accessToken, { organizationId? }) (secret key, your server). Returns { features, entitlements, creditBalance }.
- Don't infer plan state client-side; read entitlements.features.

## Provider webhooks need a SEPARATE registration step
- Setting billing-credentials does NOT register the provider webhook. Register it explicitly (operator action) AFTER saving credentials.
- Until registered, BILLING.SUBSCRIPTION.ACTIVATED never arrives and subscriptions stay PENDING. A subscription approved BEFORE registration stays orphaned — re-run checkout.

## Errors
- Every error is { code, message, fix }. Read fix — it tells you the exact correction.

## Usage & credits
- Server-to-server (secret key). Subject is { endUserId } OR { organizationId } — match the billingSubject. Org usage and personal usage are metered separately.

See also the API reference and the SDK reference.