Integration docs — Kobbopay

Overview

Kobbopay is API-first: your backend creates payments, reads authoritative status from the API, and subscribes to signed webhooks for lifecycle automation. The public marketing site is https://pay.kobbex.com; merchant operations live on https://merchant.kobbex.com after access is granted.

Code samples below use api.example.com as a neutral placeholder host. Your integration hostnames, paths, headers, and signing details come from the materials issued for your approved environment.

Before production access, review onboarding expectations. Short operational guides: /guides (lifecycle, webhooks, reconciliation, keys, onboarding). Walkthroughs: /operations.

Retries are normal. Webhook delivery is at-least-once. Design consumers to tolerate duplicates and out-of-order arrivals where possible.
Asynchronous by design. Payers, chains, and your servers operate on different clocks. UI and finance should not assume synchronous finality.
Eventual consistency. API reads, webhooks, and portal views may briefly diverge during transitions. Reconciliation jobs exist to converge truth.

Walkthroughs: /operations

Concepts

Server-to-server only: API keys must live on your infrastructure, rotated on your policy, and never ship to browsers or mobile clients.
Explicit lifecycle: model your internal state machine on documented statuses for your deployment—do not infer semantics from generic “crypto paid” language.
Rails are selective: assets and networks are enabled per merchant configuration; unsupported combinations should fail fast at creation time where possible.
Operations portal: teams reconcile, configure webhooks/keys where exposed, and initiate withdrawal requests according to your controls.
Environments: non-production and production differ by credentials, endpoints, and rails — configuration drift is an operational risk to review periodically.
Failure handling: retries, signature failures, and reconciliation exceptions are normal operational signals — design monitoring and exception queues accordingly.

Separate environments. Non-production and production use distinct configuration: API credentials, webhook URLs, rails, and confirmation policy. Do not share secrets across environments.
Scoped approval. Approval can be partial: limited rails, staged access, or operational holds until mapping and monitoring meet your production bar.
Configuration drift. Portal settings, consumer code, and finance rules can diverge over time. Periodic alignment reviews reduce “paid in portal, wrong in ERP” incidents.
Controlled rollout. Rollout is sequenced: mapping agreement, verification tests, monitoring baselines, then production traffic — integrations mature over weeks, not a single deploy.

Architecture (high level)

Payers interact with your surfaces; payment authority and secrets stay on your servers. Kobbopay exposes a payment API and lifecycle signals—never a pattern where API keys ship inside browser bundles.

Figure: data flow from payer to rails and back to your systems (conceptual; not every deployment topology).

Public marketing pages such as pay.kobbex.com describe the product. Day-to-day operations for approved merchants use merchant.kobbex.com alongside your own backends.

Payment lifecycle

A payment typically moves through a small set of states such as Pending → Paid → Confirmed, with Expired as a common terminal branch. Exact names, ordering, and edge transitions are deployment-specific—treat this description as conceptual.

Webhooks emit lifecycle transitions your systems consume to update orders, entitlements, and accounting—after you verify authenticity and process idempotently.

Lifecycle sequence (conceptual)

Typical progression for a single payment object. Finance and engineering should agree which state gates entitlements and books — exact transitions depend on enabled rails and your approved configuration.

Figure: conceptual payment states (not an exhaustive state machine for every deployment).

Pending — payment created / awaiting detection.
Paid — payment detected but not final for your reconciliation rules.
Confirmed — confirmation semantics met for the rail and policy you operate under.
Expired — payment window ended or configuration marks the path as expired (terminal for the original attempt).

Create payment

Creation is always initiated from your backend using a secret API key.

curl -sS -X POST "https://api.example.com/v1/payments" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "amount": "10.50",
    "currency": "USDT",
    "network": "example-network",
    "orderId": "order-123"
  }'

Read payment status

Your services poll or refresh status server-side. A separate public payment status surface (tokenized URL or similar) may exist for payer UX without exposing merchant secrets—availability depends on your deployment configuration.

curl -sS "https://api.example.com/v1/payments/payment_id" \
  -H "x-api-key: YOUR_API_KEY"

Webhooks

Register an HTTPS endpoint you control (for example https://api.example.com/webhook/kobbopay). Kobbopay will POST signed JSON payloads representing lifecycle changes. Use a dedicated route with minimal middleware so the raw body used for verification matches bytes on the wire.

Respond with 2xx only after you have durably recorded the event (or queued safe work). Non-2xx responses invite retries.

Webhook delivery (conceptual)

Kobbopay emits lifecycle events as signed HTTPS callbacks. Your backend verifies the signature on raw bytes, then updates internal systems using idempotent upserts so retries are safe.

Figure: signed webhook path from event emission to durable merchant-side processing.

Retries: treat duplicate deliveries as expected. Deduplicate using a stable event identifier when available, otherwise payment_id plus a derived transition key from the payload.

Webhook verification

Compute the expected signature from YOUR_WEBHOOK_SECRET and the raw request body, then compare using a constant-time check after enforcing equal buffer lengths. Parse JSON only after verification succeeds.

Event: Kobbopay emits a lifecycle transition for an authoritative payment object. Your systems should treat the webhook as a signal to reconcile — not as proof until verified.

Register a dedicated route with minimal middleware on the raw body path.
Map external lifecycle enums to your internal order model after verification.
Monitor for signature failures — they often indicate proxy or parsing mistakes.

// Express-style sketch: read raw bytes, verify, then process.
import express from "express";
import crypto from "crypto";

const app = express();

app.post(
  "/webhook/kobbopay",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const rawBody = req.body as Buffer;
    const signature = String(req.header("x-signature") ?? "");
    const secret = "YOUR_WEBHOOK_SECRET"; // load from secure config in production — never commit

    const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
    // Production: length-check buffers before timingSafeEqual; handle encoding explicitly.
    const ok = crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
    if (!ok) return res.status(401).end();

    // Parse JSON only after verification (on a copy) and upsert idempotently by payment_id + event id.
    res.status(200).end();
  },
);

Security practices · Webhook verification guide

Retry and idempotency

Webhook delivery may retry on transient failures. Make consumers idempotent by deduplicating on a stable event identifier when present, otherwise on payment_id + event type + logical transition key you derive from the payload.

For your own API calls, use bounded exponential backoff on 429/5xx, respect Retry-After when provided, and prefer create operations that accept an idempotency key if your integration kit exposes one.

Security notes

Ownership boundaries. Engineering owns webhook verification, consumers, and deployment configuration. Finance owns recognition rules and period close. Product semantics define external states — your mapping is explicit and versioned.
Escalation routing. Classify issues by signal: delivery failures, signature errors, lifecycle mapping drift, reconciliation exceptions, or treasury controls. Route with payment_id and state history — not ad-hoc wallet access.
Reconciliation responsibility. Detection on the rail does not replace your books. Scheduled reconciliation compares authoritative API or event exports to internal orders — exceptions are reviewed, not assumed away.

Never expose API keys in frontend code, demos, or screenshots.
Never send private keys, seed phrases, or webhook secrets in email, chat, or support tickets—including messages to pay.kobbex.com contact paths.
Rotate compromised keys immediately; assume leaked secrets are abused.
Prefer network controls (allowlists, mTLS where offered) for webhook ingress in high-risk deployments.

What is not public yet

OpenAPI / JSON Schema bundles pinned to production versions.
Authenticated reference for every error code and pagination edge case.
Public postman collection or SDKs (if/when published).
Formal SLA tables for webhook delivery latency.

Request integration materials for your environment via Request access.

Glossary

Short definitions for quick alignment. Canonical anchors: /glossary.

View full glossary →

These docs are an integration overview, not legal or commercial terms.
Asset and network availability depend on merchant configuration and approval.
No guarantee of instant settlement, universal finality, or global asset support.

Request access Developer hub