DojaPay API Documentation

Secure, Scalable & Developer Friendly Financial API Platform

Authentication

All requests to DojaPay API must be authenticated. Use Basic Authentication to obtain an access_token which must be included in the Authorization header for subsequent requests.

Token Expiration: The access_token is valid for 60 minutes.

Request

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

Response

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

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.

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

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

Verify Transaction

POST /transactions/verify

Verify transaction status using 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 can have specific amount rules (EXACT, ANY, HIGHEROREXACT, LOWEROREXACT) and optional expiry hours.

📥 Request Body

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

Example for a Dynamic Account with amount rules:

{
  "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"
  }
}
  

❌ Validation Error Example

{
  "code": "400",
  "message": ["Validation failed"],
  "errors": {
    "email": ["The email field is required."],
    "accountType": ["The selected accountType is invalid."]
  }
}
  

📘 Notes

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

Wallet Balance

GET /wallet/balance

Get current wallet balance of 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
  }
}

Webhook Notification

We notify your webhook URL for events like payment success. Always verify using the reference ID.

{
  "event": "payment.success",
  "data": {
    "reference": "DP12345678",
    "amount": 5000,
    "status": "successful"
  }
}