This walkthrough shows how to set up Profile Service data in a way that works cleanly with Billing & Ledger and Invoicing.
You’ll build the core billing identity graph:
- Billable Entity (who received the service)
- Account (who is financially responsible)
- Payer (who is authorized to pay)
- Stored payment method (token attached to the payer)
All API calls use Bearer JWT authentication (API keys → JWT), same as other NPS services.
Billing and invoicing require Accounts + Billable Entities so responsibility and downstream documents are explicit.
Use this flow when you need:
- Charges and balances tied to an Account
- Invoices/receipts that reference a payer and recipient
- Recurring billing / auto-pay configuration
Production:
https://api.nelnetpay.comA Billable Entity represents the person or recipient the service was rendered to (for example, a child/student).
In billing workflows, this is commonly “the one receiving the service,” not “the payer.”
curl -X POST https://api.nelnetpay.com/billable-entities -H "Authorization: Bearer <JWT>" -H "Content-Type: application/json" -d '{
"externalReferenceId": "child_00042",
"firstName": "Ava",
"lastName": "Doe",
"displayName": "Ava Doe",
"tags": {
"schoolYear": "2026",
"source": "sis"
}
}'{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"entityId": "c3073b9d-ed0a-49f2-a28d-b7edd8ff9a8b",
"externalReferenceId": "child_00042",
"firstName": "Ava",
"lastName": "Doe",
"displayName": "Ava Doe",
"tags": {
"schoolYear": "2026",
"source": "sis"
},
"createdAt": "2026-01-15T14:12:22Z",
"updatedAt": "2026-01-15T14:12:22Z"
}An Account represents who is financially responsible (for example, a household or sponsoring organization).
curl -X POST https://api.nelnetpay.com/accounts -H "Authorization: Bearer <JWT>" -H "Content-Type: application/json" -d '{
"name": "Doe Household",
"externalReferenceId": "acct_household_123",
"isBillable": true,
"tags": {
"customerGroup": "household"
}
}'{
"id": "123e4567-e89b-12d3-a456-426614174000",
"entityId": "c3073b9d-ed0a-49f2-a28d-b7edd8ff9a8b",
"name": "Doe Household",
"externalReferenceId": "acct_household_123",
"isBillable": true,
"tags": {
"customerGroup": "household"
},
"createdAt": "2026-01-15T14:18:10Z",
"updatedAt": "2026-01-15T14:18:10Z"
}This links the recipient (Billable Entity) to the financially responsible Account.
curl -X POST https://api.nelnetpay.com/accounts/123e4567-e89b-12d3-a456-426614174000/billable-entities/497f6eca-6276-4993-bfeb-53cbbbba6f08 -H "Authorization: Bearer <JWT>"This operation is an association call and does not require a request body.
A Person represents an individual who may be assigned to an Account as a payer or contact.
curl -X POST https://api.nelnetpay.com/people -H "Authorization: Bearer <JWT>" -H "Content-Type: application/json" -d '{
"firstName": "Jane",
"lastName": "Doe",
"email": "jane.doe@example.com",
"phone": "4025550100",
"address": "123 Main St",
"city": "Lincoln",
"state": "NE",
"postalCode": "68508"
}'{
"id": "7f6e1b8d-9f87-4d8a-8c8a-4ad0d6b8f1f1",
"entityId": "c3073b9d-ed0a-49f2-a28d-b7edd8ff9a8b",
"firstName": "Jane",
"lastName": "Doe",
"email": "jane.doe@example.com",
"phone": "4025550100",
"address": "123 Main St",
"city": "Lincoln",
"state": "NE",
"postalCode": "68508",
"createdAt": "2026-01-15T14:21:55Z",
"updatedAt": "2026-01-15T14:21:55Z"
}Assign the Person to the Account as a payer. This is where “who can pay” becomes explicit.
curl -X POST https://api.nelnetpay.com/accounts/123e4567-e89b-12d3-a456-426614174000/payers/7f6e1b8d-9f87-4d8a-8c8a-4ad0d6b8f1f1 -H "Authorization: Bearer <JWT>" -H "Content-Type: application/json" Use the Hosted Tokenization Iframe to collect payment credentials securely in the browser.
At the end of tokenization, you receive an NPS token such as:
{
"token": "tok_abc123",
"tokenType": "CARD"
}Payment Widget provides a user selectable check box to store the payment method once tokenized.
Attach the token to the Person as a stored payment method.
type must be one of:
CARDACHAPPLE_PAY
The merchant must be configured to process the supplied type.
curl -X POST https://api.nelnetpay.com/people/7f6e1b8d-9f87-4d8a-8c8a-4ad0d6b8f1f1/payment-methods -H "Authorization: Bearer <JWT>" -H "Content-Type: application/json" -d '{
"token": "tok_abc123",
"type": "CARD",
"label": "Visa ending in 4242",
"isDefault": true
}'{
"id": "2b2f7d2a-9fcb-4a52-a2f2-5a1d0a1b2c3d",
"personId": "7f6e1b8d-9f87-4d8a-8c8a-4ad0d6b8f1f1",
"token": "tok_abc123",
"type": "CARD",
"label": "Visa ending in 4242",
"isDefault": true,
"createdAt": "2026-01-15T14:30:01Z",
"updatedAt": "2026-01-15T14:30:01Z"
}To enable auto-pay, update the payer record with:
autoPayEnabled: trueautoPayPaymentMethodId: <paymentMethodId>
Only one payer per Account can have auto-pay enabled.
curl -X PATCH https://api.nelnetpay.com/accounts/123e4567-e89b-12d3-a456-426614174000/payers/7f6e1b8d-9f87-4d8a-8c8a-4ad0d6b8f1f1 -H "Authorization: Bearer <JWT>" -H "Content-Type: application/json" -d '{
"autoPayEnabled": true,
"autoPayPaymentMethodId": "2b2f7d2a-9fcb-4a52-a2f2-5a1d0a1b2c3d"
}'The Profile Service supports custom tags (key/value metadata) on Accounts and Billable Entities.
Tags are commonly used for:
- Client/partner metadata
- Audit and traceability
- Reporting enrichment
- Cross-service context propagation
When used with billing workflows, tags are designed to be consolidated when referenced by downstream services (for example, Billable Entity tags and configured rate tags combined into a resulting charge).
A dedicated Tagging article is planned; for now, refer to the Tagging section of the Billing Platform Overview.
You created a billing-ready Profile model:
- Billable Entity (recipient) ✅
- Account (responsible party) ✅
- Payer (authorized to pay) ✅
- Tokenized payment method stored on the payer ✅
- Optional auto-pay configured ✅
From here, Billing & Ledger can create charges against the Account, and Payments can process token-based transactions for authorized payers.