# Using the Profile Service with Billing — API Walkthrough

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.

## When to Use This Pattern

div
strong
Key idea:
br

  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


## Base URL

Production:


```
https://api.nelnetpay.com
```

## Step 1: Create a Billable Entity (service recipient)

A **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.”


### Request


```bash
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"
    }
  }'
```

### Response (example)


```json
{
  "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"
}
```

## Step 2: Create an Account (financial responsibility)

An **Account** represents who is financially responsible (for example, a household or sponsoring organization).

### Request


```bash
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"
    }
  }'
```

### Response (example)


```json
{
  "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"
}
```

## Step 3: Associate the Billable Entity to the Account

This links the recipient (Billable Entity) to the financially responsible Account.

### Request


```bash
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.

## Step 4: Create a Person (payer identity)

A **Person** represents an individual who may be assigned to an Account as a payer or contact.

### Request


```bash
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"
  }'
```

### Response (example)


```json
{
  "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"
}
```

## Step 5: Assign the Person as a Payer on the Account

Assign the Person to the Account as a payer. This is where “who can pay” becomes explicit.

### Request


```bash
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"
```

## Step 6: Tokenize a Payment Method (frontend)

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:


```json
{
  "token": "tok_abc123",
  "tokenType": "CARD"
}
```

> **Payment Widget** provides a user selectable check box to store the payment method once tokenized.


## Step 7: Store the Payment Method on the Person

Attach the token to the Person as a stored payment method.

`type` must be one of:

- `CARD`
- `ACH`
- `APPLE_PAY`


The merchant must be configured to process the supplied `type`.

### Request


```bash
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
  }'
```

### Response (example)


```json
{
  "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"
}
```

## Step 8 (Optional): Enable Auto-Pay for the Account

To enable auto-pay, update the payer record with:

- `autoPayEnabled: true`
- `autoPayPaymentMethodId: <paymentMethodId>`


> Only **one** payer per Account can have auto-pay enabled.


### Request


```bash
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"
  }'
```

## Tags (and why they matter)

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.

## Summary

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.