The Balance Transaction object

Balance transactions represent funds moving through your Zoneless account. Zoneless creates them for every type of transaction that enters or leaves your Zoneless account balance.

Stripe API equivalent

Retrieve a balance transaction

GET /v1/balance_transactions/:id

List all balance transactions

GET /v1/balance_transactions

Attributes

id string

Unique identifier for the object. Zoneless balance transaction IDs are prefixed with txn_z_.

object string

String representing the object's type. Objects of the same type share the same value.

amount integer

Gross amount of this transaction (in cents). A positive value represents funds received, and a negative value represents funds sent to another party.

available_on timestamp

The date that the transaction's net funds become available in the Zoneless balance.

balance_type enum

The balance that this transaction impacts. For most Zoneless transactions, this is payments.

Difference from Stripe: Zoneless only uses the payments balance type. Stripe's issuing and refund_and_dispute_prefunding types are not applicable.

Possible enum values

paymentsBalance Transactions that affect your Payments balance.

created timestamp

Time at which the object was created. Measured in seconds since the Unix epoch.

currency string

Currency code, in lowercase. For Zoneless, this is usdc.

Difference from Stripe: Always usdc instead of fiat currency codes like usd.

descriptionnullable string

An arbitrary string attached to the object. Often useful for displaying to users.

fee integer

Fees (in cents) paid for this transaction. Represented as a positive integer when assessed.

fee_details array of objects

Detailed breakdown of fees (in cents) paid for this transaction.

net integer

Net impact to your Zoneless balance (in cents). A positive value represents incrementing a balance, and a negative value decrementing a balance. You can calculate the net impact of a transaction on a balance by amount - fee.

reporting_category string

A category that helps you understand balance transactions from an accounting perspective. Common values include transfer, payout, and topup.

sourcenullable string

The ID of the object that this transaction relates to (e.g., a Transfer, Payout, or TopUp).

status enum

The transaction's net funds status in the Zoneless balance.

Possible enum values

availableFunds are available for use.

pendingFunds are not yet available.

type enum

Transaction type. The most common types for Zoneless are transfer, payout, and topup.

Difference from Stripe: Zoneless supports a focused subset of transaction types relevant to USDC payouts. Stripe's issuing, climate, and other product-specific types are not included.

Possible enum values

transferFunds transferred to an account.

transfer_cancelA transfer was canceled.

transfer_failureA transfer failed.

transfer_refundA transfer was refunded.

payoutFunds paid out to an external wallet.

payout_cancelA payout was canceled.

payout_failureA payout failed.

topupFunds added to the balance.

topup_reversalA topup was reversed.

application_feePlatform fee collected.

application_fee_refundPlatform fee refunded.

adjustmentManual balance adjustment.

More attributes

THE BALANCE TRANSACTION OBJECT

{
  "id": "txn_z_1MiN3gLkdIwHu7ixxapQrznl",
  "object": "balance_transaction",
  "amount": -40000,
  "available_on": 1678043844,
  "balance_type": "payments",
  "created": 1678043844,
  "currency": "usdc",
  "description": null,
  "fee": 0,
  "fee_details": [],
  "net": -40000,
  "platform_account": "acct_z_Platform123abc",
  "reporting_category": "transfer",
  "source": "tr_z_1MiN3gLkdIwHu7ixNCZvFdgA",
  "status": "available",
  "type": "transfer"
}

Retrieve a balance transaction

Retrieves the balance transaction with the given ID.

ENDPOINTS

GET /v1/balance_transactions/:id

Parameters

No parameters.

Returns

Returns a balance transaction if a valid balance transaction ID was provided. Raises an error otherwise.

GET/v1/balance_transactions/:id

import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const balanceTransaction = await zoneless.balanceTransactions.retrieve(
  'txn_z_1MiN3gLkdIwHu7ixxapQrznl'
);

RESPONSE

{
  "id": "txn_z_1MiN3gLkdIwHu7ixxapQrznl",
  "object": "balance_transaction",
  "amount": -40000,
  "available_on": 1678043844,
  "balance_type": "payments",
  "created": 1678043844,
  "currency": "usdc",
  "description": null,
  "fee": 0,
  "fee_details": [],
  "net": -40000,
  "platform_account": "acct_z_Platform123abc",
  "reporting_category": "transfer",
  "source": "tr_z_1MiN3gLkdIwHu7ixNCZvFdgA",
  "status": "available",
  "type": "transfer"
}

Retrieving a connected account's balance transaction

As a platform, you can retrieve balance transactions for any of your connected accounts. The platform must have created the connected account.

On behalf of a connected account

import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const balanceTransaction = await zoneless.balanceTransactions.retrieve(
  'txn_z_1MiN3gLkdIwHu7ixxapQrznl',
  {
    zonelessAccount: 'acct_z_1Nv0FGQ9RKHgCVdK',
  }
);

List all balance transactions

Returns a list of transactions that have contributed to the Zoneless account balance (e.g., transfers, payouts, topups). The transactions are returned in sorted order, with the most recent transactions appearing first.

ENDPOINTS

GET /v1/balance_transactions

Parameters

No required parameters.

More attributes

Returns

A dictionary with a data property that contains an array of up to limit transactions, starting after transaction starting_after. Each entry in the array is a separate balance transaction object. If no more transactions are available, the resulting array will be empty.

GET/v1/balance_transactions

import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const balanceTransactions = await zoneless.balanceTransactions.list({
  limit: 3,
});

RESPONSE

{
  "object": "list",
  "url": "/v1/balance_transactions",
  "has_more": false,
  "data": [
    {
      "id": "txn_z_1MiN3gLkdIwHu7ixxapQrznl",
      "object": "balance_transaction",
      "amount": -40000,
      "available_on": 1678043844,
      "balance_type": "payments",
      "created": 1678043844,
      "currency": "usdc",
      "description": null,
      "fee": 0,
      "fee_details": [],
      "net": -40000,
      "platform_account": "acct_z_Platform123abc",
      "reporting_category": "transfer",
      "source": "tr_z_1MiN3gLkdIwHu7ixNCZvFdgA",
      "status": "available",
      "type": "transfer"
    }
  ]
}

Filtering by type

You can filter balance transactions by type to see only specific kinds of transactions, such as all transfers or all payouts.

Filter by transaction type

import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const transfers = await zoneless.balanceTransactions.list({
  type: 'transfer',
  limit: 10,
});

Filtering by date range

Use the created parameter to filter transactions by their creation date. This is useful for generating reports or reconciling balances for a specific time period.

Filter by date range

import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const transactions = await zoneless.balanceTransactions.list({
  created: {
    gte: 1704067200, // Jan 1, 2024
    lt: 1706745600,  // Feb 1, 2024
  },
});