Balance API

The Balance API allows you to retrieve your Shika Creators account balance.

The Balance Object

{
  "object": "balance",
  "available": [
    {
      "amount": 15000.00,
      "currency": "GHS"
    }
  ],
  "pending": [
    {
      "amount": 2500.00,
      "currency": "GHS"
    }
  ],
  "livemode": true
}

Attributes

Attribute	Type	Description
`object`	string	Always `"balance"`
`available`	array	Funds available for payouts
`pending`	array	Funds not yet available
`livemode`	boolean	Whether this is a live mode balance

Balance Types

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

Retrieve Balance

Retrieves your current balance.

GET /v1/balance_transactions/summary

curl https://api.shikacreators.com/v1/balance_transactions/summary \
  -H "Authorization: Bearer sk_test_..."

const balance = await shikacreators.balance.retrieve()

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

balance = client.balance.retrieve()

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

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

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

Response

{
  "object": "balance",
  "available": [
    {
      "amount": 15000.00,
      "currency": "GHS"
    }
  ],
  "pending": [
    {
      "amount": 2500.00,
      "currency": "GHS"
    }
  ],
  "livemode": true
}

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
`source`	string	Filter by source (e.g., `payment:pay_xyz`)
`status`	string	Filter by status (`pending`, `available`)
`created_gte`	string	Filter by creation date (after)
`created_lte`	string	Filter by creation date (before)

Transaction Types

Type	Description
`payment`	Successful payment
`refund`	Refund issued
`payout`	Payout to your bank/mobile money
`transfer`	Transfer between accounts

curl "https://api.shikacreators.com/v1/balance_transactions?limit=10" \
  -H "Authorization: Bearer sk_test_..."

const transactions = await shikacreators.balanceTransactions.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": 50.00,
      "currency": "GHS",
      "net": 48.50,
      "fee": 1.50,
      "type": "payment",
      "source": "payment:pay_xyz789",
      "description": "Payment from customer@example.com",
      "status": "available",
      "balance_after": 15000.00,
      "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": 50.00,
  "currency": "GHS",
  "net": 48.50,
  "fee": 1.50,
  "type": "payment",
  "source": "payment:pay_xyz789",
  "description": "Payment from customer@example.com",
  "status": "available",
  "balance_after": 15000.00,
  "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`	number	Gross amount in GHS
`currency`	string	Currency code
`net`	number	Net amount after fees in GHS
`fee`	number	Shika Creators fees in GHS
`type`	string	Transaction type
`source`	string	Source type and ID (e.g., `payment:pay_xyz`)
`description`	string	Description
`status`	string	`pending` or `available`
`balance_after`	number	Balance after this transaction in GHS
`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.shikacreators.com/v1/balance_transactions/txn_abc123def456 \
  -H "Authorization: Bearer sk_test_..."

const transaction = await shikacreators.balanceTransactions.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 shikacreators.balance.retrieve()
  const available = balance.available[0]?.amount || 0

  return available >= amount
}

// Usage - amount is in GHS
if (await canMakePayout(100)) {
  const payout = await shikacreators.payouts.create({
    amount: 100, // GHS 100.00
    recipient: 'rcp_xyz789'
  })
} else {
  console.log('Insufficient available balance')
}

Example: Daily Balance Summary

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

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

  const transactions = await shikacreators.balanceTransactions.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