Understand how NadaPay uses NP-Reference IDs as the canonical control plane for deposits, payouts, swaps, and money-state orchestration.

🧭

The NP-Reference ID Engine is the canonical spine of the NadaPay platform. It is not a logging tool or debugging aid. It is the control plane for money, state, and autonomous orchestration.

Use this guide to understand what an NP-Reference ID is, how it is structured, how it moves through its lifecycle, and what your integration must do with it.

Golden invariant

⚠️

Golden invariant: If it doesn’t have an NP-Reference ID, it does not exist inside NadaPay.

All systems inside NadaPay must anchor to the NP-Reference ID as the single source of truth, including:

• ledger
• orchestration
• AI agents
• hardware
• provider rails

What an NP-Reference ID is

An NP-Reference ID is the canonical identity for a tracked money movement or money-state process inside NadaPay.

It is not only a label attached to a transaction. It is the reference spine that ties together:

• transaction identity
• lifecycle state
• event emission
• reconciliation
• operational tracking
• orchestration across internal and external systems

Your integration should treat the NP-Reference ID as the authoritative identifier for the lifecycle it represents.

NP-Reference ID format

Use this format as the canonical public pattern:

NP-L-<TYPE>-<ID>

Known examples

Known type codes

⚠️

Needs confirmation: The public docs currently describe the canonical format and known type codes, but do not yet define whether additional type codes exist or whether the L segment has a public semantic meaning for integrators.

NP-Reference ID as a state machine

An NP-Reference ID is not a passive label. It represents a finite, deterministic lifecycle.

Every tracked reference must progress through the following canonical states:

CREATED → AUTHORIZED → ROUTED → SENT → CLEARED → SETTLED → CLOSED

This lifecycle is the canonical state model for tracked NadaPay money movement.

Lifecycle rules

These rules apply to the NP-Reference spine:

Transitions are explicit

State changes are not implied. Each movement from one state to the next must be treated as an explicit transition.

State change events must be emitted

Every state change must emit an event to the event bus.

The lifecycle is fully tracked

There is no such thing as an untracked or partial transaction inside the NP-Reference model.

The NP-Reference ID is the control-plane anchor

All systems that participate in the lifecycle must anchor their tracking, reconciliation, and automation to the same NP-Reference ID.

What this means for integrators

If you integrate deposits, payouts, swaps, or downstream reporting workflows, you should:

1. persist the NP-Reference ID in your system of record
2. treat it as the canonical identifier for the lifecycle it represents
3. use it for reconciliation and operational investigations
4. map internal transaction tracking to the NP-Reference ID instead of inventing a competing source of truth
5. process lifecycle changes as state transitions, not as disconnected status updates

Recommended implementation behavior

Store the NP-Reference ID early

As soon as your workflow receives an NP-Reference ID, persist it in your backend and associate it with your internal transaction, payout, swap, or deposit record.

Reconcile on NP-Reference ID

When operations, support, finance, or engineering teams investigate a money movement, the NP-Reference ID should be the first shared identifier used across systems.

Keep internal state aligned

If your internal workflow has its own transaction statuses, map them to the canonical NadaPay lifecycle carefully. Do not create a conflicting state model that obscures the actual reference lifecycle.

Treat missing NP-Reference IDs as a hard failure condition

If a workflow claims to exist inside NadaPay but no NP-Reference ID is present, treat that as a broken or incomplete integration condition.

Deposits, payouts, and swaps

The NP-Reference ID format already signals the tracked lifecycle category.

Deposits

Example:

NP-L-DEP-89A65ACA

Use the deposit NP-Reference ID as the canonical identity for the deposit lifecycle.

Payouts

Example:

NP-L-PAY-0A80EA27

Use the payout NP-Reference ID as the canonical identity for the payout lifecycle.

Swaps

Example:

NP-L-FX-7F4682BD

Use the swap NP-Reference ID as the canonical identity for the swap lifecycle.

Operational guidance

Support and incident review

Use the NP-Reference ID when:

• investigating lifecycle delays
• matching internal records to NadaPay processing
• reviewing provider-rail activity
• reconciling money movement across systems

Auditability

Record the NP-Reference ID alongside:

• your internal transaction or workflow ID
• timestamps for important business actions
• beneficiary, account, or organization context where relevant
• event-processing history in your own systems

Event-driven processing

If your architecture is event-driven, treat the NP-Reference ID as the primary correlation key for lifecycle transitions.

What this page does not yet define

This page defines the NP-Reference ID concept, format, and state model, but does not yet define:

• timing windows for lifecycle progression
• SLA thresholds between individual states
• any additional public type codes beyond FX, DEP, and PAY
• exact event payload structures or webhook delivery details

Those details should be documented separately once confirmed.

Troubleshooting

A workflow has no NP-Reference ID

Treat this as a broken integration or incomplete tracking condition. If there is no NP-Reference ID, the workflow does not exist inside NadaPay.

Internal state does not match NadaPay lifecycle state

Use the NP-Reference ID as the reconciliation anchor and correct the state mapping in your internal systems.

Multiple systems refer to the same money movement differently

Standardize operational investigation on the NP-Reference ID first, then map all other identifiers to it.

Related pages