Get your NadaPay integration to a first successful API call in under 10 minutes.

⏱️

Estimated setup time: 10 minutes for your first successful call, about 1 hour to complete a basic sandbox integration after your team has API access and KYC/KYB is complete.

NadaPay lets you manage organizational accounts, verify onboarding status, register beneficiaries, generate transaction quotes, fund accounts, and execute cross-border transactions through a single API.

Who this API is for

Use NadaPay if you are building:

• a platform that sends payouts to businesses or individuals
• a treasury workflow that manages balances across currencies
• an embedded finance or partner integration for cross-border payments
• an internal operations tool for reconciliation, funding, and account management

Prerequisites

Complete these steps before you make your first call:

1. Get your NadaPay API key from your NadaPay dashboard or onboarding contact.
2. Confirm your environment base URL.
3. Store the API key in your secrets manager or environment variables.
4. Confirm your organization has completed the required KYC/KYB review if you plan to move to production.

⚠️

Needs confirmation: Official sandbox base URL, production base URL, and where API keys are created in the dashboard are not yet documented in this page.

Authentication overview

Authenticate every request with your API key in the x-api-key header.

Sandbox vs production

Use sandbox to build and validate your integration flow before you request or enable live processing.

🔐

Treat sandbox and production keys as separate credentials. Keep them in separate environments, rotate them independently, and never reuse production secrets in test systems.

Quickstart

Time to first successful call: 10 minutes

Follow these steps in order.

1. Export your API key

export NADAPAY_API_KEY="your_api_key"
export NADAPAY_BASE_URL="YOUR_NADAPAY_BASE_URL"

2. Make your first request

List the accounts available to your organization.

curl --request GET \
  --url "$NADAPAY_BASE_URL/organizations/accounts" \
  --header "x-api-key: $NADAPAY_API_KEY" \
  --header "Accept: application/json"

3. Confirm the response

If your credentials are valid, NadaPay returns an array of account objects.

[
  {
    "id": "acc-uuid-123",
    "name": "Main Wallet",
    "currency": "USD",
    "walletStatus": "ACTIVE"
  }
]

4. Use the response in your integration

Store the account id values you need for later flows such as quoting, funding, reconciliation, and transaction execution.

What to build next

After your first successful call, follow this sequence:

1. Check your organization verification status with GET /organizations/verification/{type}.
2. Fetch your available accounts with GET /organizations/accounts.
3. Create a beneficiary with POST /beneficiaries.
4. Add or validate a payout destination with POST /beneficiaries/{id}/accounts or POST /transactions/resolve-bank-account.
5. Generate a quote with POST /transactions/quote.
6. Execute the transaction with POST /transactions/execute.

This is the shortest path from onboarding completion to a working payout or funds movement flow.

If you want the full implementation sequence, including funding, route selection, partner flows, and production checkpoints, continue with Quickstart / End-to-End Integration Paths.

Common setup mistakes

401 or 403 responses

Check these items first:

• Confirm the x-api-key header is present.
• Confirm you are using the correct key for the environment.
• Confirm the key has not been rotated or revoked.
• Confirm your request is being sent to the correct base URL.

Empty or unexpected account results

Check these items next:

• Confirm you are calling the environment where your organization was provisioned.
• Confirm your onboarding flow is complete for the organization you expect to use.
• Confirm you are not mixing sandbox credentials with production assumptions.

Rate limit responses

Rate limits are enforced per API key.

When you receive a rate limit error:

• retry with backoff
• avoid parallel retries from multiple workers using the same key
• separate high-volume background jobs from latency-sensitive user flows when possible

⚠️

Needs confirmation: Exact rate limit thresholds, response headers, and retry timing guidance still need to be documented.

Production readiness checklist

Before you move beyond initial testing, complete these steps:

1. Store your API key in a managed secrets system.
2. Separate sandbox and production configuration.
3. Confirm KYC/KYB approval status for the organization you will transact from.
4. Validate your beneficiary creation and account resolution flow.
5. Test quote generation and transaction execution end to end.
6. Prepare webhook handling and operational monitoring before live launch.

Troubleshooting

Authentication issues

If requests fail immediately, test with a minimal request to GET /organizations/accounts before debugging more complex endpoints.

KYC/KYB delays

If your team cannot proceed to production flows, verify the current verification status first. Use the verification endpoint as your source of truth instead of relying on manual status updates.

Sandbox and production confusion

Keep separate configuration values for:

• API keys
• base URLs
• webhook endpoints
• monitoring and alerting destinations

Next steps