Skip to content

Create a Sandbox API key

Create a sandbox key, keep it safe, and be sure the sandbox is where your requests go.

Sandbox: test money only. No request moves real money.

In this step you create a Sandbox API key in your dashboard, put it where every example reads it, and learn the signs that a request went to the Sandbox. Your setup checklist marks the step done once an active key can place and read orders.

The sandbox is a separate host, https://sandbox-api.nasfampay.com/v1, with its own nbk_test_ keys. It answers with the same operations, fields, statuses and errors that Live is designed to. No real money moves and nothing is delivered to Telegram; the outcome of an order is simulated.

Create a sandbox key

  1. Sign in to your dashboard, in your workspace.
  2. Open Developers, then API keys, and create a key. You choose what the key may do when you create it. Creating a key needs a sign-in in the last five minutes; if yours is older, the dashboard asks you to sign in again first.
  3. Give it at least quotes:write, orders:write and orders:read: the scopes an order needs. Add balance:read to read your balance.
  4. Copy the key when it is shown. It is shown once and cannot be read again. It starts with nbk_test_.

Protect the key

The key is the only credential. Anyone who holds it can spend the balance behind it, so decide where it will live before you create it. Keep it in the environment or a secret store. Never commit it, log it, or send it to a browser or a mobile app.

Keys are created, rotated and revoked in the dashboard, never through the API. See Create and manage API keys.

Put the key in your environment

Every example on these pages reads the key from the NASFAM_SANDBOX_KEY environment variable. Set it once in the terminal you run them from. In a POSIX shell that is export NASFAM_SANDBOX_KEY= followed by the key you created.

Keep the key out of your code and out of any browser. A key that is never written into a file cannot be committed by accident.

An example that changes your balance also reads IDEMPOTENCY_KEY. Set it once per purchase, keep it with that purchase, and run the example again with the same value to retry: the API answers with the first result and never charges twice. In your own code, store the key with the purchase before you send it; see Idempotency.

How to tell you are in the sandbox

  • The key starts with nbk_test_. A nbk_live_ key is refused here with key_environment_mismatch.
  • GET /account answers with an environment of sandbox.
  • Every order and every event carries the same environment.
  • A product with a status of sandbox is simulated only. One with planned is not orderable.

Synthetic money

The balance behind a sandbox key holds synthetic money: the test funds you added in step 1. POST /sandbox/funding/deposits simulates a GRAM deposit. Neither exists on Live.

An order is paid from available, so an order sent with nothing available is refused with insufficient_funds. An amount always names its currency: read it, and never assume it.

Test recipients and forced outcomes

A telegram_username in the reserved nasfam_test_ namespace chooses what the simulated provider does: nasfam_test_ok succeeds, nasfam_test_rejected fails, nasfam_test_slow takes about two minutes and nasfam_test_timeout ends under review. Live refuses every one of them. Any other username behaves as an ordinary order.

You can still cause a funding, an accepted order, a replay, a lost response and every kind of refusal yourself, and a test event shows your endpoint each event type. Sandbox scenarios lists each one.

Differences from live

  • Amounts are synthetic. A price in the sandbox is not a quote for live.
  • Product limits are provisional (provisional is true) until provider capabilities are confirmed.
  • The sandbox routes do not exist on Live. A Live balance is designed to be funded with GRAM, on the TON network; see Funding with GRAM.
  • Orders on Live are real: a succeeded order is delivered to Telegram and paid from real money.
  • A sandbox key needs only an account. Live keys exist only for a workspace activated for Live; see Complete Live activation.

What you should see

You hold a key that starts with nbk_test_. It is in NASFAM_SANDBOX_KEY and never in your code. The next steps use it. When you read the account behind the key, the environment is sandbox:

Code for What you should see
A sandbox account
JSON
200 OKSynthetic sandbox data
{  "id": "org_01K7SAMP000000000000000090",  "name": "Example Business Ltd",  "environment": "sandbox",  "kyb_status": "sandbox_only",  "limits": {    "max_queued": 50  }}

If it fails

What you seeWhat to check
The examples fail before sending anythingNASFAM_SANDBOX_KEY is not set in the terminal that runs them. Set it there, then run the example again.
key_environment_mismatchThe key and the host belong to different environments. Send a nbk_test_ key to https://sandbox-api.nasfampay.com/v1.
insufficient_scopeThe key lacks a scope this operation needs. A key keeps the scopes it was made with: create one with quotes:write, orders:write and orders:read.
You did not copy the key when it was shownIt cannot be shown again. Revoke it in the dashboard and create another.
A 404 on a /sandbox routeThe request went to the live host. Sandbox routes exist on the sandbox host only.
invalid_api_keyThe key is missing, mistyped or revoked. Check the Authorization header is Bearer followed by the whole key.
key_expiredThe key has expired. Create a new one in your dashboard.

Next step

Sandbox step 3 of 7: Learn recipient lookup. Show your customer the Telegram account behind the username they typed, and order only once they confirm it.