Sandbox Documentation URL
https://nadd.io/api/sandbox
This page describes the sandbox process, test scenarios, credential rules, webhook simulations, and migration requirements.
Sandbox Environment
NADD API Sandbox for controlled integration testing.
The NADD API Sandbox is the controlled partner testing environment for validating authentication, payment requests, idempotency, wallet validation, reserve simulation, webhook handling, and reconciliation workflows before production approval.
EnvironmentControlled Sandbox
Use CasePartner Integration Testing
Production MigrationApproval-Based Go-Live
Environment Structure
Clear separation between documentation, sandbox testing, and production API execution.
Sandbox documentation is public at this page. Actual sandbox API credentials, wallets, webhook secrets, test ledgers, and partner-specific scenarios are issued through controlled onboarding.
Issued During Onboarding
Sandbox API endpoints and credentials are provided to approved partners. Sandbox is not connected to live reserves, production wallets, or production settlement.
Operational Base URL
https://api.admin.nadd.io/nadd-api
Production access requires KYB, API approval, credentials, IP controls, signature validation, and operational readiness review.
Testing Scope
What partners can validate before production launch.
The sandbox is intended to prove integration behavior before any real-value payment flows or institutional settlement connections are activated.
Core Sandbox Tests
AuthenticationAPI key, timestamp, signature, request identity
PaymentsCreate simulated NADD payment instructions
IdempotencyReplay same request without duplicate posting
Wallet ValidationValid wallet, invalid wallet, inactive wallet cases
Risk & VelocityThreshold, limit, and review simulations
Reserve SimulationFully backed, stale, unavailable, and blocked states
Credentials
Sandbox credentials are never public.
Public pages must not expose live API keys, signing secrets, webhook secrets, internal source code, production wallet IDs, or privileged operational endpoints.
Issued Credential Set
| Credential | Purpose | Publicly Exposed? |
|---|---|---|
| Sandbox API Key | Identifies the approved sandbox integration client. | No |
| Signing Secret | Used to generate HMAC request signatures. | No |
| Webhook Secret | Used to verify sandbox webhook payloads. | No |
| Test Wallet IDs | Controlled test wallets for simulated NADD movement. | Issued to approved partner only |
| IP Allowlist | Optional network restriction for approved test environments. | No |
Payment Object
Standard sandbox payment request structure.
The sandbox mirrors production payment object requirements while using simulated wallets, simulated balances, and controlled response behavior.
Illustrative Request Body
{
"sourceWalletId": "sandbox-source-wallet-uuid",
"destinationWalletId": "sandbox-destination-wallet-uuid",
"amount": "10.000000",
"currency": "NADD",
"rail": "nadd_internal",
"purpose": "wallet_transfer",
"priority": "normal",
"externalReference": "PARTNER-SANDBOX-000001",
"narration": "Sandbox NADD API test payment",
"complianceNarrative": "Controlled sandbox payment simulation"
}This sample is illustrative only. Actual sandbox wallet identifiers and credentials are issued through approved onboarding.
Webhook Simulation
Event handling before production activation.
Sandbox webhook testing allows partners to validate event intake, signature verification, retries, idempotent processing, and reconciliation mapping before go-live.
Supported Sandbox Events
payment.completed, payment.failed, payment.review_required, payment.blocked, payment.reversed
Posting & Reconciliation
ledger.posted, fee.posted, reconciliation.ready, settlement.batch_created
Signed Webhooks
Each webhook should be verified using issued webhook signing secrets and partner-side idempotency controls.
Error Handling
Sandbox scenarios should include controlled failure testing.
Partners should deliberately test declined transactions, invalid payloads, duplicate requests, expired timestamps, insufficient balances, reserve blocks, and velocity breaches.
| Status | Scenario | Expected Integration Behavior |
|---|---|---|
400 | Invalid payload or wallet reference | Correct request data before retrying. |
401 | Invalid signature or expired timestamp | Regenerate signature and timestamp. |
403 | Balance, reserve, risk, or velocity control block | Do not automatically retry without resolving cause. |
409 | Identical request already processing | Wait, then check idempotency result. |
503 | Temporary service dependency unavailable | Use safe retry policy with idempotency. |
Reconciliation
Sandbox settlement records mirror production accounting concepts.
Sandbox responses and reports should map each test payment to transaction reference, ledger batch reference, debit entry, credit entry, fee entry, status transition, and webhook event.
Minimum Reconciliation Fields
- Partner external reference
- NADD transaction reference
- Ledger batch reference
- Principal amount, fee amount, and total debit
- Debit entry, credit entry, and revenue entry references
- Final payment status and timestamp
- Idempotency key and request fingerprint
Production Migration
From sandbox validation to approved production access.
Production access is approval-based and requires operational, technical, and compliance readiness before live NADD settlement is enabled.
Complete Sandbox Testing
Validate authentication, payments, webhooks, error handling, idempotency, reconciliation, and security controls.
Submit Integration Review
Provide use case, technical contact, webhook endpoints, IP ranges, transaction volumes, and compliance workflow.
Complete KYB & Approval
Production access is issued after partner review, access controls, rate limits, and production credentials are approved.
Security & Governance
NADD API provides the documentation required for secure integration and deployment. Security-sensitive infrastructure and operational controls are managed through controlled-access processes. Additional technical, security, and audit documentation may be made available to approved institutional partners.
Important Sandbox Notice
The sandbox environment is for testing and integration readiness only. Sandbox activity does not represent live NADD settlement, production reserves, production wallets, legal tender activity, banking services, or regulated financial advice.
NADD is a privately issued blockchain-native digital payment instrument. It is not legal tender, not a CBDC, and is not issued, endorsed, guaranteed, regulated, or affiliated with the Bank of Namibia, the Government of the Republic of Namibia, or any central bank.