Build on OrbytPay

Get started

OrbytPay moves money through Kora: your customer pays on hosted checkout, both sides verify the deposit, then your merchant balance is credited. Processing is a fixed ₦100 per collection — you choose whether the customer or you bears it.

Connect your API key

Paste your secret key. OrbytPay checks it against live merchant records and confirms your account — without ever storing the key in the browser.

From your server

# Confirm the secret belongs to a live OrbytPay merchant
curl -X POST https://www.orbytpay.app/v1/connect/verify \
  -H "Authorization: Bearer orbk_sec_…"
→ { "status": true, "data": { "connected": true, "app_id": "…", "name": "…", "kyc": { "status": "approved" }, … } }

Authentication

Every merchant API call uses your secret key:

Authorization: Bearer orbk_sec_…

Responses always look like:

{ "status": true, "data": { … }, "request_id": "req_…" }

On failure: status: false with error.type and error.message.

• Secret key (orbk_sec_) — server-to-server. Full API access after KYC unlock.
• Portal session (opt_) — browser/app after email login. Full scope for collect/withdraw; pinned to up to two devices.
• Webhook secret (orbk_whk_) — only for verifying OrbytPay → your server signatures. Never use it as an API Bearer.

Collect payments

When a customer taps Pay in your app, your backend creates a payment. Open the returned payment_url (hosted OrbytPay checkout). Kora takes the deposit; OrbytPay double-checks before crediting you.

# Create a payment (₦100 fee — customer pays it by default)
curl -X POST https://www.orbytpay.app/v1/payments \
  -H "Authorization: Bearer orbk_sec_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8842" \
  -d '{
    "amount": 25000,
    "currency": "NGN",
    "fee_bearer": "customer",
    "customer": { "name": "Ada Obi", "email": "ada@example.com" },
    "callback_url": "https://yourapp.com/wallet"
  }'
→ payment_url, reference, charge_total, status: "pending"

Fee bearer

• customer (default) — they pay amount + ₦100; you receive the full amount.
• merchant — they pay exactly the amount; ₦100 is taken from your credit.

Check status

curl https://www.orbytpay.app/v1/payments/orb_… \
  -H "Authorization: Bearer orbk_sec_…"

curl https://www.orbytpay.app/v1/balance \
  -H "Authorization: Bearer orbk_sec_…"

Only release goods or unlock value after status is success (and ideally after your payment.credited webhook).

Webhooks

Set your HTTPS endpoint in the portal (or PATCH /v1/me). OrbytPay POSTs signed events after Kora + OrbytPay both confirm a deposit.

# Configure webhook URL
curl -X PATCH https://www.orbytpay.app/v1/me \
  -H "Authorization: Bearer orbk_sec_…" \
  -H "Content-Type: application/json" \
  -d '{ "webhook_url": "https://yourapp.com/webhooks/orbytpay" }'

Verify signatures

Header x-orbytpay-signature is HMAC-SHA256 of JSON.stringify(data) using your webhook secret. Sign the data object only — not the outer envelope.

{
  "event": "payment.credited",
  "data": {
    "app_id": "your_merchant_id",
    "reference": "orb_…",
    "amount": 25000,
    "currency": "NGN",
    "status": "success",
    "balance_after": 25000
  }
}

Deliveries retry up to 6 times. Respond 2xx quickly; do heavy work async. Amount mismatches never credit.

Withdraw to bank

Requires approved KYC. Resolve the account name first, then disburse. Balance is debited atomically; failed Kora calls reverse the debit.

curl -X POST https://www.orbytpay.app/v1/banks/resolve \
  -H "Authorization: Bearer orbk_sec_…" \
  -H "Content-Type: application/json" \
  -d '{ "bank": "058", "account": "0123456789" }'

curl -X POST https://www.orbytpay.app/v1/withdrawals \
  -H "Authorization: Bearer orbk_sec_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wd-payroll-01" \
  -d '{
    "amount": 50000,
    "currency": "NGN",
    "bank": "058",
    "account": "0123456789",
    "account_name": "ADA OBI"
  }'

Refunds

Full or partial refunds debit your balance and reverse the deposit via Kora.

curl -X POST https://www.orbytpay.app/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" }'

Watch refund.completed / refund.failed (balance restored on failure).

Security rules

• Keep orbk_sec_ on your server only — never in APK/IPA, GitHub, or browser code.
• Use HTTPS webhook URLs only (live mode rejects private/metadata hosts).
• Verify every webhook signature before trusting the payload.
• Use Idempotency-Key on payments, withdrawals, and refunds.
• Rotate secrets anytime: POST /v1/keys/rotate and POST /v1/webhooks/rotate-secret.
• Do not release value on pending status — wait for success + webhook.

API reference

Base URL: https://www.orbytpay.app

Need the portal? Sign in → · Questions on fees: Terms.