NADD API

Institutional API access for NADD payments.

NADD API is the authenticated payment infrastructure layer for partners, platforms, merchants, financial technology providers, and enterprise systems that need to initiate NADD transfers through reserve-verified, risk-screened, idempotent, ledger-backed settlement rails.

StatusProduction Rail Verified

Assurance DateJune 4, 2026

Core PostingDouble-Entry Ledger

HMAC Signed RequestsReserve VerifiedRisk ScreenedIdempotent

Enterprise Integration

Designed for banks, fintechs, merchants, and platforms.

NADD API is designed for financial institutions, payment providers, digital wallets, merchant platforms, exchanges, treasury operations, and enterprise applications seeking secure, programmable access to NADD payment and settlement infrastructure.

Bank Integrations

Controlled payment initiation

Supports authenticated API payments with signed requests, reserve checks, audit records, and reconciliation references for bank-grade workflows.

Merchant Platforms

Checkout and settlement rails

Enables platforms to initiate NADD wallet transfers, track payment references, and reconcile fee and revenue entries.

Treasury Systems

Accounting-grade records

Provides ledger-backed transaction data, fee allocation records, and settlement references for finance and operations teams.

Operational Assurance

Control stack verified through production transaction testing.

The NADD API payment rail has been validated through successful payment execution, duplicate idempotency replay, insufficient-balance rejection, invalid-wallet rejection, velocity-limit blocking, reserve under-collateralization blocking, and concurrent duplicate request protection.

Settlement Controls

Reserve-verified payments

Payments are evaluated against reserve snapshots before ledger posting. Under-collateralized reserve conditions are blocked before settlement.

Risk Controls

Risk and AML screening

Every payment request passes through risk scoring, AML status checks, sanctions status checks, velocity evaluation, and maker-checker flags where required.

Ledger Controls

Double-entry posting

Successful payments post source debit, destination credit, and revenue credit entries with transaction references, request fingerprints, and idempotency metadata.

API Base URL

Production and sandbox endpoints.

Production access is restricted to approved API clients. Sandbox access is issued for integration testing before production approval.

Environment	Base URL	Purpose	Access
Production	`https://api.admin.nadd.io/nadd-api`	Approved live NADD API payment operations	KYB-approved clients only
Sandbox	`https://nadd.io/api/sandbox`	Integration testing with test wallets and non-production balances	Issued after developer onboarding

Developer & Partner Access: The NADD API is available to approved partners through the NADD onboarding process. Qualified organizations receive API credentials, integration documentation, sandbox access, webhook configuration guidance, and production activation support.

API Documentation

Authentication, payment fields, and request structure.

Partners must sign each request using the assigned API key and secret. All money movement endpoints require timestamped signatures, idempotency keys, request identifiers, and correlation identifiers.

Authentication Headers

Header	Required	Description
`x-api-key`	Yes	Public API key assigned to the approved partner.
`x-timestamp`	Yes	ISO-8601 UTC timestamp. Requests outside the permitted time window are rejected.
`x-signature`	Yes	HMAC signature over the canonical request.
`x-signature-version`	Yes	Current version: `v1`.
`x-idempotency-key`	Yes	Unique key preventing duplicate posting for the same payment request.
`x-request-id`	Yes	Unique request trace identifier generated by the client.
`x-correlation-id`	Yes	Identifier used to trace related operations across systems.

Payment Object Fields

Field	Type	Rule
`sourceWalletId`	UUID	Wallet debited for principal plus applicable fee.
`destinationWalletId`	UUID	Wallet credited with principal amount.
`amount`	String decimal	NADD amount with up to six decimal places.
`currency`	String	Currently restricted to `NADD`.
`rail`	Enum	Example: `nadd_internal`.
`purpose`	Enum	Example: `wallet_transfer`.
`externalReference`	String	Partner-side reference for reconciliation.
`narration`	String	Human-readable payment description.
`complianceNarrative`	String	Purpose and compliance context for audit review.

Illustrative Request

POST /nadd-api/payments
Content-Type: application/json
x-api-key: nadd_pk_partner_example
x-timestamp: 2026-06-04T07:35:37.080Z
x-signature-version: v1
x-signature: <hmac_signature>
x-idempotency-key: partner-payment-000001
x-request-id: req-000001
x-correlation-id: corr-000001

{
  "sourceWalletId": "<source-wallet-uuid>",
  "destinationWalletId": "<destination-wallet-uuid>",
  "amount": "1.000000",
  "currency": "NADD",
  "rail": "nadd_internal",
  "purpose": "wallet_transfer",
  "priority": "normal",
  "externalReference": "PARTNER.REF.000001",
  "narration": "Partner NADD payment",
  "complianceNarrative": "Approved partner payment instruction"
}

Illustrative Completed Response

HTTP/2 202
{
  "fee": "0.005000",
  "amount": "1.000000",
  "status": "completed",
  "totalDebit": "1.005000",
  "debitEntryId": "<ledger-entry-id>",
  "creditEntryId": "<ledger-entry-id>",
  "revenueEntryId": "<ledger-entry-id>",
  "ledgerTransactionId": "<ledger-batch-id>",
  "ledgerBatchReference": "NAPI_LB_...",
  "paymentInstructionId": "<payment-id>",
  "transactionReference": "NAPI_TX_..."
}

Error Codes

Predictable failure behavior for partner systems.

NADD API returns structured HTTP responses when requests fail validation, authorization, risk, reserve, velocity, or ledger controls.

HTTP Status	Scenario	Example Message	Partner Action
`400`	Invalid request body or wallet	`Wallet not found`	Correct request data before retrying.
`401`	Authentication failure	`Invalid request signature` or `timestamp outside allowed window`	Regenerate timestamp and signature.
`403`	Business control block	`Insufficient available balance`	Do not retry without resolving funds or control issue.
`403`	Reserve enforcement	`Reserve check blocked payment`	Payment blocked until reserve condition is cleared.
`403`	Velocity enforcement	`source_wallet_daily_amount_limit_exceeded`	Wait for limit window or request approved limit change.
`409`	Concurrent duplicate request	`identical request is already processing`	Retry idempotently after current processing completes.
`503`	Service dependency unavailable	`service unavailable`	Retry according to exponential backoff policy.

Webhook Events

Event notifications for payment lifecycle updates.

Approved partners may configure signed webhook endpoints to receive payment status changes and reconciliation events.

Supported Events

Event	Description
`payment.completed`	Payment has posted to the ledger and final references are available.
`payment.failed`	Payment failed before settlement.
`payment.blocked`	Risk, reserve, balance, or velocity control blocked settlement.
`payment.review_required`	Maker-checker or manual review is required before completion.
`reconciliation.available`	A reconciliation record or reporting file is available.

Illustrative Webhook Payload

{
  "event": "payment.completed",
  "eventId": "evt_000001",
  "createdAt": "2026-06-04T07:38:17Z",
  "transactionReference": "NAPI_TX_...",
  "ledgerBatchReference": "NAPI_LB_...",
  "amount": "1.000000",
  "fee": "0.005000",
  "totalDebit": "1.005000",
  "currency": "NADD",
  "externalReference": "PARTNER.REF.000001",
  "status": "completed"
}

Webhook security: webhook deliveries should be signed using partner-specific webhook secrets, delivered over HTTPS, retried safely, and reconciled by event ID and transaction reference.

Idempotency Policy

Duplicate-safe money movement.

Every money movement request must include an idempotency key. Identical replayed requests return the stored result. Concurrent duplicates are blocked while the first request is processing.

Replay Protection

Same key, same payload

Returns the completed response and does not create another ledger posting.

Conflict Protection

Same key, different payload

Rejected as an idempotency conflict to prevent ambiguous settlement.

Race Protection

Concurrent duplicates

Only one request may process while matching duplicates receive a conflict response.

Settlement & Reconciliation

Ledger-first records for finance teams.

NADD API is designed around ledger-backed records instead of unsecured response-only payments. Partners reconcile using transaction references, ledger batch references, idempotency keys, external references, and webhook events.

Record	Purpose	Key Fields
Transaction Journal	Authoritative payment transaction record	`transactionReference`, `amount`, `currency`, `status`
Ledger Entries	Debit, credit, and fee postings	`debitEntryId`, `creditEntryId`, `revenueEntryId`
Ledger Batch	Batch-level accounting group	`ledgerBatchReference`, `ledgerTransactionId`
Reserve Check	Reserve coverage audit	`backingRatio`, `reserveStatus`, `decision`
Risk & Velocity Checks	Control-layer audit trail	`riskLevel`, `triggeredRules`, `decision`
State History	Payment lifecycle movement	`pending` → `completed` or failure state

Access Process

Sandbox access before production approval.

NADD API access is not open-anonymous access. Partners are onboarded through a controlled process involving business verification, technical integration review, compliance review, and production approval.

Sandbox Access

Submit integration request

Email api@nadd.io with business profile, intended use case, technical contact, and expected volume.

Receive sandbox credentials

Approved developers receive sandbox API keys, test wallets, sample payloads, and webhook test instructions.

Complete integration tests

Partners must pass signing, timestamp, idempotency, invalid wallet, insufficient balance, velocity, webhook, and reconciliation tests.

Production Approval

KYB and compliance review

Production access requires verified business information, authorized signatories, approved use case, and compliance documentation.

Security controls

Partners must provide IP allowlist ranges, production webhook URLs, escalation contacts, and operational monitoring details.

Production key issuance

Production keys are issued only after sandbox sign-off, risk approval, and production readiness confirmation.

Security & Responsible Disclosure

Security-first access and disclosure channels.

NADD API credentials, signing secrets, webhook secrets, infrastructure configuration, and production system internals are never published publicly. Security reports should be submitted through the official channel.

Security Controls

HMAC request signatures with timestamp controls.
Mandatory idempotency keys for money movement.
API key permissions and production approval controls.
IP allowlisting for approved production clients where required.
Risk, velocity, reserve, and ledger controls before settlement.
Audit metadata: request ID, correlation ID, request fingerprint, and external reference.

Responsible Disclosure

Security researchers, partners, and institutional reviewers may report suspected vulnerabilities, integration risks, credential exposure, or API abuse concerns through the security contact below.

Email: security@nadd.io
API access: api@nadd.io
General support: support@nadd.io

Regulatory-Conscious Public Notice

NADD is a privately issued blockchain-native digital payment instrument. It is not legal tender, not a central bank digital currency, and not issued, endorsed, guaranteed, regulated, or affiliated with the Bank of Namibia, the Government of the Republic of Namibia, or any central bank.

Information on this page is provided for institutional, developer, ecosystem, and partner integration purposes. It is not financial, legal, banking, investment, regulatory, or tax advice. Production API access is subject to NADD approval, compliance review, technical review, risk controls, and applicable contractual terms.