Payment Gateway
The Payment Gateway is the single surface kuploy-cloud uses to accept payments. It rolls mobile money (Orange Money, MTN MoMo, KULU), cards (Visa / Mastercard / Amex via Stripe), and Apple/Google Pay / Link under one configuration. Available on the Business plan and above.
The Payment Gateway feature covers both:
- How your organizations pay you for their instance subscriptions. Every rail — Stripe card checkout and mobile money alike — flows through the same gateway.
- A composable "Payment Gateway" service your organizations can add to their projects so their own apps can accept payments.
Platform billing from you to kuploy.app stays on Stripe (direct, not through the gateway) and is not affected.
Since this release, kuploy-cloud no longer manages Stripe keys directly. Your Stripe secret key and webhook signing secret live on a Provider record inside your epay-gateway deployment, not in kuploy-cloud's /admin/stripe page. That page is kept for transitional tenants and will be retired.
Before you start
- Your tenant subscription must be on the Business plan or higher at kuploy.app. Lower plans don't see the Payment Gateway admin pages or the service type.
- Decide which operating mode fits you — managed (zero-config, platform-hosted) or BYO (bring your own epay-gateway deployment for data sovereignty). Details below.
The full merchant + admin epay-gateway reference — architecture, provider plugins, management API, subscription engine, DevOps — lives at docs.epay-gateway.com. Both modes route through the same gateway surface; only who operates it changes.
Funds settle into the mobile-money / card accounts registered inside the gateway's provider plugins. kuploy-cloud never holds funds — it only orchestrates the checkout and listens for payment events.
Two modes
You pick managed or BYO from a single toggle in Admin → Payment Gateway. Swap any time.
| Managed | BYO | |
|---|---|---|
| Who runs the gateway | Platform (us) | You |
| Credentials | Provisioned automatically via license sync | You paste them into the admin UI |
| Webhook wiring | Automatic | Automatic (on save) |
| Data sovereignty | Shared infrastructure | Fully on your side |
| Typical fit | Most tenants | Compliance / regulated industries |
Managed is the default for new Business+ tenants. BYO is an opt-out when you need payment credentials to live on your own infrastructure.
Step 1 — Pick a mode in the admin UI
- Sign in to your kuploy-cloud dashboard as a platform admin.
- Open Admin → Payment Gateway.
- At the top you'll see a Mode card. Enable managed mode or leave it off for BYO — one click either way.
Managed mode
Click Enable managed. On the next license sync (under a minute), the platform provisions a merchant on the shared gateway on your behalf and your admin page switches to a read-only view labelled "Connected via managed-mode (license sync)". Nothing else to set up.
To turn it off later: Disable managed. The managed credentials clear on the next sync; your tenant's active org-facing payment services stay live during a brief grace period, then are torn down.
BYO mode
Leave the Mode card in its default (managed disabled) state. The credential form below the card becomes active. Fill in:
- Gateway URL — the public URL of your epay-gateway deployment (e.g.
https://pay.yourcompany.com). - Merchant Code — the tenant merchant identifier from the gateway's admin console.
- Admin API Key — a DB-backed API key minted on your gateway (see docs.epay-gateway.com/admin/api-keys).
- Merchant Key — the HMAC secret used to sign webhooks.
Click Save Configuration. kuploy-cloud validates connectivity before persisting; bad URL or revoked key fails loudly. All secrets are stored encrypted.
You don't configure the webhook URL anywhere. On save (BYO) or first provision (managed), kuploy-cloud tells your gateway where to deliver events — the URL derives from your cloud's APP_URL and updates automatically if you change domains. The admin page shows the current value for audit.
Step 2 — Stripe webhooks (BYO only)
In managed mode this step is handled for you. In BYO mode, point your Stripe Dashboard webhook endpoint at your gateway, not at kuploy-cloud:
https://<your-gateway-host>/api/webhooks/stripe/<merchantCode>
The gateway verifies Stripe's signature, normalises the event, and relays it to kuploy-cloud. See the epay-gateway Stripe integration docs for the setup details.
What events land on your cloud
kuploy-cloud processes these events (same set both modes):
| Event | What kuploy-cloud does |
|---|---|
customer.subscription.created / updated | Upserts the org's subscription and syncs cluster quotas. |
customer.subscription.deleted | Cancels the subscription and falls back to your default plan. |
invoice.payment_succeeded | Clears a past-due status if the org was in dunning. |
invoice.payment_failed | Marks the org past-due so your dunning rules kick in. |
epay-gateway emits Stripe-shaped event payloads so the same downstream code paths handle both sources. The metadata.externalReference field ties each event back to the org inside your kuploy-cloud instance.
Step 3 — What your orgs see at checkout
Once either mode is live, your organizations get a Payment method picker on /account/billing. The list is driven by whatever payment rails your gateway has enabled — cards via Stripe, mobile money, anything the gateway supports — so new providers appear automatically as your platform adds them. No provider names are hard-coded anywhere in the cloud UI.
When an org confirms a plan change, their browser posts to the gateway's checkout counter. The counter renders the provider's native flow (Stripe's hosted Checkout, the mobile-money carrier's OTP page, etc.), the customer pays, the gateway fires a subscription event back to your cloud, and the org's plan flips to active.
See the developer guide for the composable Payment Gateway service for the end-to-end picture your org's developers get.
The composable "Payment Gateway" service
Your organizations can add a Payment Gateway service to their projects, the same way they add Applications, Databases, or Compose services. See the Payment Gateway developer guide for the end-user flow.
Each organization that uses the service gets its own merchant — separate payouts and reconciliation per org, so one org's revenue is never collapsed onto another's (or onto your own subscription merchant). The platform provisions and maintains these org merchants for you; you don't act per org.
Payment events for an org's merchant are delivered to your kuploy-cloud instance, signature-checked against that org's own key, and relayed on to the webhook URL the org configured in its service settings.
The per-org composable service is managed-mode only. In BYO mode you run a single merchant on your own gateway, which can't issue separate per-org payouts — so the "Payment Gateway" service type is unavailable to your orgs until you switch to managed. (Your own org→you subscription billing still works in both modes.)
Status & monitoring
Both kuploy.app and your kuploy-cloud dashboard expose a Payment Gateway row on their /status page:
- kuploy.app/status tracks the shared epay-gateway singleton. If it turns red, checkout is impaired for every Business+ tenant — not just yours.
- Your kuploy-cloud
/statusprobes the same gateway using your own merchant connection. It shows green only when your license grants Payment Gateway and your admin config passes a live connectivity check. Free/Pro tenants and tenants who haven't finished setup don't see the row at all.
Read the two together: if kuploy.app says the gateway is up but your own page says it's down, the problem is your configuration (wrong URL, revoked key) — start at Admin → Payment Gateway → Test Connection.
Switching, rotating, tearing down
- Switch managed ↔ BYO: flip the Mode card toggle. On switching to BYO, fill in your own gateway credentials. On switching to managed, wait one sync cycle for the platform to provision.
- Rotate BYO credentials: enter the new values and click Save. The old values are replaced atomically.
- Disable entirely: turn managed off and click Reset on the BYO form. The Payment Gateway UI disappears from your orgs' dashboards. Existing merchants on the gateway are soft-deleted (with a grace window for active subscriptions).
Troubleshooting
- Mode card says "Managed mode — enabled" but credentials are missing — the provisioning call is pending or failed. Give it up to a minute; if it persists, your license plan may not grant Payment Gateway. Check Admin → License.
- "Not configured" in BYO mode — the save didn't land. Re-check the Gateway URL and Admin Key using Test Connection.
- Webhooks arrive but events look unprocessed — the signature check is strict. See the epay-gateway webhook signature docs for the HMAC formula.
- Orgs don't see a payment method at checkout — make sure at least one provider is enabled on your gateway. In managed mode the provider list is platform-managed; in BYO, configure providers in your gateway's admin console.
- "Payment Gateway" service can't be created — the feature is gated on the license feature flag, on the gateway being configured, and on managed mode being on (per-org merchants are managed-only). If you're in BYO mode, the service type won't be offered to your orgs.
Privacy & data boundaries
- BYO mode: payment credentials and merchant secrets never leave your kuploy-cloud instance (they live encrypted in your own database). Funds settle on accounts you registered with your providers directly.
- Managed mode: credentials are minted and held on the platform's infrastructure; your kuploy-cloud receives and stores the per-tenant merchant secret + a narrowly-scoped admin key that can only touch your own merchant (nothing broader). When your orgs use the composable service, each org's own merchant secret is also synced down and stored encrypted at rest, scoped to that org; it's used to verify that org's payment events before they're relayed to the org's app. A gateway-side key rotation self-heals on the next sync. Funds settle on accounts the platform admin has registered on the shared gateway's provider plugins, on your behalf.
- The platform reports only aggregate payment metrics back to kuploy.app on license sync: transaction count, total volume (in the gateway's base currency minor units), active merchant count, and the list of active provider names. No customer identifiers, amounts-per-transaction, or phone numbers are sent upstream.
- Disabling the Payment Gateway feature (downgrade, toggle off, or BYO reset) halts the aggregate reporting immediately.