Developers

API Documentation

Secure, scalable and developer-friendly financial APIs. Authenticate once, then collect, verify, and pay out.

Authentication

All requests to the DojaPay API must be authenticated. Use Basic Authentication to obtain an access_token, then include it as a Bearer token in the Authorization header of subsequent requests.

Token expiration: the access token is valid for 24 hours (configurable per integration).

Request

POST /auth/login
Authorization: Basic base64(public_key:secret_key)

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Response codes

Code	Description
00	Successful
01	Invalid credentials
02	Transaction not found
03	Validation error
04	Insufficient balance
99	Internal server error

Create payment

POST /payments

Initiate a new payment transaction.

Request

{
  "amount": 5000,
  "currency": "NGN",
  "customer_email": "john@example.com",
  "callback_url": "https://yourapp.com/payment/callback"
}

Response

{
  "code": "00",
  "message": "Payment initialized",
  "data": {
    "reference": "DP12345678",
    "payment_url": "https://dojapay.com/pay/DP12345678"
  }
}

Verify transaction

POST /transactions/verify

Verify a transaction's status using its reference.

{
  "reference": "DP12345678"
}

{
  "code": "00",
  "message": "Transaction successful",
  "data": {
    "reference": "DP12345678",
    "status": "successful",
    "amount": 5000,
    "channel": "card",
    "paid_at": "2025-07-02T12:45:00Z"
  }
}

Create virtual account

POST /api/virtual-accounts

Create a static or dynamic virtual account for a customer. Dynamic accounts support amount rules (EXACT, ANY, HIGHEROREXACT, LOWEROREXACT) and optional expiry hours.

Request - static account

{
  "accountType": "STATIC",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "bvn": "12345678901",
  "nin": "23456789012",
  "bank": "9PSB"
}

Request - dynamic account

{
  "accountType": "DYNAMIC",
  "amountType": "EXACT",
  "amount": 1500.00,
  "expiryHours": 3,
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane@example.com",
  "bvn": "12345678901",
  "bank": "9PSB"
}

Successful response

{
  "code": "00",
  "message": "Account created successfully",
  "data": {
    "account_number": "5895001444",
    "bank_name": "9PSB",
    "reference": "VA-20251008123045ABCD1234",
    "expiry": "2025-10-08T15:30:45+01:00"
  }
}

Notes

accountType can be STATIC or DYNAMIC.
amountType is required for dynamic accounts: EXACT, ANY, HIGHEROREXACT or LOWEROREXACT.
expiryHours applies to dynamic accounts and must be between 1 and 24.
Either bvn or nin is required.

Wallet balance

GET /wallet/balance

Get the current wallet balance of the authenticated merchant.

{
  "code": "00",
  "message": "Success",
  "data": {
    "balance": 150000.75,
    "currency": "NGN"
  }
}

Create payout

POST /payouts

Disburse funds to a bank account.

{
  "amount": 10000,
  "bank_code": "044",
  "account_number": "0123456789",
  "narration": "Vendor payment"
}

{
  "code": "00",
  "message": "Payout initiated",
  "data": {
    "reference": "POUT123456"
  }
}

Merchant profile

GET /merchant/profile

Retrieve details of the authenticated merchant.

{
  "code": "00",
  "message": "Success",
  "data": {
    "merchant_name": "Doja Digital Ltd",
    "email": "support@dojapay.com",
    "wallet_balance": 250000
  }
}

Webhooks

We notify your webhook URL for events like inflows and payment success. Always verify each event against the reference before fulfilling.

{
  "event": "inflow.received",
  "data": {
    "reference": "DP12345678",
    "amount": 5000,
    "status": "successful"
  }
}

Looking for the complete reference?

Every endpoint, parameter and example lives in our interactive API reference.

Open API reference