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.

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

Value in"EGP" | "USD" | "EUR" | "GBP" | "SAR" | "AED" | "QAR" | "KWD" | "JOD" | "OMR" | "BHD" | "LYD" | "AUD" | "CAD" | "CNY"

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

Value in"AVAILABLE" | "PENDING"

type*string

Transaction type

Value in

"CHARGE" | "PAYMENT" | "PAYMENT_FAILURE_REFUND" | "PAYMENT_REFUND" | "PAYMENT_REVERSAL" | "REFUND" | "REFUND_FAILURE" | "ADJUSTMENT" | "ADVANCE" | "ADVANCE_FUNDING" | "PAYOUT" | "PAYOUT_CANCEL" | "PAYOUT_FAILURE" | "PAYOUT_MINIMUM_BALANCE_HOLD" | "PAYOUT_MINIMUM_BALANCE_RELEASE" | "RESERVED_FUNDS" | "RESERVE_HOLD" | "RESERVE_RELEASE" | "RECOVERY_FROM_FUTURE_FUNDS" | "XPAY_FEE" | "XPAY_FX_FEE" | "TAX_FEE" | "TOPUP" | "TOPUP_REVERSAL"

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