Developers
API documentation
Merchant REST API for virtual accounts and webhooks.
Base URL
https://apipaycore.domovate.tech/v1Authentication
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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxConventions
- Money — always kobo as a string/integer (₦1.00 =
100). - Idempotency — send
Idempotency-Keyon 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
/virtual-account-banksList available banks (PalmPay, OPay)/virtual-accountsCreate reserved account(s) for a customerCreate 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"
}
]
}
}/virtual-accounts?customer_reference=usr_8f3a2c1b9e7d&limit=50List accounts/virtual-accounts/:idGet one accountPass 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-Signatureheader (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
200quickly. 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.reversedvirtual_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.