OrbytPay API

Every endpoint below is live on orbytpay.app. Authenticate with your orbk_sec_ secret key. All responses are { "status": true, "data": { ... }, "request_id": "req_..." }.

# 1 — create a payment when the user taps Pay
#    Optional: Idempotency-Key header prevents duplicate charges on retries
#    fee_bearer: 'customer' (default — they pay amount + ₦100, you receive it all)
#                or 'merchant' (they pay exactly the amount, ₦100 comes off your credit)
curl -X POST {ORIGIN}/v1/payments \
  -H "Authorization: Bearer orbk_sec_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deposit-ada-2026-07-02" \
  -d '{ "amount": 25000, "currency": "NGN", "fee_bearer": "customer",
        "customer": { "name": "Ada Obi", "email": "ada@example.com" },
        "callback_url": "https://yourapp.com/wallet" }'
→ { "status": true, "data": { "reference": "orb_...", "payment_url": "{ORIGIN}/checkout?reference=orb_...", "status": "pending", "amount": 25000, "charge_total": 25100, "fee_bearer": "customer" } }

# 2 — your app identity
curl {ORIGIN}/v1/me -H "Authorization: Bearer orbk_sec_..."

# 3 — list payments for your app
curl "{ORIGIN}/v1/payments?limit=20&status=success" -H "Authorization: Bearer orbk_sec_..."

# 4 — OrbytPay POSTs this to your webhook_url after Kora + OrbytPay double-verify
#     Header: x-orbytpay-signature = HMAC_SHA256(JSON.stringify(data), your orbk_whk_ secret)
#     Sign the data object only — not the outer envelope.
{ "event": "payment.credited",
  "data": { "app_id": "your_merchant_id", "event_time": "2026-07-02T12:00:00.000Z",
            "reference": "orb_...", "amount": 25000, "currency": "NGN",
            "status": "success", "balance_after": 25000 } }

# 5 — verify a webhook signature server-side
curl -X POST {ORIGIN}/v1/webhooks/verify -H "Authorization: Bearer orbk_sec_..." \
  -H "x-orbytpay-signature: <sig>" -H "Content-Type: application/json" \
  -d '{ "event": "payment.credited", "data": { ... } }'

# 6 — verify payment + balance before releasing value
curl {ORIGIN}/v1/payments/orb_... -H "Authorization: Bearer orbk_sec_..."
curl {ORIGIN}/v1/balance -H "Authorization: Bearer orbk_sec_..."

# 7 — rotate credentials any time (old key + sessions die instantly)
curl -X POST {ORIGIN}/v1/keys/rotate -H "Authorization: Bearer orbk_sec_..."
curl -X POST {ORIGIN}/v1/webhooks/rotate-secret -H "Authorization: Bearer orbk_sec_..."

# 8 — update your webhook / callback URL
curl -X PATCH {ORIGIN}/v1/me -H "Authorization: Bearer orbk_sec_..." \
  -H "Content-Type: application/json" \
  -d '{ "webhook_url": "https://yourapp.com/webhooks/orbytpay" }'

# 9 — refund a settled payment (full or partial); balance is debited
curl -X POST {ORIGIN}/v1/refunds -H "Authorization: Bearer orbk_sec_..." \
  -H "Content-Type: application/json" -H "Idempotency-Key: refund-order-8842" \
  -d '{ "payment_reference": "orb_...", "amount": 10000, "reason": "customer request" }'
→ { "status": true, "data": { "reference": "orbref_...", "status": "processing", "amount": 10000, "charge_reference": "orb_..." } }
#     Webhooks: refund.created (immediate) → refund.completed or refund.failed (balance restored on fail)

Every deposit: Kora signed webhook → Orbyt Pay independent API cross-check → full balance credit → signed payment.credited webhook (retried up to 6×). Terminal states cannot regress. Amount mismatches withhold credit.

Sign up → Create a merchant account · Merchant portal → Sign in with your secret key to withdraw via Kora.