Access Specific Fund Ledger Entry

When you retrieve a ledger entry from Payiano, you are obtaining a detailed record of a specific financial movement within your account. Each ledger entry captures the type of transaction (debit or credit), the affected balance bucket, the amount, and the resulting balance after the entry was applied.

Detailed Entry Breakdown

A single ledger entry provides a comprehensive snapshot of a fund movement. It includes the reason behind the movement (such as a payment collection, settlement, withdrawal, or fee charge), a reference to the originating transaction, and the exact balance state after the operation. This level of detail supports thorough financial auditing, dispute resolution, and operational reporting.

  • Transaction Type: Determine whether the entry is a debit or credit, helping you understand the direction of the fund movement.
  • Bucket Classification: Identify which balance bucket (available or pending) was affected by the financial event, enabling precise fund tracking.
  • Source Traceability: Trace the ledger entry back to its originating payment or payout transaction through the source reference fields.
  • Balance Reconciliation: View the resulting balance after the entry was applied, making it straightforward to reconcile your account at any point in time.
GET/fund/ledgers/{ledger_id}
Sandbox: https://api.payiano.dev/v1/fund/ledgers/{ledger_id}
Live: https://api.payiano.com/v1/fund/ledgers/{ledger_id}
Security
  • Authorization header with access token is required to access this endpoint: Bearer ACCESS-TOKEN
  • Your access token should be associated to this permission fund.ledgers.view
Request
Request body schema:
application/json
Path parameters:
ledger_id
required
Type: ulid
Length: 26

The unique ID assigned to each fund ledger which is generated by our system using the ULID format. Each ID is precisely 26 characters long, ensuring a unique and consistent identifier for every fund ledger. This ULID is automatically created by our system and is used to uniquely identify and track each fund ledger in our database.

Query parameters:
includes
Type: array_of_enums|null
Possible values:
JSON
[ "ledger.balance" ]

A list of additional fund ledger related objects to eager-load and return with the response. Pass only the relations you need to keep response payloads lean. See Including Resources for the full list of supported include values and usage details.

Response
200
Response schema:
application/json
Response body:
ledger
Type: object

The ledger entry record including transaction direction, amount, currency, and reference details.

id
Type: ulid
Length: 26

The unique ID assigned to each ledger which is generated by our system using the ULID format. Each ID is precisely 26 characters long, ensuring a unique and consistent identifier for every ledger. This ULID is automatically created by our system and is used to uniquely identify and track each ledger in our database.

type
Type: enum
Possible values:
JSON
[ "debit", "credit" ]

The type of the ledger entry indicating whether funds were debited or credited.

bucket
Type: enum
Possible values:
JSON
[ "available", "pending" ]

The balance bucket affected by this ledger entry, either available or pending funds.

amount
Type: decimal

The amount value of the ledger entry. The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.

balance_after
Type: decimal

The balance of this bucket after applying the ledger entry. The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.

reason
Type: enum
Possible values:
JSON
[ "payment_collected", "payment_settled", "withdrawal", "withdrawal_reversed", "fee_charged" ]

The reason for this ledger entry, indicating the financial event that triggered it.

sourceable_id
Type: ulid
Length: 26

The unique ID of the source entity (e.g., a payment or payout transaction) that triggered this ledger entry.

sourceable_type
Type: enum
Possible values:
JSON
[ "payment.transaction", "payout.transaction" ]

The type of the source entity that triggered this ledger entry.

balance_id
Type: ulid
Length: 26

The unique ID of the balance record this ledger entry belongs to.

balance
Type: object

The balance details model for the ledger entry.

id
Type: ulid
Length: 26

The unique ID assigned to each balance which is generated by our system using the ULID format. Each ID is precisely 26 characters long, ensuring a unique and consistent identifier for every balance. This ULID is automatically created by our system and is used to uniquely identify and track each balance in our database.

currency_code
Type: enum
Possible values:
JSON
[ "EGP" ]

The three-character ISO-4217 Currency Code that identifies the currency for the balance. Your business should be eligible to use the selected currency code.

available_amount
Type: decimal

The available amount value to be withdrawn. The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.

pending_amount
Type: decimal

The pending amount value to be collected. The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.

created_at
Type: datetime

The creation datetime of the ledger entry. This attribute can be formatted as an ISO 8601 string or a UNIX timestamp in milliseconds, depending on the preferred datetime format specified in the request header (e.g., 2024-08-04T14:22:01Z or 1722572118554). By default, the format is UNIX timestamp in milliseconds.

Response sample:
JSON
1
{ 2
 "ledger": { 3 "id": "01hqh45s7826hfwdze8dp1z22g", 4 "type": "credit", 5 "bucket": "available", 6 "amount": 50000, 7 "balance_after": 200000, 8 "reason": "payment_collected", 9 "sourceable_id": "01hsgngrhmjmcdr560hwzvv8e2", 10 "sourceable_type": "payment.transaction", 11 "balance_id": "01hqh45s7826hfwdze8dp1z21f", 12
 "balance": { 13 "id": "01hqh45s7826hfwdze8dp1z21f", 14 "currency_code": "EGP", 15 "available_amount": 200000, 16 "pending_amount": 68500 17 }, 18 "created_at": "1775242402269" 19 } 20}