# Billing & Ledger Service API The Billing & Ledger Service is the financial engine of the NPS Billing Platform. It manages pricing (Rates, Rate Cards), subscription configurations, allocation rules for split billing scenarios (divorced households, subsidies), charge lifecycle, and double-entry accounting ledger. ## Key Concepts ### Charge Lifecycle Charges follow a strict lifecycle with immutability after invoicing: - **PENDING** → Created but not validated - **BILLED** → Validated and ready to invoice (still editable) - **INVOICED** → Invoiced (IMMUTABLE - moved to SettledCharge) - **PAID** → Paid directly without invoice - **VOID** → Cancelled ### Allocation Configuration Defines how charges are split between multiple accounts (e.g., divorced parents, subsidy agencies). Three rule types: - **RESPONSIBLE_PARTY**: Percentage-based split - **COVERAGE_TRANSFER**: Fixed amount covered (e.g., $25 subsidy per charge) - **BILLING_CAP**: Maximum amount per period ### Double-Entry Ledger All financial transactions follow the accounting equation (Debits = Credits). Journal entries are immutable once created - corrections use adjustment entries. ### Monetary Values All monetary amounts are stored as **DECIMAL type in cents** (e.g., 5000 = $50.00). Use DECIMAL or NUMERIC type (BigDecimal in Java) for precision and to avoid rounding errors. Never use integers or floating-point for money. Version: 1.0.0 ## Servers UAT server ``` https://api.uat.nelnetpay.com/billing ``` Production server ``` https://api.nelnetpay.com/billing ``` ## Security ### OAuth2 Type: oauth2 ## Download OpenAPI description [Billing & Ledger Service API](https://docs.nelnetpay.com/_bundle/apis/billing-ledger-service.yaml) ## Rates Manage rate catalog (pricing for services) ### List Rates - [GET /rates](https://docs.nelnetpay.com/apis/billing-ledger-service/rates/listrates.md): List all rates (pricing catalog) for the authenticated merchant with pagination and filtering. Rates define how much each type of service costs. ### Create Rate - [POST /rates](https://docs.nelnetpay.com/apis/billing-ledger-service/rates/createrate.md): Create a new rate in the pricing catalog. Rate Types: - service fee - Regular service fee/service fees - LATE_FEE - Late payment penalties - REGISTRATION - One-time registration fees - DISCOUNT - Discount rates (use discountPercentage instead of pricePerUnit) - OTHER - Miscellaneous charges ### Get Rate Details - [GET /rates/{rateId}](https://docs.nelnetpay.com/apis/billing-ledger-service/rates/getrate.md): Retrieve details of a specific rate ### Update Rate - [PATCH /rates/{rateId}](https://docs.nelnetpay.com/apis/billing-ledger-service/rates/updaterate.md): Update a rate's information (partial update). Note: Updating a rate does NOT affect existing charges or subscriptions. They retain the rate version from when they were created. ### Delete Rate - [DELETE /rates/{rateId}](https://docs.nelnetpay.com/apis/billing-ledger-service/rates/deleterate.md): Soft delete a rate (marked as deleted but retained for audit purposes). Restrictions: Cannot delete a rate that is referenced by active subscriptions or unbilled charges. ## RateCards Manage rate card groupings for UI organization ### List Rate Cards - [GET /rateCards](https://docs.nelnetpay.com/apis/billing-ledger-service/ratecards/listratecards.md): List all rate cards for the authenticated merchant. Rate cards group related rates for easier UI presentation and selection. ### Create Rate Card - [POST /rateCards](https://docs.nelnetpay.com/apis/billing-ledger-service/ratecards/createratecard.md): Create a new rate card to group related rates. Scope: - MERCHANT - Available to all accounts - ACCOUNT - Available to specific accounts only ### Get Rate Card Details - [GET /rateCards/{rateCardId}](https://docs.nelnetpay.com/apis/billing-ledger-service/ratecards/getratecard.md): Retrieve details of a specific rate card including associated rates ### Update Rate Card - [PATCH /rateCards/{rateCardId}](https://docs.nelnetpay.com/apis/billing-ledger-service/ratecards/updateratecard.md): Update a rate card's information (partial update) ### Delete Rate Card - [DELETE /rateCards/{rateCardId}](https://docs.nelnetpay.com/apis/billing-ledger-service/ratecards/deleteratecard.md): Delete a rate card (does not delete associated rates) ### Add Rate to Rate Card - [POST /rateCards/{rateCardId}/rates/{rateId}](https://docs.nelnetpay.com/apis/billing-ledger-service/ratecards/addratetoratecard.md): Associate a rate with a rate card (idempotent) ### Remove Rate from Rate Card - [DELETE /rateCards/{rateCardId}/rates/{rateId}](https://docs.nelnetpay.com/apis/billing-ledger-service/ratecards/removeratefromratecard.md): Remove a rate from a rate card (idempotent) ## Subscriptions Manage billable entity subscriptions to rates ### List Subscriptions - [GET /subscriptions](https://docs.nelnetpay.com/apis/billing-ledger-service/subscriptions/listsubscriptions.md): List all subscriptions for the authenticated merchant. Subscriptions link billable entities to rates with allocation configurations. ### Create Subscription - [POST /subscriptions](https://docs.nelnetpay.com/apis/billing-ledger-service/subscriptions/createsubscription.md): Create a new subscription linking a billable entity to a rate. Validation: The billable entity must be associated with ALL accounts referenced in the allocation configuration. This is validated via Profile Service. Billing Frequency: - DAILY - Charges generated daily - WEEKLY - Charges generated weekly (anchorDay = day of week 1-7) - BIWEEKLY - Charges generated every two weeks - MONTHLY - Charges generated monthly (anchorDay = day of month 1-31) ### Get Subscription Details - [GET /subscriptions/{subscriptionId}](https://docs.nelnetpay.com/apis/billing-ledger-service/subscriptions/getsubscription.md): Retrieve details of a specific subscription ### Update Subscription - [PATCH /subscriptions/{subscriptionId}](https://docs.nelnetpay.com/apis/billing-ledger-service/subscriptions/updatesubscription.md): Update a subscription's information (partial update). Version Tracking: Each update increments the subscription version. Existing charges retain the version from when they were created. ### Pause Subscription - [POST /subscriptions/{subscriptionId}/pause](https://docs.nelnetpay.com/apis/billing-ledger-service/subscriptions/pausesubscription.md): Pause a subscription to temporarily stop charge generation ### Resume Subscription - [POST /subscriptions/{subscriptionId}/resume](https://docs.nelnetpay.com/apis/billing-ledger-service/subscriptions/resumesubscription.md): Resume a paused subscription ### Cancel Subscription - [POST /subscriptions/{subscriptionId}/cancel](https://docs.nelnetpay.com/apis/billing-ledger-service/subscriptions/cancelsubscription.md): Cancel a subscription permanently. Note: This does not void existing charges. Use charge void endpoints for that. ## AllocationConfigurations Manage charge allocation configurations for split billing ### List Allocation Configurations - [GET /allocationConfigurations](https://docs.nelnetpay.com/apis/billing-ledger-service/allocationconfigurations/listallocationconfigurations.md): List all allocation configurations for the authenticated merchant. Allocation configurations define how charges are split between multiple accounts (e.g., divorced parents, household + subsidy agency). ### Create Allocation Configuration - [POST /allocationConfigurations](https://docs.nelnetpay.com/apis/billing-ledger-service/allocationconfigurations/createallocationconfiguration.md): Create a new allocation configuration with rules. Important: The total allocation percentage does NOT need to equal 100% at creation time. This allows for incremental household enrollment. Validation of 100% happens at charge creation time. Rule Types: - RESPONSIBLE_PARTY - Split by percentage (e.g., Mom 50%, Dad 50%) - COVERAGE_TRANSFER - Fixed amount covered (e.g., subsidy covers $25 per charge) - BILLING_CAP - Maximum amount per period (e.g., subsidy covers up to $400/month) Processing Order: Rules are processed in priority order (1 = first). COVERAGE_TRANSFER and BILLING_CAP typically run before RESPONSIBLE_PARTY. ### Get Allocation Configuration Details - [GET /allocationConfigurations/{allocationConfigId}](https://docs.nelnetpay.com/apis/billing-ledger-service/allocationconfigurations/getallocationconfiguration.md): Retrieve details of a specific allocation configuration including all rules ### Update Allocation Configuration - [PATCH /allocationConfigurations/{allocationConfigId}](https://docs.nelnetpay.com/apis/billing-ledger-service/allocationconfigurations/updateallocationconfiguration.md): Update an allocation configuration (partial update). Version Tracking: Each update increments the version. Existing charges and subscriptions retain the version from when they were created. ### Delete Allocation Configuration - [DELETE /allocationConfigurations/{allocationConfigId}](https://docs.nelnetpay.com/apis/billing-ledger-service/allocationconfigurations/deleteallocationconfiguration.md): Soft delete an allocation configuration. Restrictions: Cannot delete if referenced by active subscriptions or unbilled charges. ### Validate Allocation Configuration - [POST /allocationConfigurations/{allocationConfigId}/validate](https://docs.nelnetpay.com/apis/billing-ledger-service/allocationconfigurations/validateallocationconfiguration.md): Validate an allocation configuration for a specific billable entity. Validation Checks: 1. All accounts in allocation rules are associated with the billable entity 2. RESPONSIBLE_PARTY rules total 100% of remaining amount 3. No circular dependencies in rules Use this before creating charges to catch configuration issues early. ## Charges Manage billable charges (mutable pre-invoice state) ### List Charges - [GET /charges](https://docs.nelnetpay.com/apis/billing-ledger-service/charges/listcharges.md): List charges (mutable pre-invoice state) for the authenticated merchant. Status Filtering: - PENDING - Created but not validated - BILLED - Ready to invoice - VOID - Cancelled Charges with status INVOICED or PAID are in the SettledCharges table. ### Create Charge - [POST /charges](https://docs.nelnetpay.com/apis/billing-ledger-service/charges/createcharge.md): Create a new charge for a billable entity. Validation at Creation: 1. Fetches all accounts associated with billableEntityId (via Profile Service) 2. Validates billableEntity is associated with ALL accounts in allocationConfig 3. Validates allocationConfig covers 100% of ALL accounts for the billableEntity 4. Returns 422 if validation fails Charge Calculation: - amount = quantity × rate.pricePerUnit - proratedAmount = amount × prorationFactor - netAmount = proratedAmount - sum(discountAmounts) Idempotency: Include Idempotency-Key header to prevent duplicate charges. ### Get Charge Details - [GET /charges/{chargeId}](https://docs.nelnetpay.com/apis/billing-ledger-service/charges/getcharge.md): Retrieve details of a specific charge ### Update Charge - [PATCH /charges/{chargeId}](https://docs.nelnetpay.com/apis/billing-ledger-service/charges/updatecharge.md): Update a charge (partial update). Restrictions: Only charges with status PENDING or BILLED can be updated. Once a charge is INVOICED, it becomes immutable (moved to SettledCharges). ### Delete Charge - [DELETE /charges/{chargeId}](https://docs.nelnetpay.com/apis/billing-ledger-service/charges/deletecharge.md): Delete a charge (hard delete for PENDING, soft delete/void for BILLED). Restrictions: Cannot delete charges with status INVOICED or PAID. Use ledger adjustments for corrections to invoiced charges. ### Void Charge - [POST /charges/{chargeId}/void](https://docs.nelnetpay.com/apis/billing-ledger-service/charges/voidcharge.md): Void a charge (sets status to VOID). Use Case: When a charge was created in error but you want to keep audit trail. ### Create Multiple Charges - [POST /charges/bulk](https://docs.nelnetpay.com/apis/billing-ledger-service/charges/createchargesbulk.md): Create multiple charges in a single request. Use Case: Creating charges for multiple billable entities at once (e.g., batch from recurring billing). Atomicity: All charges are created in a single transaction. If any fails, all are rolled back. ## SettledCharges Query settled charges (immutable post-invoice state) ### List Settled Charges - [GET /settledCharges](https://docs.nelnetpay.com/apis/billing-ledger-service/settledcharges/listsettledcharges.md): List settled charges (immutable post-invoice/payment state). Settled charges are created when: - A charge is invoiced (settlementType: INVOICED) - A charge is paid directly without invoice (settlementType: DIRECT_PAYMENT) Note: Settled charges are IMMUTABLE. Corrections must be made via ledger adjustments. ### Get Settled Charge Details - [GET /settledCharges/{settledChargeId}](https://docs.nelnetpay.com/apis/billing-ledger-service/settledcharges/getsettledcharge.md): Retrieve details of a specific settled charge. Includes frozen snapshots of: - resolvedRate - Rate details at time of settlement - resolvedAllocation - Allocation details at time of settlement - consolidatedTags - Tags from all sources (profile, rate, subscription, charge) ## Refunds Manage refunds for invoices, charges, or standalone refunds ### Create Refund - [POST /refunds](https://docs.nelnetpay.com/apis/billing-ledger-service/refunds/createrefund.md): Initiate a refund for one or more invoices, charges, or as a standalone refund. Refund Types: - Invoice Refund: Refund one or more invoices - Charge Refund: Refund one or more specific charges - Standalone Refund: Refund without reference to an invoice/charge Process: 1. Refund request is validated 2. Billing Service calls Payment API to process refund 3. On success, journal entries are created (DR Refund Expense, CR Bank) 4. Optionally, receipt is sent via Receipt Service ### List Refunds - [GET /refunds](https://docs.nelnetpay.com/apis/billing-ledger-service/refunds/listrefunds.md): List all refunds with pagination and filtering ### Get Refund - [GET /refunds/{refundId}](https://docs.nelnetpay.com/apis/billing-ledger-service/refunds/getrefund.md): Retrieve details of a specific refund ### Get Refund Status - [GET /refunds/{refundId}/status](https://docs.nelnetpay.com/apis/billing-ledger-service/refunds/getrefundstatus.md): Get the processing status of a refund ## Adjustments Manage manual adjustments and corrections ### Create Manual Adjustment - [POST /adjustments](https://docs.nelnetpay.com/apis/billing-ledger-service/adjustments/createadjustment.md): Create a manual adjustment to correct ledger entries. Adjustment Types: - DISCOUNT_CORRECTION - Fix discount calculation error - FEE_CORRECTION - Adjust fee amount - CREDIT_MEMO - Issue credit to account - DEBIT_MEMO - Charge additional amount - WRITE_OFF - Bad debt write-off Authorization: Requires special permission level for manual adjustments. All adjustments include a full audit trail. ### List Adjustments - [GET /adjustments](https://docs.nelnetpay.com/apis/billing-ledger-service/adjustments/listadjustments.md): List all manual adjustments with pagination and filtering ### Get Adjustment - [GET /adjustments/{adjustmentId}](https://docs.nelnetpay.com/apis/billing-ledger-service/adjustments/getadjustment.md): Retrieve details of a specific adjustment ## Ledger Manage double-entry accounting ledger ### List Journal Entries - [GET /ledger/journalEntries](https://docs.nelnetpay.com/apis/billing-ledger-service/ledger/listjournalentries.md): List journal entries (double-entry accounting records). Sources: - INVOICE - Created when invoice is posted (DR: A/R, CR: Revenue) - PAYMENT - Created when payment is received (DR: Bank, CR: A/R) - REFUND - Created when refund is processed - ADJUSTMENT - Manual corrections - REMITTANCE - Payment processor fee tracking ### Create Journal Entry - [POST /ledger/journalEntries](https://docs.nelnetpay.com/apis/billing-ledger-service/ledger/createjournalentry.md): Create a new journal entry with lines. Double-Entry Rule: Sum of debits MUST equal sum of credits. The entry will be rejected if not balanced. Immutability: Journal entries are immutable once created. Use adjustment entries for corrections. Account Codes: - REVENUE - Revenue accounts - AR - Accounts Receivable - CONTRA_REVENUE - Contra-revenue (discounts) - CLEARING - Clearing accounts - BANK - Bank accounts - FEE_EXPENSE - Processing fee expenses - REFUND_EXPENSE - Refund expenses ### Get Journal Entry Details - [GET /ledger/journalEntries/{journalEntryId}](https://docs.nelnetpay.com/apis/billing-ledger-service/ledger/getjournalentry.md): Retrieve details of a specific journal entry including all lines ### Get Account Balances - [GET /ledger/accountBalances](https://docs.nelnetpay.com/apis/billing-ledger-service/ledger/getaccountbalances.md): Get current balances for all ledger account codes. Useful for reconciliation and financial reporting. ### Get Trial Balance - [GET /ledger/trialBalance](https://docs.nelnetpay.com/apis/billing-ledger-service/ledger/gettrialbalance.md): Get trial balance report showing all accounts with their debit and credit totals. Validation: Debit total should equal credit total. ### Journal Entry Created - [POST ledgerJournalEntryCreated](https://docs.nelnetpay.com/apis/billing-ledger-service/ledger/webhookjournalentrycreated.md): Fired when a new journal entry is created. Use Cases: - Real-time GL integration - Audit trail synchronization - External accounting system updates Security: Payload is signed with HMAC-SHA256. Verify using the X-NPS-Signature header. ## Exports Export data in CSV format for GL integrations ### Export Charges to CSV - [GET /exports/charges](https://docs.nelnetpay.com/apis/billing-ledger-service/exports/exportcharges.md): Export charges to CSV format. Includes both mutable charges and settled charges based on filters. ### Export Ledger Entries to CSV - [GET /exports/ledgerEntries](https://docs.nelnetpay.com/apis/billing-ledger-service/exports/exportledgerentries.md): Export journal entries and lines to CSV format for GL integration. Format: Mirrors webhook event structure for consistency. Can be directly imported into QuickBooks, Xero, Sage Intacct, etc.