Balance API

The Balance API allows you to retrieve your PayGate account balance.

The Balance Object

{
  "object": "balance",
  "available": [
    {
      "amount": 1500000,
      "currency": "GHS"
    }
  ],
  "pending": [
    {
      "amount": 250000,
      "currency": "GHS"
    }
  ],
  "reserved": [
    {
      "amount": 50000,
      "currency": "GHS"
    }
  ]
}

Attributes

Attribute	Type	Description
`object`	string	Always `"balance"`
`available`	array	Funds available for payouts
`pending`	array	Funds not yet available
`reserved`	array	Funds held in reserve

Balance Types

Type	Description
Available	Funds that can be paid out immediately
Pending	Funds from recent payments (usually available in 1-2 business days)
Reserved	Funds held for refunds or disputes

Retrieve Balance

Retrieves your current balance.

GET /v1/balance

curl https://api.44.200.142.19.nip.io/v1/balance \
  -H "Authorization: Bearer sk_test_..."

const balance = await paygate.balance.retrieve()

console.log('Available:', balance.available[0].amount / 100, 'GHS')
console.log('Pending:', balance.pending[0].amount / 100, 'GHS')

balance = client.balance.retrieve()

print(f"Available: {balance.available[0].amount / 100} GHS")
print(f"Pending: {balance.pending[0].amount / 100} GHS")

$balance = $paygate->balance->retrieve();

echo 'Available: ' . ($balance->available[0]->amount / 100) . ' GHS';
echo 'Pending: ' . ($balance->pending[0]->amount / 100) . ' GHS';

Response

{
  "object": "balance",
  "available": [
    {
      "amount": 1500000,
      "currency": "GHS"
    }
  ],
  "pending": [
    {
      "amount": 250000,
      "currency": "GHS"
    }
  ],
  "reserved": [
    {
      "amount": 50000,
      "currency": "GHS"
    }
  ]
}

List Balance Transactions

Returns a list of transactions that have contributed to your balance.

GET /v1/balance/transactions

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (1-100)
`starting_after`	string	Cursor for pagination
`type`	string	Filter by transaction type
`created[gte]`	string	Filter by creation date
`created[lte]`	string	Filter by creation date

Transaction Types

Type	Description
`payment`	Successful payment
`refund`	Refund issued
`payout`	Payout to your bank/mobile money
`adjustment`	Manual adjustment
`fee`	PayGate fees

curl "https://api.44.200.142.19.nip.io/v1/balance/transactions?limit=10" \
  -H "Authorization: Bearer sk_test_..."

const transactions = await paygate.balance.transactions.list({
  limit: 10,
  type: 'payment'
})

transactions = client.balance.transactions.list(limit=10, type='payment')

Response

{
  "object": "list",
  "data": [
    {
      "id": "txn_abc123",
      "object": "balance_transaction",
      "amount": 5000,
      "currency": "GHS",
      "net": 4850,
      "fee": 150,
      "type": "payment",
      "source": "pay_xyz789",
      "description": "Payment from customer@example.com",
      "status": "available",
      "created_at": "2024-01-15T10:00:00Z",
      "available_on": "2024-01-17T00:00:00Z"
    }
  ],
  "has_more": true,
  "url": "/v1/balance/transactions"
}

Balance Transaction Object

{
  "id": "txn_abc123def456",
  "object": "balance_transaction",
  "amount": 5000,
  "currency": "GHS",
  "net": 4850,
  "fee": 150,
  "type": "payment",
  "source": "pay_xyz789",
  "description": "Payment from customer@example.com",
  "status": "available",
  "created_at": "2024-01-15T10:00:00Z",
  "available_on": "2024-01-17T00:00:00Z"
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier
`object`	string	Always `"balance_transaction"`
`amount`	integer	Gross amount in pesewas
`currency`	string	Currency code
`net`	integer	Net amount after fees
`fee`	integer	PayGate fees
`type`	string	Transaction type
`source`	string	Source object ID
`description`	string	Description
`status`	string	`pending` or `available`
`created_at`	string	Creation timestamp
`available_on`	string	When funds become available

Retrieve a Balance Transaction

Retrieves a specific balance transaction.

GET /v1/balance/transactions/:id

curl https://api.44.200.142.19.nip.io/v1/balance/transactions/txn_abc123def456 \
  -H "Authorization: Bearer sk_test_..."

const transaction = await paygate.balance.transactions.retrieve('txn_abc123def456')

transaction = client.balance.transactions.retrieve('txn_abc123def456')

Understanding Your Balance

Your available balance represents funds you can withdraw immediately. Pending funds typically become available within 1-2 business days.

Example: Checking if You Can Make a Payout

async function canMakePayout(amount: number): Promise<boolean> {
  const balance = await paygate.balance.retrieve()
  const available = balance.available[0]?.amount || 0

  return available >= amount
}

// Usage
if (await canMakePayout(10000)) {
  const payout = await paygate.payouts.create({
    amount: 10000,
    recipient: 'rcp_xyz789'
  })
} else {
  console.log('Insufficient available balance')
}

Example: Daily Balance Summary

async function getDailySummary() {
  const balance = await paygate.balance.retrieve()

  const today = new Date()
  today.setHours(0, 0, 0, 0)

  const transactions = await paygate.balance.transactions.list({
    created: { gte: today.toISOString() },
    limit: 100
  })

  let totalPayments = 0
  let totalRefunds = 0
  let totalFees = 0

  for (const txn of transactions.data) {
    if (txn.type === 'payment') totalPayments += txn.amount
    if (txn.type === 'refund') totalRefunds += txn.amount
    totalFees += txn.fee
  }

  return {
    available: balance.available[0].amount,
    pending: balance.pending[0].amount,
    todayPayments: totalPayments,
    todayRefunds: totalRefunds,
    todayFees: totalFees
  }
}

Balance

On this page