CowrieLane

Developers

API documentation

Merchant REST API for virtual accounts and webhooks.

Base URL

https://apipaycore.domovate.tech/v1

Authentication

Authenticate every request with a Bearer API key from API keys. The key identifies your business — you do not need to send business_id on every call (optional; if present it must match the key). TEST keys work before KYC; LIVE keys require an approved merchant.

Header

Authorization: Bearer pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Conventions

  • Money — always kobo as a string/integer (₦1.00 = 100).
  • Idempotency — send Idempotency-Key on POST requests.
  • Customer reference — any unique string you own (UUID, user id, order id). Not a CowrieLane-assigned sequence like cust_001.
  • Errors — { "error": { "code", "message", "request_id" } }
  • Pagination — cursor-based where listed (has_more, next_cursor).
  • Samples — switch language tabs on Create VA and Full webhook endpoint (cURL, Node.js, Python/Django, PHP, Java).

Virtual accounts

GET/virtual-account-banksList available banks (PalmPay, OPay)
POST/virtual-accountsCreate reserved account(s) for a customer

Create virtual account

curl -X POST https://apipaycore.domovate.tech/v1/virtual-accounts \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "business_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "bank_codes": ["1", "2", "3"],
    "customer": {
      "reference": "usr_8f3a2c1b9e7d",
      "first_name": "Jane",
      "last_name": "Adeyemi",
      "email": "jane@example.com",
      "phone": "08031234567"
    }
  }'

201 response

{
  "data": {
    "business_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_reference": "usr_8f3a2c1b9e7d",
    "accounts": [
      {
        "id": "3f9c2a71-…",
        "reference": "va_mg7k2p1a9f3c",
        "account_number": "9012345678",
        "account_name": "Acme Stores - Jane (CowrieLane)",
        "bank_name": "PalmPay",
        "bank_code": "1"
      },
      {
        "id": "8b14e0d2-…",
        "reference": "va_mg7k2p1b4e8d",
        "account_number": "8123456789",
        "account_name": "Acme Stores - Jane (CowrieLane)",
        "bank_name": "PalmPay",
        "bank_code": "2"
      },
      {
        "id": "c27a9f45-…",
        "reference": "va_mg7k2p1c7a2b",
        "account_number": "7234567890",
        "account_name": "Acme Stores - Jane (CowrieLane)",
        "bank_name": "OPay",
        "bank_code": "3"
      }
    ]
  }
}
GET/virtual-accounts?customer_reference=usr_8f3a2c1b9e7d&limit=50List accounts
GET/virtual-accounts/:idGet one account

Pass bank_codes like ["1","2","3"]. Accounts return as PalmPay / OPay. Sandbox typically has code 1 (PalmPay); fetch the live list from GET /virtual-account-banks.

Webhooks

Register an HTTPS URL under Webhooks. CowrieLane POSTs signed JSON events to that URL. Verify the signature with your signing secret so you only process requests that came from CowrieLane. Delivery attempts appear in Webhook Events.

  • Read the X-CowrieLane-Signature header (HMAC-SHA512 hex of the raw request body + your signing secret).
  • Hash the raw body bytes first — do not parse/re-serialize JSON before verifying.
  • Compare with a constant-time check; on match, parse JSON and handle the event.
  • Return 200 quickly. CowrieLane retries on non-2xx.

Signature header

X-CowrieLane-Signature: <HMAC-SHA512 hex of raw body>

Full webhook endpoint

# CowrieLane POSTs to your HTTPS URL with header:
#   X-CowrieLane-Signature: <HMAC-SHA512 hex of the raw body>
#
# Signing secret comes from Dashboard → Webhooks (shown once).
# Always hash the raw body bytes — do not re-serialize JSON.
#
# Local smoke-test of the HMAC (replace SECRET + BODY):
printf '%s' '{"event":"transaction.success","data":{}}' \
  | openssl dgst -sha512 -hmac 'whsec_your_signing_secret'

Example payload

{
  "event": "transaction.success",
  "data": {
    "reference": "txn_…",
    "amount": "500000",
    "fee": "2000",
    "net_amount": "498000",
    "currency": "NGN",
    "status": "SUCCESS",
    "customer_reference": "usr_8f3a2c1b9e7d",
    "customer_email": "jane@example.com",
    "occurred_at": "2026-09-27T15:00:00.000Z"
  }
}
  • transaction.success / transaction.failed / transaction.reversed
  • virtual_account.created

Need a deeper design reference?

This page mirrors the live /v1 surface. Full product design notes live in the repo at docs/SYSTEM_DESIGN.md.