Ledger Entry Details

The Ledger Entry Details endpoint provides a detailed receipt for a specific ledger movement, perfect for audit documentation, customer support, and accounting proof.

What is a Ledger Entry Receipt?

Each movement in your ledger statement has a unique ledgerEntryId. Use this ID to retrieve comprehensive details about that specific transaction, including:

Balance before and after the movement
Merchant and account details
References to associated orders or settlements
Human-readable description

Use Cases

When to use Ledger Entry Details:

Audit documentation: Generate proof of specific transactions
Customer support: Quickly retrieve transaction details for inquiries
Accounting proof: Provide detailed receipts for bookkeeping
Dispute resolution: Document transaction details for disputes
Compliance: Maintain detailed records for regulatory requirements

API Endpoint


GET /api/v1/organizations/{organizationId}/merchants/{merchantId}/accounts/{accountId}/reports/ledger-entry/{ledgerEntryId}

Path Parameters

Parameter	Required	Description
`organizationId`	Yes	Organization ID
`merchantId`	Yes	Merchant ID
`accountId`	Yes	Virtual account ID
`ledgerEntryId`	Yes	Ledger entry ID (from ledger statement)

Quick Example


const response = await axios.get(
  `https://api.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/accounts/${accountId}/reports/ledger-entry/137`,
  {
    headers: { 'Authorization': `Bearer ${token}` }
  }
);
 
console.log('Entry ID:', response.data.ledgerEntryId);
console.log('Amount:', response.data.amount, response.data.currency);
console.log('Balance Before:', response.data.balanceBefore);
console.log('Balance After:', response.data.balanceAfter);
console.log('Description:', response.data.description);


response = requests.get(
    f'https://api.koywe.com/api/v1/organizations/{org_id}/merchants/{merchant_id}/accounts/{account_id}/reports/ledger-entry/137',
    headers={'Authorization': f'Bearer {token}'}
)
 
data = response.json()
print(f"Entry ID: {data['ledgerEntryId']}")
print(f"Amount: {data['amount']} {data['currency']}")
print(f"Balance Before: {data['balanceBefore']}")
print(f"Balance After: {data['balanceAfter']}")
print(f"Description: {data['description']}")


curl -X GET 'https://api.koywe.com/api/v1/organizations/org3_xxx/merchants/mrc_xxx/accounts/acc_xxx/reports/ledger-entry/137' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Understanding the Response


{
  "ledgerEntryId": "137",
  "accountId": "acc_0031c537-2301-40ab-9153-0f7c48505350",
  "merchantId": "mrc_2e8f96ab-dbd5-45f9-b4b6-645945daf340",
  "merchantName": "Acme Corporation",
  "type": "credit",
  "amount": "1000000.00",
  "currency": "CLP",
  "postedAt": "2025-01-15T10:30:00.000Z",
  "description": "PAYIN from Juan Pérez - Bank transfer received",
  "category": "PAYIN",
  "references": {
    "orderId": "ord_abc123",
    "settlementId": null
  },
  "balanceBefore": "4000000.00",
  "balanceAfter": "5000000.00",
  "generatedAt": "2025-01-31T12:00:00.000Z"
}

Response Fields Explained

Field	Description
`ledgerEntryId`	Unique identifier for this ledger entry
`merchantId`	Merchant ID associated with the account
`merchantName`	Human-readable merchant name
`type`	`credit` (increases balance) or `debit` (decreases balance)
`amount`	Transaction amount
`currency`	Currency symbol
`postedAt`	Timestamp when movement was recorded
`description`	Human-readable description
`category`	Movement category (PAYIN, PAYOUT, SETTLEMENT, etc.)
`references.orderId`	Associated order ID (if applicable)
`references.settlementId`	Associated settlement ID (if applicable)
`balanceBefore`	Account balance before this movement
`balanceAfter`	Account balance after this movement

The balanceBefore and balanceAfter fields provide audit-ready proof of how the transaction affected the account balance.

Workflow: From Statement to Details

The typical workflow is to first retrieve a ledger statement, then get details for specific entries:

Complete Example: Statement to Details


async function getTransactionReceipt(orgId, merchantId, accountId, date, token) {
  // Step 1: Get ledger statement for the date
  const statementResponse = await axios.get(
    `https://api.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/accounts/${accountId}/reports/ledger-statement`,
    {
      params: {
        from: date,
        to: date
      },
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );
  
  const movements = statementResponse.data.movements;
  console.log(`Found ${movements.length} movements on ${date}`);
  
  // Step 2: Get details for each movement
  const receipts = [];
  
  for (const movement of movements) {
    console.log(`\nFetching details for entry ${movement.ledgerEntryId}...`);
    
    const detailResponse = await axios.get(
      `https://api.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/accounts/${accountId}/reports/ledger-entry/${movement.ledgerEntryId}`,
      {
        headers: { 'Authorization': `Bearer ${token}` }
      }
    );
    
    const receipt = detailResponse.data;
    receipts.push(receipt);
    
    // Print receipt
    console.log('='.repeat(50));
    console.log('TRANSACTION RECEIPT');
    console.log('='.repeat(50));
    console.log(`Entry ID:       ${receipt.ledgerEntryId}`);
    console.log(`Date:           ${receipt.postedAt}`);
    console.log(`Merchant:       ${receipt.merchantName}`);
    console.log(`Type:           ${receipt.type.toUpperCase()}`);
    console.log(`Category:       ${receipt.category}`);
    console.log(`Amount:         ${receipt.amount} ${receipt.currency}`);
    console.log('-'.repeat(50));
    console.log(`Balance Before: ${receipt.balanceBefore} ${receipt.currency}`);
    console.log(`Balance After:  ${receipt.balanceAfter} ${receipt.currency}`);
    console.log('-'.repeat(50));
    console.log(`Description:    ${receipt.description}`);
    
    if (receipt.references.orderId) {
      console.log(`Order ID:       ${receipt.references.orderId}`);
    }
    if (receipt.references.settlementId) {
      console.log(`Settlement ID:  ${receipt.references.settlementId}`);
    }
    
    console.log('='.repeat(50));
  }
  
  return receipts;
}
 
// Usage: Get all receipts for January 15, 2025
const receipts = await getTransactionReceipt(
  'org3_xxx',
  'mrc_xxx',
  'acc_xxx',
  '2025-01-15',
  token
);


def get_transaction_receipt(org_id, merchant_id, account_id, date, token):
    # Step 1: Get ledger statement for the date
    statement_response = requests.get(
        f'https://api.koywe.com/api/v1/organizations/{org_id}/merchants/{merchant_id}/accounts/{account_id}/reports/ledger-statement',
        params={'from': date, 'to': date},
        headers={'Authorization': f'Bearer {token}'}
    )
    
    movements = statement_response.json()['movements']
    print(f"Found {len(movements)} movements on {date}")
    
    # Step 2: Get details for each movement
    receipts = []
    
    for movement in movements:
        print(f"\nFetching details for entry {movement['ledgerEntryId']}...")
        
        detail_response = requests.get(
            f"https://api.koywe.com/api/v1/organizations/{org_id}/merchants/{merchant_id}/accounts/{account_id}/reports/ledger-entry/{movement['ledgerEntryId']}",
            headers={'Authorization': f'Bearer {token}'}
        )
        
        receipt = detail_response.json()
        receipts.append(receipt)
        
        # Print receipt
        print('=' * 50)
        print('TRANSACTION RECEIPT')
        print('=' * 50)
        print(f"Entry ID:       {receipt['ledgerEntryId']}")
        print(f"Date:           {receipt['postedAt']}")
        print(f"Merchant:       {receipt['merchantName']}")
        print(f"Type:           {receipt['type'].upper()}")
        print(f"Category:       {receipt['category']}")
        print(f"Amount:         {receipt['amount']} {receipt['currency']}")
        print('-' * 50)
        print(f"Balance Before: {receipt['balanceBefore']} {receipt['currency']}")
        print(f"Balance After:  {receipt['balanceAfter']} {receipt['currency']}")
        print('-' * 50)
        print(f"Description:    {receipt['description']}")
        
        if receipt['references'].get('orderId'):
            print(f"Order ID:       {receipt['references']['orderId']}")
        if receipt['references'].get('settlementId'):
            print(f"Settlement ID:  {receipt['references']['settlementId']}")
        
        print('=' * 50)
    
    return receipts
 
# Usage
receipts = get_transaction_receipt(
    'org3_xxx',
    'mrc_xxx',
    'acc_xxx',
    '2025-01-15',
    token
)

Finding the Ledger Entry ID

The ledgerEntryId is available in the ledger statement response. Here’s how to find a specific entry:


// Find ledger entry by associated order
const statement = await getLedgerStatement(orgId, merchantId, accountId, from, to, token);
 
const targetOrderId = 'ord_abc123';
const entry = statement.movements.find(m => m.orderId === targetOrderId);
 
if (entry) {
  console.log(`Found entry ${entry.ledgerEntryId} for order ${targetOrderId}`);
  // Now fetch details
  const receipt = await getLedgerEntryDetails(orgId, merchantId, accountId, entry.ledgerEntryId, token);
}


// Find ledger entry by amount and approximate date
const statement = await getLedgerStatement(orgId, merchantId, accountId, from, to, token);
 
const targetAmount = '1000000.00';
const targetDate = '2025-01-15';
 
const entry = statement.movements.find(m => 
  m.amount === targetAmount && 
  m.postedAt.startsWith(targetDate)
);
 
if (entry) {
  console.log(`Found entry ${entry.ledgerEntryId}`);
}

Error Handling

Common Errors:

404 Not Found: Ledger entry ID doesn’t exist or doesn’t belong to the specified account
403 Forbidden: Entry doesn’t belong to the merchant or insufficient permissions
401 Unauthorized: Invalid or expired token


async function safeGetLedgerEntry(orgId, merchantId, accountId, entryId, token) {
  try {
    const response = await axios.get(
      `https://api.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/accounts/${accountId}/reports/ledger-entry/${entryId}`,
      {
        headers: { 'Authorization': `Bearer ${token}` }
      }
    );
    return response.data;
  } catch (error) {
    if (error.response?.status === 404) {
      console.error(`Ledger entry ${entryId} not found`);
      return null;
    }
    if (error.response?.status === 403) {
      console.error(`Access denied to ledger entry ${entryId}`);
      return null;
    }
    throw error;
  }
}

Next Steps

🧾Ledger Statement

Get the full account statement

✅Orders Report

Transaction-level reporting