Balance Transaction

A Balance Transaction records every movement of money in or out of your xpay balance: successful charges, refunds, payouts, processing fees, and adjustments. Each Balance Transaction links back to its `source` (the Charge, Refund, or Payout that produced it) and breaks down `gross`, `fee`, and `net` amounts. Use Balance Transactions to reconcile what was paid into your account against what was settled to your bank.

A Balance Transaction records every movement of money in or out of your xpay balance: successful charges, refunds, payouts, processing fees, and adjustments. Each Balance Transaction links back to its source (the Charge, Refund, or Payout that produced it) and breaks down gross, fee, and net amounts. Use Balance Transactions to reconcile what was paid into your account against what was settled to your bank.

id*string

Balance transaction ID

object*string

Object type

amount*number

Gross amount (positive for money in, negative for money out) in smallest currency unit

availableOn?|

Timestamp when funds become available in balance (ISO 8601)

createdAt*string

Created timestamp (ISO 8601)

currency*string

Currency

description?|

Human-readable description

fee*number

Total fees in smallest currency unit

net*number

Net amount after fees in smallest currency unit

feeDetails*array<>

Breakdown of the fee. Platform COGS entries (PROCESSOR_COST) are stripped before emission — merchants only see the fees they care about.

status*string

Transaction status

type*string

Transaction type

reportingCategory*string

Reporting category for accounting/analytics. Falls back to type when the entity has no explicit override.

exchangeRate?|

Exchange rate when currency conversion occurred

source*string

Source resource id (charge, refund, payout, topup, dispute). Scalar id only — merchants query the source explicitly.

payoutBatch*|null

The PayoutBatch this balance transaction was included in, or null until it's batched.

paymentIntentId?|

Associated payment intent ID (if applicable)

merchantId*string

Merchant ID owning this balance transaction

{
  "id": "txn_abc123",
  "object": "balance_transaction",
  "amount": 22604,
  "availableOn": "string",
  "createdAt": "string",
  "currency": "EGP",
  "description": "string",
  "fee": 912,
  "net": 21692,
  "feeDetails": [
    {
      "amount": 0,
      "currency": "EGP",
      "description": "string",
      "type": "string",
      "application": "string"
    }
  ],
  "status": "AVAILABLE",
  "type": "CHARGE",
  "reportingCategory": "string",
  "exchangeRate": 0,
  "source": "string",
  "payoutBatch": {
    "id": "pb_xxx",
    "object": "payout_batch",
    "amount": 0,
    "currency": "EGP",
    "status": "paid",
    "arrivalDate": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "paymentIntentId": "string",
  "merchantId": "string"
}