Guides
  1. Quickstart

Quickstart: Your First Payout

Authenticate your environment, choose a supported payout network, prepare a destination, generate a quote, and execute your first payout.

Authenticate your environment, prepare a payout destination, generate a quote, and execute your first payout.

Time to complete: 5 minutes

Step 1 — Obtain your API credentials

Before making your first request, you must have an active API key.

  1. Log in to the NadaPay Dashboard.
  2. Complete the KYB (Know Your Business) onboarding process.
  3. Generate a Secret Key in the API Settings section.
⚠️

Use sandbox keys, starting with np_test_, for development and testing. Live keys, starting with np_live_, move real money and should only be used in production.

Step 2 — Configure your environment

Set your credentials as environment variables to make your API calls cleaner and more secure.

export NADAPAY_API_KEY="your_secret_key_here"
export NADAPAY_BASE_URL="https://core.nadapay.io"

Step 3 — Fetch your Source Account ID

Every payout must originate from a specific internal account in NadaPay. Fetch your organization accounts and save the account id you want to use as the source for future transactions.

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

Step 4 — Interpret the response

A successful request returns your account details. Look for the id field.

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

Copy the account id, such as acc-uuid-123. You will use this ID as the source account when generating quotes and executing transactions.

Step 5 — Get supported networks for the payout country

Get the supported networks for the country you want to pay into. Use this step to choose the rail and save the networkId required for bank-based and mobile money payouts.

curl --request POST \
  --url "$NADAPAY_BASE_URL/transactions/networks" \
  --header "x-api-key: $NADAPAY_API_KEY" \
  --header "Content-Type: application/json" \
  --header "x-idempotency-key: YOUR_UNIQUE_UUID" \
  --data '{
    "country": "NG"
  }'

For this Quickstart, continue with Bank Transfer and save the networkId for the destination bank network you want to use.

Step 6 — Create a beneficiary

Create a beneficiary (a reusable payout recipient profile) for the person or business you want to pay.

curl --request POST \
  --url "$NADAPAY_BASE_URL/beneficiaries" \
  --header "x-api-key: $NADAPAY_API_KEY" \
  --header "Content-Type: application/json" \
  --header "x-idempotency-key: YOUR_UNIQUE_UUID" \
  --data '{
    "name": "Jane Doe",
    "email": "[email protected]",
    "phone": "+2348012345678",
    "currency": "NGN",
    "type": "EXTERNAL_BANK",
    "details": {
      "accountNumber": "0123456789",
      "accountName": "Jane Doe",
      "networkId": "ntwk_01HXXXXXXXXXXXXXXXXXX",
      "rail": "Bank Transfer",
      "country": "NG"
    }
  }'

Save the returned beneficiary ID. You will use it when you attach the beneficiary account.

Step 7 — Resolve the bank account

For bank-based payouts, resolve the bank account before you add it as a beneficiary account.

curl --request POST \
  --url "$NADAPAY_BASE_URL/transactions/resolve-bank-account" \
  --header "x-api-key: $NADAPAY_API_KEY" \
  --header "Content-Type: application/json" \
  --header "x-idempotency-key: YOUR_UNIQUE_UUID" \
  --data '{
    "accountNumber": "0123456789",
    "networkId": "ntwk_01HXXXXXXXXXXXXXXXXXX"
  }'

Do not continue if the resolved account name does not match the intended beneficiary.

Step 8 — Add a beneficiary account

Attach the payout account to the beneficiary.

curl --request POST \
  --url "$NADAPAY_BASE_URL/beneficiaries/ben_01HXXXXXXXXXXXXXXXXXX/accounts" \
  --header "x-api-key: $NADAPAY_API_KEY" \
  --header "Content-Type: application/json" \
  --header "x-idempotency-key: YOUR_UNIQUE_UUID" \
  --data '{
    "currency": "NGN",
    "type": "EXTERNAL_BANK",
    "details": {
      "accountNumber": "0123456789",
      "accountName": "Jane Doe",
      "networkId": "ntwk_01HXXXXXXXXXXXXXXXXXX",
      "rail": "Bank Transfer",
      "country": "NG"
    }
  }'

Save the returned beneficiary account ID. You will use it as the destination when generating a quote and executing the payout.

Step 9 — Check transaction limits

Check the allowed amount range before you generate a quote.

curl --request POST \
  --url "$NADAPAY_BASE_URL/transactions/limits" \
  --header "x-api-key: $NADAPAY_API_KEY" \
  --header "Content-Type: application/json" \
  --header "x-idempotency-key: YOUR_UNIQUE_UUID" \
  --data '{
    "currency": "NGN",
    "country": "NG",
    "rail": "Bank Transfer"
  }'

Do not continue if the payout amount falls outside the returned limits.

Step 10 — Generate a quote

Generate a quote to price the payout before execution.

curl --request POST \
  --url "$NADAPAY_BASE_URL/transactions/quote" \
  --header "x-api-key: $NADAPAY_API_KEY" \
  --header "Content-Type: application/json" \
  --header "x-idempotency-key: YOUR_UNIQUE_UUID" \
  --data '{
    "source": {
      "accountId": "acc-uuid-123",
      "currency": "USD",
      "amount": 1000000,
      "type": "FIAT"
    },
    "destination": {
      "beneficiaryAccountId": "bac_01HXXXXXXXXXXXXXXXXXX",
      "currency": "NGN",
      "type": "BANK",
      "country": "NG",
      "paymentMethod": "Bank Transfer"
    },
    "metadata": {
      "reference": "first-payout-test"
    }
  }'

Save the returned quoteId. You need it to execute the payout.

Step 11 — Execute the transaction

Use the quoteId, source account, and beneficiary account to execute the payout.

curl --request POST \
  --url "$NADAPAY_BASE_URL/transactions/execute" \
  --header "x-api-key: $NADAPAY_API_KEY" \
  --header "Content-Type: application/json" \
  --header "x-idempotency-key: YOUR_UNIQUE_UUID" \
  --data '{
    "quoteId": "qte_01HXXXXXXXXXXXXXXXXXX",
    "reason": "gift",
    "reasonDescription": "First test payout",
    "metadata": {
      "reference": "first-payout-test"
    },
    "source": {
      "accountId": "acc-uuid-123",
      "amount": 1000000
    },
    "destination": {
      "beneficiaryAccountId": "bac_01HXXXXXXXXXXXXXXXXXX"
    }
  }'

Save the transaction identifiers returned by this request for monitoring and reconciliation.

What success looks like

  • your request includes the x-api-key header
  • the accounts request returns successfully and you save a Source Account ID
  • you retrieve supported networks and save the networkId for the selected rail
  • you create a beneficiary and attach a beneficiary account
  • you resolve bank account details before using a bank-based rail
  • you check transaction limits before quote generation
  • you generate a quote and save the returned quoteId
  • the execute request creates the payout transaction

Troubleshooting

401 Unauthorized

Check that:

  • the x-api-key header is present
  • the header name is spelled exactly as x-api-key
  • your key is active in the dashboard
  • you are using the correct key for sandbox or production

404 Not Found

Check that:

  • NADAPAY_BASE_URL is correct
  • the endpoint path is /organizations/accounts

Next steps

Updated 29 days ago