Skip to content
API & References
/
Billing & Ledger
/
/
Get Refund

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

Create Refund

Request

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
Security
OAuth2
Bodyapplication/jsonrequired
refundTypestringrequired

Type of refund to process

Enum"INVOICE""CHARGE""STANDALONE"
invoiceIdsArray of strings(uuid)

Invoice IDs to refund (required if refundType is INVOICE)

chargeIdsArray of strings(uuid)

Charge IDs to refund (required if refundType is CHARGE)

accountIdstring(uuid)

Account to refund to (required for STANDALONE)

amountinteger>= 1required

Refund amount in cents

reasonstring<= 500 characters

Reason for the refund

sendReceiptboolean

Whether to send a receipt via Receipt Service

Default false
metadataobject

Additional metadata for the refund

curl -i -X POST \
  https://docs.nelnetpay.com/_mock/apis/billing-ledger-service/refunds \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "refundType": "INVOICE",
    "invoiceIds": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "chargeIds": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
    "amount": 1,
    "reason": "string",
    "sendReceipt": false,
    "metadata": {
      "property1": "string",
      "property2": "string"
    }
  }'

Responses

Refund created successfully

Bodyapplication/json
idstring(uuid)required
entityIdstring(uuid)required
refundTypestringrequired
Enum"INVOICE""CHARGE""STANDALONE"
invoiceIdsArray of strings(uuid)
chargeIdsArray of strings(uuid)
accountIdstring(uuid)
amountintegerrequired
statusstringrequired
Enum"PENDING""PROCESSING""COMPLETED""FAILED""CANCELLED"
reasonstring
paymentTransactionIdstring

Payment gateway transaction ID

journalEntryIdstring(uuid)

Linked journal entry

failureReasonstring

Reason for failure (if status is FAILED)

metadataobject
optimisticLockVersioninteger(int64)read-only

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

createdAtstring(date-time)required
updatedAtstring(date-time)
completedAtstring(date-time)
Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "entityId": "156e622c-6cdf-4c27-9bc9-2f2db69919f5",
  "refundType": "INVOICE",
  "invoiceIds": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "chargeIds": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  "amount": 0,
  "status": "PENDING",
  "reason": "string",
  "paymentTransactionId": "string",
  "journalEntryId": "72600ee4-b304-47f3-89cd-f685d2692490",
  "failureReason": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "optimisticLockVersion": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "completedAt": "2019-08-24T14:15:22Z"
}

List Refunds

Request

List all refunds with pagination and filtering

Security
OAuth2
Query
statusstring
Enum"PENDING""PROCESSING""COMPLETED""FAILED""CANCELLED"
refund_typestring
Enum"INVOICE""CHARGE""STANDALONE"
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/refunds?status=PENDING&refund_type=INVOICE&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[].​refundTypestringrequired
Enum"INVOICE""CHARGE""STANDALONE"
results[].​invoiceIdsArray of strings(uuid)
results[].​chargeIdsArray of strings(uuid)
results[].​accountIdstring(uuid)
results[].​amountintegerrequired
results[].​statusstringrequired
Enum"PENDING""PROCESSING""COMPLETED""FAILED""CANCELLED"
results[].​reasonstring
results[].​paymentTransactionIdstring

Payment gateway transaction ID

results[].​journalEntryIdstring(uuid)

Linked journal entry

results[].​failureReasonstring

Reason for failure (if status is FAILED)

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

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

results[].​createdAtstring(date-time)required
results[].​updatedAtstring(date-time)
results[].​completedAtstring(date-time)
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
  }
}

Get Refund

Request

Retrieve details of a specific refund

Security
OAuth2
Path
refundIdstring(uuid)required
curl -i -X GET \
  'https://docs.nelnetpay.com/_mock/apis/billing-ledger-service/refunds/{refundId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful response

Bodyapplication/json
idstring(uuid)required
entityIdstring(uuid)required
refundTypestringrequired
Enum"INVOICE""CHARGE""STANDALONE"
invoiceIdsArray of strings(uuid)
chargeIdsArray of strings(uuid)
accountIdstring(uuid)
amountintegerrequired
statusstringrequired
Enum"PENDING""PROCESSING""COMPLETED""FAILED""CANCELLED"
reasonstring
paymentTransactionIdstring

Payment gateway transaction ID

journalEntryIdstring(uuid)

Linked journal entry

failureReasonstring

Reason for failure (if status is FAILED)

metadataobject
optimisticLockVersioninteger(int64)read-only

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

createdAtstring(date-time)required
updatedAtstring(date-time)
completedAtstring(date-time)
Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "entityId": "156e622c-6cdf-4c27-9bc9-2f2db69919f5",
  "refundType": "INVOICE",
  "invoiceIds": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "chargeIds": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  "amount": 0,
  "status": "PENDING",
  "reason": "string",
  "paymentTransactionId": "string",
  "journalEntryId": "72600ee4-b304-47f3-89cd-f685d2692490",
  "failureReason": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "optimisticLockVersion": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "completedAt": "2019-08-24T14:15:22Z"
}

Get Refund Status

Request

Get the processing status of a refund

Security
OAuth2
Path
refundIdstring(uuid)required
curl -i -X GET \
  'https://docs.nelnetpay.com/_mock/apis/billing-ledger-service/refunds/{refundId}/status' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful response

Bodyapplication/json
refundIdstring(uuid)required
statusstringrequired
Enum"PENDING""PROCESSING""COMPLETED""FAILED""CANCELLED"
paymentGatewayStatusstring

Status from payment gateway

lastCheckedAtstring(date-time)
Response
application/json
{
  "refundId": "3324897f-393a-4bf6-b3af-0b999cbc2521",
  "status": "PENDING",
  "paymentGatewayStatus": "string",
  "lastCheckedAt": "2019-08-24T14:15:22Z"
}

Adjustments

Manage manual adjustments and corrections

Operations

Ledger

Manage double-entry accounting ledger

Operations
Webhooks

Exports

Export data in CSV format for GL integrations

Operations