Skip to content
API & References
/
Billing & Ledger
/
/
Get Journal Entry Details

Billing & Ledger Service API (1.0.0)

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.

Download OpenAPI description
billing-ledger-service.json
billing-ledger-service.yaml
Languages
Servers
Mock server
https://docs.nelnetpay.com/_mock/apis/billing-ledger-service
UAT server
https://api.uat.nelnetpay.com/billing
Production server
https://api.nelnetpay.com/billing

Rates

Manage rate catalog (pricing for services)

Operations

RateCards

Manage rate card groupings for UI organization

Operations

Subscriptions

Manage billable entity subscriptions to rates

Operations

AllocationConfigurations

Manage charge allocation configurations for split billing

Operations

Charges

Manage billable charges (mutable pre-invoice state)

Operations

SettledCharges

Query settled charges (immutable post-invoice state)

Operations

Refunds

Manage refunds for invoices, charges, or standalone refunds

Operations

Adjustments

Manage manual adjustments and corrections

Operations

Ledger

Manage double-entry accounting ledger

Operations
Webhooks

List Journal Entries

Request

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
Security
OAuth2
Query
sourcestring

Filter by journal entry source

Enum"INVOICE""PAYMENT""REFUND""ADJUSTMENT""REMITTANCE"
entry_date_fromstring(date-time)

Filter journal entries on or after this date

entry_date_tostring(date-time)

Filter journal entries on or before this date

source_referencestring

Filter by source reference (e.g., invoice ID)

pageinteger>= 1

Page number (1-indexed)

Default 1
Example: page=1
page_sizeinteger[ 1 .. 200 ]

Number of items per page

Default 50
Example: page_size=50
curl -i -X GET \
  'https://docs.nelnetpay.com/_mock/apis/billing-ledger-service/ledger/journalEntries?source=INVOICE&entry_date_from=2019-08-24T14%3A15%3A22Z&entry_date_to=2019-08-24T14%3A15%3A22Z&source_reference=string&page=1&page_size=50' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful response

Bodyapplication/json
resultsArray of objectsrequired
results[].​idstring(uuid)required
results[].​entityIdstring(uuid)required
results[].​entryDatestring(date-time)required
results[].​currencystringrequired

ISO 4217 currency code

Default "USD"
results[].​sourcestringrequired

Source of journal entry

Enum"INVOICE""PAYMENT""REFUND""ADJUSTMENT""REMITTANCE"
results[].​sourceReferencestring

Reference to source document (e.g., invoice ID)

results[].​referencesobject

Nested map of invoice IDs to charge IDs for tracing. Structure: { "invoiceId": ["chargeId1", "chargeId2"], ... } Enables tracking when a payment applies to multiple invoices.

results[].​adjustmentTypestring

Type of adjustment for manual entries

Enum"STANDARD""DISCOUNT_CORRECTION""FEE_CORRECTION""CREDIT_MEMO""DEBIT_MEMO""WRITE_OFF"
results[].​reasonstring

Reason for adjustment (if applicable)

results[].​adminUserIdstring

Admin user who created the entry (for adjustments)

results[].​relatedSourceRefstring

Reference to related entries

results[].​totalAmountintegerrequired

Total amount of the entry in cents

results[].​isBalancedbooleanrequired

Whether debits equal credits

results[].​linesArray of objectsrequired
results[].​lines[].​idstring(uuid)required
results[].​lines[].​accountCodestringrequired

Chart of accounts code

Enum"REVENUE""AR""CONTRA_REVENUE""CLEARING""BANK""FEE_EXPENSE""REFUND_EXPENSE"
results[].​lines[].​externalAccountCodestring

External GL account code for export

results[].​lines[].​directionstringrequired

Direction of journal line

Enum"DEBIT""CREDIT"
results[].​lines[].​amountintegerrequired

Amount in cents (always positive)

results[].​lines[].​descriptionstring
results[].​lines[].​billableEntityIdstring(uuid)
results[].​lines[].​accountIdstring(uuid)
results[].​lines[].​invoiceIdstring(uuid)
results[].​lines[].​dimensionsobject

Reporting dimensions

results[].​lines[].​tagsobject
results[].​optimisticLockVersioninteger(int64)read-only

Optimistic locking version (managed by Hibernate @Version). Prevents concurrent update conflicts.

results[].​createdAtstring(date-time)required
paginationobjectrequired
pagination.​totalRecordsintegerrequired

Total number of records across all pages

Example: 100
pagination.​currentPageintegerrequired

Current page number (1-indexed)

Example: 1
pagination.​totalPagesintegerrequired

Total number of pages

Example: 10
pagination.​nextPageinteger or null

Next page number, null if on last page

Example: 2
pagination.​prevPageinteger or null

Previous page number, null if on first page

Example: null
Response
application/json
{
  "results": [
    { … }
  ],
  "pagination": {
    "totalRecords": 100,
    "currentPage": 1,
    "totalPages": 10,
    "nextPage": 2,
    "prevPage": null
  }
}

Create Journal Entry

Request

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
Security
OAuth2
Headers
Idempotency-Keystring(uuid)

Unique key to ensure idempotent operations (UUID recommended)

Bodyapplication/jsonrequired
entryDatestring(date-time)required
currencystring
Default "USD"
sourcestringrequired

Source of journal entry

Enum"INVOICE""PAYMENT""REFUND""ADJUSTMENT""REMITTANCE"
sourceReferencestring
adjustmentTypestring

Type of adjustment for manual entries

Enum"STANDARD""DISCOUNT_CORRECTION""FEE_CORRECTION""CREDIT_MEMO""DEBIT_MEMO""WRITE_OFF"
reasonstring<= 1000 characters
relatedSourceRefstring
linesArray of objects>= 2 itemsrequired
lines[].​accountCodestringrequired

Chart of accounts code

Enum"REVENUE""AR""CONTRA_REVENUE""CLEARING""BANK""FEE_EXPENSE""REFUND_EXPENSE"
lines[].​externalAccountCodestring
lines[].​directionstringrequired

Direction of journal line

Enum"DEBIT""CREDIT"
lines[].​amountinteger>= 1required
lines[].​descriptionstring
lines[].​billableEntityIdstring(uuid)
lines[].​accountIdstring(uuid)
lines[].​invoiceIdstring(uuid)
lines[].​dimensionsobject
lines[].​tagsobject
curl -i -X POST \
  https://docs.nelnetpay.com/_mock/apis/billing-ledger-service/ledger/journalEntries \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -d '{
    "entryDate": "2026-01-20T10:30:00Z",
    "currency": "USD",
    "source": "ADJUSTMENT",
    "sourceReference": "ADJ-2026-001",
    "adjustmentType": "DISCOUNT_CORRECTION",
    "reason": "Applied missing sibling discount",
    "lines": [
      {
        "accountCode": "CONTRA_REVENUE",
        "direction": "DEBIT",
        "amount": 1000,
        "description": "Sibling discount correction",
        "accountId": "550e8400-e29b-41d4-a716-446655440031"
      },
      {
        "accountCode": "AR",
        "direction": "CREDIT",
        "amount": 1000,
        "description": "Reduce A/R for discount",
        "accountId": "550e8400-e29b-41d4-a716-446655440031"
      }
    ]
  }'

Responses

Journal entry created successfully

Bodyapplication/json
idstring(uuid)required
entityIdstring(uuid)required
entryDatestring(date-time)required
currencystringrequired

ISO 4217 currency code

Default "USD"
sourcestringrequired

Source of journal entry

Enum"INVOICE""PAYMENT""REFUND""ADJUSTMENT""REMITTANCE"
sourceReferencestring

Reference to source document (e.g., invoice ID)

referencesobject

Nested map of invoice IDs to charge IDs for tracing. Structure: { "invoiceId": ["chargeId1", "chargeId2"], ... } Enables tracking when a payment applies to multiple invoices.

adjustmentTypestring

Type of adjustment for manual entries

Enum"STANDARD""DISCOUNT_CORRECTION""FEE_CORRECTION""CREDIT_MEMO""DEBIT_MEMO""WRITE_OFF"
reasonstring

Reason for adjustment (if applicable)

adminUserIdstring

Admin user who created the entry (for adjustments)

relatedSourceRefstring

Reference to related entries

totalAmountintegerrequired

Total amount of the entry in cents

isBalancedbooleanrequired

Whether debits equal credits

linesArray of objectsrequired
lines[].​idstring(uuid)required
lines[].​accountCodestringrequired

Chart of accounts code

Enum"REVENUE""AR""CONTRA_REVENUE""CLEARING""BANK""FEE_EXPENSE""REFUND_EXPENSE"
lines[].​externalAccountCodestring

External GL account code for export

lines[].​directionstringrequired

Direction of journal line

Enum"DEBIT""CREDIT"
lines[].​amountintegerrequired

Amount in cents (always positive)

lines[].​descriptionstring
lines[].​billableEntityIdstring(uuid)
lines[].​accountIdstring(uuid)
lines[].​invoiceIdstring(uuid)
lines[].​dimensionsobject

Reporting dimensions

lines[].​tagsobject
optimisticLockVersioninteger(int64)read-only

Optimistic locking version (managed by Hibernate @Version). Prevents concurrent update conflicts.

createdAtstring(date-time)required
Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "entityId": "156e622c-6cdf-4c27-9bc9-2f2db69919f5",
  "entryDate": "2019-08-24T14:15:22Z",
  "currency": "USD",
  "source": "INVOICE",
  "sourceReference": "string",
  "references": {
    "property1": [ … ],
    "property2": [ … ]
  },
  "adjustmentType": "STANDARD",
  "reason": "string",
  "adminUserId": "string",
  "relatedSourceRef": "string",
  "totalAmount": 0,
  "isBalanced": true,
  "lines": [
    { … }
  ],
  "optimisticLockVersion": 0,
  "createdAt": "2019-08-24T14:15:22Z"
}

Get Journal Entry Details

Request

Retrieve details of a specific journal entry including all lines

Security
OAuth2
Path
journalEntryIdstring(uuid)required

Unique identifier for the journal entry

curl -i -X GET \
  'https://docs.nelnetpay.com/_mock/apis/billing-ledger-service/ledger/journalEntries/{journalEntryId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful response

Bodyapplication/json
idstring(uuid)required
entityIdstring(uuid)required
entryDatestring(date-time)required
currencystringrequired

ISO 4217 currency code

Default "USD"
sourcestringrequired

Source of journal entry

Enum"INVOICE""PAYMENT""REFUND""ADJUSTMENT""REMITTANCE"
sourceReferencestring

Reference to source document (e.g., invoice ID)

referencesobject

Nested map of invoice IDs to charge IDs for tracing. Structure: { "invoiceId": ["chargeId1", "chargeId2"], ... } Enables tracking when a payment applies to multiple invoices.

adjustmentTypestring

Type of adjustment for manual entries

Enum"STANDARD""DISCOUNT_CORRECTION""FEE_CORRECTION""CREDIT_MEMO""DEBIT_MEMO""WRITE_OFF"
reasonstring

Reason for adjustment (if applicable)

adminUserIdstring

Admin user who created the entry (for adjustments)

relatedSourceRefstring

Reference to related entries

totalAmountintegerrequired

Total amount of the entry in cents

isBalancedbooleanrequired

Whether debits equal credits

linesArray of objectsrequired
lines[].​idstring(uuid)required
lines[].​accountCodestringrequired

Chart of accounts code

Enum"REVENUE""AR""CONTRA_REVENUE""CLEARING""BANK""FEE_EXPENSE""REFUND_EXPENSE"
lines[].​externalAccountCodestring

External GL account code for export

lines[].​directionstringrequired

Direction of journal line

Enum"DEBIT""CREDIT"
lines[].​amountintegerrequired

Amount in cents (always positive)

lines[].​descriptionstring
lines[].​billableEntityIdstring(uuid)
lines[].​accountIdstring(uuid)
lines[].​invoiceIdstring(uuid)
lines[].​dimensionsobject

Reporting dimensions

lines[].​tagsobject
optimisticLockVersioninteger(int64)read-only

Optimistic locking version (managed by Hibernate @Version). Prevents concurrent update conflicts.

createdAtstring(date-time)required
Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "entityId": "156e622c-6cdf-4c27-9bc9-2f2db69919f5",
  "entryDate": "2019-08-24T14:15:22Z",
  "currency": "USD",
  "source": "INVOICE",
  "sourceReference": "string",
  "references": {
    "property1": [ … ],
    "property2": [ … ]
  },
  "adjustmentType": "STANDARD",
  "reason": "string",
  "adminUserId": "string",
  "relatedSourceRef": "string",
  "totalAmount": 0,
  "isBalanced": true,
  "lines": [
    { … }
  ],
  "optimisticLockVersion": 0,
  "createdAt": "2019-08-24T14:15:22Z"
}

Get Account Balances

Request

Get current balances for all ledger account codes.

Useful for reconciliation and financial reporting.

Security
OAuth2
Query
as_of_datestring(date-time)

Get balances as of this date (defaults to current)

curl -i -X GET \
  'https://docs.nelnetpay.com/_mock/apis/billing-ledger-service/ledger/accountBalances?as_of_date=2019-08-24T14%3A15%3A22Z' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful response

Bodyapplication/json
asOfDatestring(date-time)
balancesArray of objects
Response
application/json
{
  "asOfDate": "2019-08-24T14:15:22Z",
  "balances": [
    { … }
  ]
}

Get Trial Balance

Request

Get trial balance report showing all accounts with their debit and credit totals.

Validation: Debit total should equal credit total.

Security
OAuth2
Query
from_datestring(date)

Start date for the period

to_datestring(date)

End date for the period

curl -i -X GET \
  'https://docs.nelnetpay.com/_mock/apis/billing-ledger-service/ledger/trialBalance?from_date=2019-08-24&to_date=2019-08-24' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful response

Bodyapplication/json
periodStartstring(date)
periodEndstring(date)
accountsArray of objects
totalDebitsinteger
totalCreditsinteger
isBalancedboolean
Response
application/json
{
  "periodStart": "2019-08-24",
  "periodEnd": "2019-08-24",
  "accounts": [
    { … }
  ],
  "totalDebits": 0,
  "totalCredits": 0,
  "isBalanced": true
}

Journal Entry CreatedWebhook

Request

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.

Bodyapplication/jsonrequired
idstring(uuid)

Unique event ID (use for idempotency)

typestring
Value"ledger.journal_entry.created"
occurredAtstring(date-time)
dataobject
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "type": "ledger.journal_entry.created",
  "occurredAt": "2019-08-24T14:15:22Z",
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "entityId": "156e622c-6cdf-4c27-9bc9-2f2db69919f5",
    "entryDate": "2019-08-24T14:15:22Z",
    "currency": "USD",
    "source": "INVOICE",
    "sourceReference": "string",
    "references": { … },
    "adjustmentType": "STANDARD",
    "reason": "string",
    "adminUserId": "string",
    "relatedSourceRef": "string",
    "totalAmount": 0,
    "isBalanced": true,
    "lines": [ … ],
    "optimisticLockVersion": 0,
    "createdAt": "2019-08-24T14:15:22Z"
  }
}

Responses

Webhook processed successfully

Exports

Export data in CSV format for GL integrations

Operations