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 /virtual-accounts

Create a static or dynamic virtual account.

{
  "account_type": "static",
  "customer_name": "John Doe",
  "bvn": "12345678901",
  "email": "john@example.com"
}

{
  "code": "00",
  "message": "Account created",
  "data": {
    "account_number": "3001234567",
    "bank_name": "9PSB",
    "reference": "VA98765432"
  }
}

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