Skip to content
Migration & Advanced Topi...
/
Migration Guide (Existing...
Last updated

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

Key idea:
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

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

Important:
Legacy transaction IDs are generally 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.

Why this matters:
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
  1. Finish or cancel in-flight legacy transactions
  2. Validate refund behavior using legacy IDs in NPS
  3. Migrate tokenization and payment creation flows
  4. 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
Previous page