Wallet & Transactions

Wallet & Transactions

Manage your pharmacy’s finances — check balances, view transaction history, manage virtual accounts, and handle payouts.

Check Wallet Balance

View your current wallet balance and pending amounts.

# Get current wallet balance
getProviderWalletBalance()

Response:

{
  "currency": "NGN",
  "availableBalance": 1250000,
  "pendingBalance": 45000,
  "totalBalance": 1295000,
  "lastUpdated": "2026-04-18T14:30:00Z",
  "thresholds": {
    "lowBalanceAlert": 50000,
    "autoDebitEnabled": true
  }
}

Balance Types:

Type	Description
availableBalance	Funds ready for withdrawal/spending
pendingBalance	Funds being processed (settlements)
totalBalance	Combined available + pending

Transaction History

View all wallet transactions with filters.

# Get transaction history
getProviderTransactionHistory({
  page: 1,
  limit: 20,
  type: "credit",  // credit, debit, all
  startDate: "2026-04-01",
  endDate: "2026-04-30"
})

Parameters:

Parameter	Type	Required	Description
page	number	No	Page number (default: 1)
limit	number	No	Results per page (default: 20)
type	string	No	Filter: credit, debit, all
startDate	string	No	Filter from date
endDate	string	No	Filter to date

Response:

{
  "transactions": [
    {
      "id": "TXN-789",
      "type": "credit",
      "amount": 8500,
      "currency": "NGN",
      "description": "Order payment - ORD-456",
      "status": "completed",
      "balanceAfter": 1250000,
      "metadata": {
        "orderId": "ORD-456",
        "customer": "John Doe"
      },
      "createdAt": "2026-04-18T10:30:00Z"
    },
    {
      "id": "TXN-790",
      "type": "debit",
      "amount": 500,
      "currency": "NGN",
      "description": "Delivery fee",
      "status": "completed",
      "balanceAfter": 1241500,
      "createdAt": "2026-04-18T09:15:00Z"
    },
    {
      "id": "TXN-791",
      "type": "credit",
      "amount": 12000,
      "currency": "NGN",
      "description": "Order payment - ORD-457",
      "status": "pending",
      "balanceAfter": null,
      "createdAt": "2026-04-18T08:00:00Z"
    }
  ],
  "total": 156,
  "summary": {
    "totalCredits": 2450000,
    "totalDebits": 1200000,
    "net": 1250000
  }
}

Virtual Accounts

Manage virtual bank accounts for receiving payments.

# Get all virtual accounts
getAllProviderVirtualAccounts()

Response:

{
  "accounts": [
    {
      "id": "VA-123",
      "accountNumber": "1234567890",
      "accountName": "GreenCross Pharmacy",
      "bankName": "Providus Bank",
      "bankCode": "101",
      "status": "active",
      "createdAt": "2025-06-15T10:00:00Z",
      "totalReceived": 2450000
    },
    {
      "id": "VA-124",
      "accountNumber": "9876543210",
      "accountName": "GreenCross Pharmacy",
      "bankName": "Wema Bank",
      "bankCode": "035",
      "status": "active",
      "createdAt": "2025-08-20T14:30:00Z",
      "totalReceived": 1200000
    }
  ]
}

Create Virtual Account

Create a new virtual account for receiving payments.

# Create new virtual account
createProviderVirtualAccount({
  bankCode: "035",  // Wema Bank
  label: "Main Branch"
})

Request Payout

Withdraw funds from your wallet.

# Request payout to bank account
requestProviderPayout({
  amount: 500000,
  bankCode: "011",  // First Bank
  accountNumber: "1234567890",
  accountName: "GreenCross Pharmacy Ltd",
  description: "Weekly settlement"
})

Response:

{
  "success": true,
  "payoutId": "PAY-456",
  "amount": 500000,
  "fee": 500,
  "total": 500500,
  "status": "processing",
  "estimatedArrival": "2026-04-19T10:00:00Z",
  "reference": "PAYOUT-20260418-001"
}

Payout History

View past withdrawal requests.

# Get payout history
getProviderPayoutHistory({
  page: 1,
  limit: 10,
  status: "completed"
})

Response:

{
  "payouts": [
    {
      "id": "PAY-456",
      "amount": 500000,
      "fee": 500,
      "status": "completed",
      "bank": "First Bank",
      "accountNumber": "****7890",
      "reference": "PAYOUT-20260418-001",
      "createdAt": "2026-04-18T10:00:00Z",
      "completedAt": "2026-04-18T14:30:00Z"
    }
  ],
  "total": 45
}

Set Low Balance Threshold

Configure alerts for low wallet balance.

# Set low balance alert threshold
setLowWalletThreshold({
  threshold: 10000
})

Toggle Auto-Debit

Enable or disable automatic debits for fees.

# Enable auto-debit for fees
toggleAutoDebit({
  enabled: true
})

When enabled, fees (delivery, service fees) are automatically deducted from your wallet.

Transaction Types

Type	Description
credit	Money added to wallet (order payments)
debit	Money deducted (fees, payouts)
refund	Refund to customer
adjustment	Manual balance adjustment

Example: Financial Workflow

# Step 1: Check current balance
getProviderWalletBalance()
# → Shows available and pending funds

# Step 2: Review recent transactions
getProviderTransactionHistory({
  limit: 10,
  type: "credit"
})
# → Shows recent incoming payments

# Step 3: Request payout
requestProviderPayout({
  amount: 500000,
  bankCode: "011",
  accountNumber: "1234567890",
  accountName: "GreenCross Pharmacy Ltd"
})
# → Payout queued for processing

# Step 4: Check payout status
getProviderPayoutHistory({ status: "processing" })
# → Shows pending payouts

Fees Structure

Transaction	Fee
Order payment (card)	1.5%
Order payment (transfer)	1%
Order payment (wallet)	0%
Payout to bank	₦50
Delivery fee	Variable

Next steps

• Settings — Configure payment preferences
• Analytics — View revenue reports
• Orders — Track order payments