# Migration Guide for Existing Clients

This guide provides guidance for clients migrating from **legacy Direct** integrations to the **Nelnet Payment Services (NPS) Payments API**.

It highlights known compatibility considerations, field mappings, and operational recommendations to help ensure a smooth transition.

This document is intentionally scoped to **migration-specific concerns**.
It does not replace core API documentation.

## Who This Guide Is For

div
strong
Key idea:
br

  This guide is for existing Direct / legacy clients moving to the NPS Payments API.

You should review this guide if you:

- Currently use Direct
- Have existing transaction IDs you may need to reference
- Support refunds, recurring payments, or delayed capture flows
- Plan to migrate production traffic to the NPS Payments API


## Key Differences to Understand

Before migrating, it’s important to understand a few high-level changes:

- NPS uses **JWT-based authentication** instead of legacy auth models
- Payment processing is **token-first**
- Transactions are identified by an NPS `paymentTransactionId`
- Some legacy identifiers may be reused **only in limited scenarios**


## Key Field Changes

### `originalPaymentTransactionId`

The `originalPaymentTransactionId` field identifies the **original transaction being referenced**, most commonly for refunds.

In the NPS Payments API:

- Transactions are referenced using the NPS-assigned `paymentTransactionId`
- During migration, legacy transaction IDs may still be used


#### Refund Scenarios

div
strong
Supported legacy references:
- **Existing card processing clients**
  - When submitting a `REFUND` transaction
  - A previously assigned legacy `<GatewayTransactionId>` may be used
- **Existing ACH processing clients**
  - When submitting an ACH refund
  - A previously assigned legacy `<CryptPayTransactionId>` may be used


> This guidance applies **only to refund transactions**.


#### Important Limitations

div
strong
Important:
br

  Legacy transaction IDs are generally 
em
not
 supported for other transaction types.

For example:

- `CAPTURE`
- `VOID`
- `CANCEL`
- Post-auth or time-sensitive actions


These transaction types are subject to processor and timing restrictions and typically **cannot reference legacy transactions** after migration.

Always validate refund acceptance using legacy IDs prior to going live.

### `credentialsOnFile.sourceEntityParams`

The `credentialsOnFile.sourceEntityParams` field is used to associate and group **related or recurring transactions**.

It accepts arbitrary name/value pairs.

#### Maintaining Recurring Payment Continuity

**Existing clients** may continue using legacy identifiers such as:

- `AppId`
- `PlanId`
- Subscription identifiers
- Other recurring series keys


These values may be sent unchanged in `credentialsOnFile.sourceEntityParams`.

div
strong
Why this matters:
br

  This allows you to preserve reporting, grouping, and business logic continuity while adopting the new API.

## Operational Migration Considerations

### Delayed Capture / Post-Authorization Flows

Clients who perform **delayed captures** (AUTH → CAPTURE) should:

- Complete all outstanding post-auth transactions in the legacy system
- Avoid migrating in-flight authorizations
- Begin new authorization flows only after switching to NPS


### Recommended Migration Approach

div
ol
li
Finish or cancel in-flight legacy transactions
li
Validate refund behavior using legacy IDs in NPS
li
Migrate tokenization and payment creation flows
li
Monitor early transactions closely
## What This Guide Does Not Cover

This migration guide does not cover:

- Full API field mappings
- Tokenization or SDK setup
- Lifecycle management behavior
- Reporting changes


Refer to the main documentation for those topics.

## Summary

- This guide applies only to existing Direct / legacy clients
- Legacy transaction IDs may be reused **only for refunds**
- Other transaction types must reference NPS transaction IDs
- Recurring identifiers can be preserved via `sourceEntityParams`
- Complete delayed transactions before migrating