Get started

Quickstart

From a new sandbox key to a completed transfer and a cash-out in ten calls. Everything here runs against the sandbox, where no real money moves.

Set up

Put your sandbox key and base URL in your shell. Your key arrives with your onboarding email.

export NDEIPI_API_KEY=nd_test_your_key_here
export NDEIPI=https://sandbox.api.ndeipi.example/v1

Walk through it

1. Create two users

   Use your own customer ID as external_reference. It's unique per integrator, so a retry can never create a duplicate person. Repeat with crm-1043 for the second user.

   ShellCopy

   curl -X POST "$NDEIPI/users" \
     -H "Api-Key: $NDEIPI_API_KEY" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{ "type": "individual", "external_reference": "crm-1042",
           "email": "ama.moyo@example.com", "first_name": "Ama", "last_name": "Moyo", "country": "ZW" }'

2. Send them through onboarding

   Open the returned kyc.url and terms.url in the user's browser. In the sandbox you can skip the hosted flow and approve them directly.

   ShellCopy

   curl -X POST "$NDEIPI/users/usr_01JA8Z2F5G6H7J8K9M0N1P2Q3R/onboarding_links" \
     -H "Api-Key: $NDEIPI_API_KEY" -H "Idempotency-Key: $(uuidgen)"
   
   # Sandbox only: finish KYC and accept the terms
   curl -X POST "$NDEIPI/sandbox/users/usr_01JA8Z2F5G6H7J8K9M0N1P2Q3R/kyc" \
     -H "Api-Key: $NDEIPI_API_KEY" -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" -d '{ "kyc_status": "approved" }'

3. Give each user a wallet
   ShellCopy

   curl -X POST "$NDEIPI/users/usr_01JA8Z2F5G6H7J8K9M0N1P2Q3R/wallets" \
     -H "Api-Key: $NDEIPI_API_KEY" -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" -d '{ "asset": "ndeipi-points" }'

4. Fund the first wallet

   Create standing deposit details, then simulate a ZAR 100 EFT arriving.

   ShellCopy

   curl -X POST "$NDEIPI/users/usr_01JA8Z2F5G6H7J8K9M0N1P2Q3R/deposit_accounts" \
     -H "Api-Key: $NDEIPI_API_KEY" -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{ "source": { "currency": "zar", "rail": "absa_eft" },
           "destination": { "wallet_id": "wal_01JA8Z4K2V9QW3H6Y7XKD2M0RS" } }'
   
   curl -X POST "$NDEIPI/sandbox/deposits" \
     -H "Api-Key: $NDEIPI_API_KEY" -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{ "deposit_account_id": "da_01JA8ZF5TP0R5B8Z6Y3X2W1V0T", "amount": "100.00" }'

5. Send 25.00 to the second user

   Keep the idempotency key with your own record of the payment. If the request times out, send it again with the same key: you get the same transfer back, never a second one.

   ShellCopy

   curl -X POST "$NDEIPI/transfers" \
     -H "Api-Key: $NDEIPI_API_KEY" \
     -H "Idempotency-Key: 6b1f7f0e-3c55-4d1b-9a43-0d9f1c2e7a10" \
     -H "Content-Type: application/json" \
     -d '{ "source": { "type": "wallet", "wallet_id": "wal_01JA8Z4K2V9QW3H6Y7XKD2M0RS" },
           "destination": { "type": "wallet", "wallet_id": "wal_01JA8Z5B7C1DE2F3G4H5J6K7LM" },
           "amount": "25.00", "integrator_reference": "invoice-7781" }'

   The response is already completed: user-to-user transfers settle on the ledger immediately.

6. Cash out

   Register a payout account for the second user, then move 20.00 to it. In the sandbox, you decide how the payout ends.

   ShellCopy

   curl -X POST "$NDEIPI/users/usr_01JA8Z3H6J7K8M9N0P1Q2R3S4T/payout_accounts" \
     -H "Api-Key: $NDEIPI_API_KEY" -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{ "type": "bank", "currency": "zar", "country": "ZA", "rail": "absa_eft",
           "account_owner_name": "Tendai Ncube",
           "bank": { "bank_name": "Absa Bank", "account_number": "4091234567", "routing_code": "632005" } }'
   
   curl -X POST "$NDEIPI/transfers" \
     -H "Api-Key: $NDEIPI_API_KEY" -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{ "source": { "type": "wallet", "wallet_id": "wal_01JA8Z5B7C1DE2F3G4H5J6K7LM" },
           "destination": { "type": "payout_account", "payout_account_id": "pa_01JA8Z6N3P4Q5R6S7T8U9V0WXY" },
           "amount": "20.00" }'

Next