Transaction Templates Reference
The Transaction Templates Service provides pre-built double-entry transaction patterns that automatically create balanced journal entries.
Templates Overview
| Template | Description | Double-Entry Pattern |
|---|---|---|
getUserTransferTemplate | P2P transfer between users | User Wallets ↔ User Wallets |
getUserPaymentTemplate | User pays vendor (with fee) | User Wallets → Vendor Wallets + Fee Revenue |
getUserTopupTemplate | User adds funds from external source | User Wallets ↔ Cash in Transit |
getUserWithdrawalTemplate | User withdraws cash at vendor | User Wallets → Vendor + Fee Revenue |
getVendorCommissionTemplate | Vendor earns commission | Commission Income → Vendor Wallets |
getUserRefundTemplate | Refund to user | Refund Expenses → User Wallets |
getAirtimePurchaseTemplate | Airtime purchase | User Wallets → Processing Costs |
getBillPaymentTemplate | Bill payment | User Wallets → Processing Costs |
getOpeningBalanceTemplate | Migration balance | Wallet → Retained Earnings |
getManualAdjustmentTemplate | Admin correction | Specified Account ↔ Retained Earnings |
getReversalTemplate | Reverse any entry | Swaps all debits/credits |
Template Details
1. User Transfer (P2P)
Transfers funds between two users.
| Parameter | Type | Required | Description |
|---|---|---|---|
senderId | string | Yes | Sender user ID |
recipientId | string | Yes | Recipient user ID |
amount | number | Yes | Amount in Emalageni |
reference | string | No | Transaction description |
Accounts: 1110 (User Wallets) - debit sender, credit recipient
2. User Payment (to Vendor)
User pays vendor with transaction fee.
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | Paying user ID |
vendorId | string | Yes | Receiving vendor ID |
amount | number | Yes | Payment amount |
fee | number | Yes | Transaction fee |
reference | string | No | Transaction description |
Accounts:
1110(User Wallets) - debit (amount + fee)1120(Vendor Wallets) - credit amount4110(Transaction Fee Revenue) - credit fee
3. User Topup
User adds funds from external source (mobile money, etc.).
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | User ID |
amount | number | Yes | Topup amount |
source | string | Yes | Payment source (e.g., "Mobile Money - MTN") |
Accounts:
1110(User Wallets) - debit1130(Cash in Transit) - credit
4. User Withdrawal
User withdraws cash at vendor location.
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | Withdrawing user ID |
vendorId | string | Yes | Payout vendor ID |
amount | number | Yes | Withdrawal amount |
fee | number | Yes | Withdrawal fee |
reference | string | No | Transaction description |
Accounts:
1110(User Wallets) - debit (amount + fee)1120(Vendor Wallets) - credit amount4120(Withdrawal Fee Revenue) - credit fee
5. Vendor Commission
Vendor earns commission from platform.
| Parameter | Type | Required | Description |
|---|---|---|---|
vendorId | string | Yes | Vendor ID |
amount | number | Yes | Commission amount |
description | string | Yes | Commission description |
Accounts:
4130(Commission Income) - debit1120(Vendor Wallets) - credit
6. User Refund
Refund a previous transaction.
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | User receiving refund |
amount | number | Yes | Refund amount |
reason | string | Yes | Refund reason |
originalTransactionId | string | No | Original transaction reference |
Accounts:
5120(Refund Expenses) - debit1110(User Wallets) - credit
7. Airtime Purchase
User purchases airtime through platform.
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | Purchasing user ID |
amount | number | Yes | Airtime amount |
provider | string | Yes | Network provider (MTN, etc.) |
phoneNumber | string | Yes | Recipient phone number |
Accounts:
1110(User Wallets) - debit5110(Processing Costs) - credit
8. Bill Payment
User pays utility bill (electricity, water, etc.).
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | Paying user ID |
amount | number | Yes | Bill amount |
billType | string | Yes | Bill type (Electricity, Water, etc.) |
accountNumber | string | Yes | Utility account number |
Accounts:
1110(User Wallets) - debit5110(Processing Costs) - credit
9. Opening Balance
Migrate historical balance for existing user/vendor (one-time migration).
| Parameter | Type | Required | Description |
|---|---|---|---|
entityId | string | Yes | User or Vendor ID |
entityType | string | Yes | "User" or "Vendor" |
balance | number | Yes | Existing balance to migrate |
description | string | Yes | Migration description |
Accounts:
1110/1120(Wallet) - debit balance3100(Retained Earnings) - credit balance
Use Case: One-time migration of existing wallet balances to new accounting system.
10. Manual Adjustment
Admin manual correction (use sparingly, requires approval).
| Parameter | Type | Required | Description |
|---|---|---|---|
entityId | string | Yes | User or Vendor ID |
entityType | string | Yes | "User" or "Vendor" |
accountCode | string | Yes | Target account code |
amount | number | Yes | Adjustment amount |
isDebit | boolean | Yes | true = increase, false = decrease |
reason | string | Yes | Adjustment reason |
adminId | string | Yes | Approving admin ID |
Accounts: Specified account ↔ 3100 (Retained Earnings)
Warning: Only use for corrections approved by finance team.
11. Reversal
Reverse any existing template.
| Parameter | Type | Required | Description |
|---|---|---|---|
originalTemplate | object | Yes | The template to reverse |
reason | string | Yes | Reversal reason |
Effect: Swaps all debits ↔ credits from the original template
Note: Prefer using ledgerService.reverseJournalEntry() for posted entries.
Account Codes Reference
| Code | Account Name | Type | Normal Balance |
|---|---|---|---|
1110 | User Wallets | Asset | Debit |
1120 | Vendor Wallets | Asset | Debit |
1130 | Cash in Transit | Asset | Debit |
3100 | Retained Earnings | Equity | Credit |
4110 | Transaction Fee Revenue | Revenue | Credit |
4120 | Withdrawal Fee Revenue | Revenue | Credit |
4130 | Commission Income | Revenue | Credit |
5110 | Processing Costs | Expense | Debit |
5120 | Refund Expenses | Expense | Debit |
Validation Rules
All templates are validated before journal creation:
- Balance Check: Total debits must equal total credits
- Account Existence: All account codes must exist in Chart of Accounts
- Amount Validation: All amounts must be > 0
- Currency Consistency: All amounts in Emalageni (E)
Best Practices
- Always use templates - Don't create journal entries manually
- Choose the right template - Use the most specific template available
- Provide references - Help with tracing and audit
- Use opening balances once - Only during migration
- Document manual adjustments - Require approval and clear reasoning
Related Documentation
- Ledger Service - Create journal entries from templates
- Integration Guide - Integration examples
- Accounting System - Understand double-entry