---
name: nasfam-business-api
description: "Integrate the Nasfam Business API. Deliver digital products (`telegram_stars` and `telegram_premium`) to Telegram accounts from a prefunded balance. A sandbox on synthetic money, and live for a business activated for it. Use when writing or reviewing code that calls this API or handles its orders, errors or webhook deliveries."
---

# Integrating the Nasfam Business API

Contract 1.0.0-draft.10. Every page of the documentation is listed in [llms.txt](https://business.nasfampay.com/docs/llms.txt), each as Markdown; [llms-full.txt](https://business.nasfampay.com/docs/llms-full.txt) is an index of the full text, which is one file per task.

## Rules

1. Write for the sandbox, `https://sandbox-api.nasfampay.com/v1`, where every amount is synthetic. The sandbox host, `https://sandbox-api.nasfampay.com/v1`, takes `nbk_test_` keys and test money only. The Live host, `https://api.nasfampay.com/v1`, takes only `nbk_live_` keys and moves real money; a business can create a Live key once it is activated for Live. Every example reads the key from `NASFAM_SANDBOX_KEY` in the sandbox and `NASFAM_LIVE_KEY` in Live, and shows each request and its answer exactly as the contract defines them. Point code at Live only when the developer asks for it: a Live order spends real money.
2. Use only what the contract defines: [openapi.json](https://business.nasfampay.com/docs/openapi.json). Never invent an endpoint, a field, a header, a status or an error code. When the contract does not say, ask the developer instead of guessing.
3. Read the key from an environment variable (`NASFAM_SANDBOX_KEY` in the sandbox, `NASFAM_LIVE_KEY` in Live). Never write a key into code, a prompt, a log or a commit, and never ask the developer to paste one.
4. Send an `Idempotency-Key` on every operation the table below marks "Changes your balance": the ones the contract says move money, and on `POST /statements`, which the contract also binds one to. Reuse the same key on every retry of the same request, and a new key for a new intent.
5. `under_review` is a hold, not a failure. The funds stay held: do not create a second order, do not treat it as failed, wait for the next state.
6. Amounts are what the contract types them as, below: integers in the minor unit. Never a float, never a converted figure.
7. Webhooks: verify every delivery as the contract defines it, Standard Webhooks v1, before parsing it: an HMAC-SHA256 under the bytes of the endpoint secret (the base64 after `whsec_`) over `<webhook-id>.<webhook-timestamp>.<raw body>`, compared in constant time with each `v1,` value of `webhook-signature`, and a timestamp within 5 minutes. Deduplicate by `webhook-id`, fetch the object before releasing value, and never act on a test event (`"test": true`). Invent no other header or check.
8. This file holds no script and asks for none to be run. Propose commands and code; the developer runs them.

## What the contract says about itself

- DRAFT contract. Sandbox only in Phase 1; no live provider availability is claimed.
- Every operation that moves money (`x-nb-moves-money: true`) requires an Idempotency-Key, bound permanently.
- The balance is USD, in Sandbox and Live. Money amounts are integers in cents; exact USD figures are integer micro-dollar strings.
- GRAM (an organisation that pays with GRAM, ledger currency TON): its quotes and orders are priced in USD from the server's
- price book (`amount`, USD cents) and charged as GRAM (`settlement`); every GRAM amount is an integer nanogram string
- (1 GRAM = 1,000,000,000 nanogram), rounded up. `GET /v1/rates` and `GET /v1/prices` are what it is quoted from.
- Display currencies (draft.6, display only; USD unless a member chooses another). A `display` object is an indicative equivalent, never
- a balance, price, quote, charge or settlement, and choosing a display currency changes no other field.
- USD (draft.7): an organisation that spends USD (`spending_currency`) holds USD credits in micro-dollars
- (`*_micros`, 1 USD = 1,000,000, integer strings). A deposit converts when it is credited: GRAM at the verified GRAM/USD rate
- less the deposit spread. With no verified rate
- a deposit is held in its own asset, never credited at a guess. Quotes and orders charge USD.
- Not served yet: direct GRAM orders (a GRAM order is made from a quote), and
- GRAM in the balance statement (`/v1/balance/transactions` lists USD movements).
- Requests are strict: unknown request fields are rejected.
- Free-text request strings (metadata, filters, descriptions) never contain U+0000 or an unpaired surrogate, and a date-time is from year 0001 with an offset within 15:59: values outside what the store holds are refused 400 `invalid_request`, never accepted.
- Responses are extensible: integrations must ignore unknown response fields, enum values and event types.
- Order events are ordered by the order's monotonic `version`, not by timestamps.
- Quickstart (draft.10): `POST /v1/orders` with `{"product": "telegram_stars", "username": "@customer", "quantity": 100}` (or `"telegram_premium"` with `months`) and an Idempotency-Key is a whole order. The server checks the recipient, prices it from the same price book a quote uses, and holds the funds, all in one step; `max_amount` is an optional ceiling. `GET /v1/recipients/lookup?username=&product=` is an optional check beforehand; an order never needs anything it returns. Both are on in the sandbox and in Live; the quote flow is unchanged.
- Look a recipient up before quoting (`POST /v1/recipient-lookups`): it returns the account the provider found at the username (display name and photo as returned, null where not) for your customer to confirm, and the quote that cites it (`recipient_lookup`) is refused if it no longer matches. "Found" means the provider found an account at that username; nothing here verifies who a Telegram account belongs to.
- Rate limits are listed in `x-nb-rate-limits` and reported in the RateLimit-Policy and RateLimit headers of draft-ietf-httpapi-ratelimit-headers-11 (an Internet-Draft, not yet an RFC); a 429 carries Retry-After.

## Every operation

| Operation | Request | What it does | Changes your balance |
| --- | --- | --- | --- |
| [listProducts](https://business.nasfampay.com/docs/reference/list-products.md) | `GET /products` | List products | No |
| [listPrices](https://business.nasfampay.com/docs/reference/list-prices.md) | `GET /prices` | The USD price book in effect, with indicative GRAM figures | No |
| [getRates](https://business.nasfampay.com/docs/reference/get-rates.md) | `GET /rates` | The GRAM/USD reference rate GRAM quotes are priced at, and display rates | No |
| [createRecipientLookup](https://business.nasfampay.com/docs/reference/create-recipient-lookup.md) | `POST /recipient-lookups` | Look up a Telegram recipient before quoting | No |
| [lookupRecipient](https://business.nasfampay.com/docs/reference/lookup-recipient.md) | `GET /recipients/lookup` | Check a Telegram username before ordering (optional) | No |
| [createQuote](https://business.nasfampay.com/docs/reference/create-quote.md) | `POST /quotes` | Verify a recipient and lock a price for up to 60 seconds | No |
| [listOrders](https://business.nasfampay.com/docs/reference/list-orders.md) | `GET /orders` | List orders | No |
| [createOrder](https://business.nasfampay.com/docs/reference/create-order.md) | `POST /orders` | Create an order (funds are reserved before the response) | Yes |
| [getOrder](https://business.nasfampay.com/docs/reference/get-order.md) | `GET /orders/{id}` | Retrieve an order | No |
| [getBalance](https://business.nasfampay.com/docs/reference/get-balance.md) | `GET /balance` | Available, held and pending-funding balances | No |
| [listBalanceTransactions](https://business.nasfampay.com/docs/reference/list-balance-transactions.md) | `GET /balance/transactions` | Every movement on the balance | No |
| [getLimits](https://business.nasfampay.com/docs/reference/get-limits.md) | `GET /limits` | The platform's limits, the workspace's own spending limits and what they have used | No |
| [listStatements](https://business.nasfampay.com/docs/reference/list-statements.md) | `GET /statements` | The workspace's statements, newest first | No |
| [createStatement](https://business.nasfampay.com/docs/reference/create-statement.md) | `POST /statements` | Request an account statement for whole local days | No |
| [getStatement](https://business.nasfampay.com/docs/reference/get-statement.md) | `GET /statements/{id}` | One statement, its state and, once ready, its reconciled summary | No |
| [listFundings](https://business.nasfampay.com/docs/reference/list-fundings.md) | `GET /fundings` | Incoming transfers and their state | No |
| [getDepositAddress](https://business.nasfampay.com/docs/reference/get-deposit-address.md) | `GET /funding/deposit-address` | Your organisation's Gram (GRAM) deposit address on the TON network | No |
| [listGramDeposits](https://business.nasfampay.com/docs/reference/list-gram-deposits.md) | `GET /funding/deposits` | GRAM deposits to your address, and their state | No |
| [listEvents](https://business.nasfampay.com/docs/reference/list-events.md) | `GET /events` | Event log (30-day retention) | No |
| [getEvent](https://business.nasfampay.com/docs/reference/get-event.md) | `GET /events/{id}` | Retrieve an event | No |
| [listWebhookEndpoints](https://business.nasfampay.com/docs/reference/list-webhook-endpoints.md) | `GET /webhook-endpoints` | List webhook endpoints | No |
| [createWebhookEndpoint](https://business.nasfampay.com/docs/reference/create-webhook-endpoint.md) | `POST /webhook-endpoints` | Create a webhook endpoint (the secret is returned once) | No |
| [getWebhookEndpoint](https://business.nasfampay.com/docs/reference/get-webhook-endpoint.md) | `GET /webhook-endpoints/{id}` |  | No |
| [updateWebhookEndpoint](https://business.nasfampay.com/docs/reference/update-webhook-endpoint.md) | `PATCH /webhook-endpoints/{id}` |  | No |
| [deleteWebhookEndpoint](https://business.nasfampay.com/docs/reference/delete-webhook-endpoint.md) | `DELETE /webhook-endpoints/{id}` |  | No |
| [rotateWebhookSecret](https://business.nasfampay.com/docs/reference/rotate-webhook-secret.md) | `POST /webhook-endpoints/{id}/rotate-secret` | Issue a new secret. Both secrets sign for 24 hours. | No |
| [listWebhookDeliveries](https://business.nasfampay.com/docs/reference/list-webhook-deliveries.md) | `GET /webhook-endpoints/{id}/deliveries` |  | No |
| [replayWebhookDelivery](https://business.nasfampay.com/docs/reference/replay-webhook-delivery.md) | `POST /webhook-deliveries/{id}/replay` | Resend the same event (same webhook-id). Never creates a financial event. | No |
| [sendWebhookTestEvent](https://business.nasfampay.com/docs/reference/send-webhook-test-event.md) | `POST /webhook-endpoints/{id}/test` | Send one test event of a type the endpoint subscribes to. It is marked and synthetic, and never a real order or funding. | No |
| [getAccount](https://business.nasfampay.com/docs/reference/get-account.md) | `GET /account` |  | No |
| [createSandboxGramDeposit](https://business.nasfampay.com/docs/reference/create-sandbox-gram-deposit.md) | `POST /sandbox/funding/deposits` | Simulate a GRAM deposit to your address (sandbox host only; 404 in production) | Yes |
| [createSandboxDeposit](https://business.nasfampay.com/docs/reference/create-sandbox-deposit.md) | `POST /sandbox/deposits` | Simulate a GRAM deposit to your address (sandbox host only; 404 in production) | Yes |
| [listSandboxTestRuns](https://business.nasfampay.com/docs/reference/list-sandbox-test-runs.md) | `GET /sandbox/test-runs` | The organisation's test runs, newest first (sandbox host only). Kept 30 days. | No |
| [createSandboxTestRun](https://business.nasfampay.com/docs/reference/create-sandbox-test-run.md) | `POST /sandbox/test-runs` | Run a simulated order through the integration steps (sandbox host only; 404 in production). Writes no order and moves no money. | No |
| [getSandboxTestRun](https://business.nasfampay.com/docs/reference/get-sandbox-test-run.md) | `GET /sandbox/test-runs/{id}` | One test run (sandbox host only). The first read with a key passes the run's status_retrieval step. | No |

## Amounts

| Field | Name | Description |
| --- | --- | --- |
| Amount | `amount`, integer, required | USD, in cents. 0 to 100000000000. |
| Currency | `currency`, string, required | USD. One of `USD`. |

## Order statuses

| Status | Name | Your money | What to do |
| --- | --- | --- | --- |
| Processing | `processing` | Held. Delivery is in progress. | Wait for the next state. |
| Succeeded | `succeeded` | Captured. The order is paid for. | Nothing. `completed_at` is set. |
| Failed | `failed` | Released back to `available`. | Read `status_reason`; order again if it makes sense. |
| Under review | `under_review` | Your funds stay held. | No action needed. |

## Event types

- `order.accepted`
- `order.processing`
- `order.succeeded`
- `order.failed`
- `order.refunded`
- `order.under_review`
- `funding.credited`
- `deposit.confirmed`
- `balance.low`
- `balance.recovered`

## Authentication and keys

One bearer key per environment, sent on every request.

Every request carries an API key as a bearer token: `Authorization: Bearer nbk_test_...`. There are no sessions, no cookies and no signed requests; the key is the credential, so treat it like a password.

Full page: [Authentication and keys](https://business.nasfampay.com/docs/authentication.md)

## Create a Sandbox API key

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

**Sandbox step 2 of 7: Create a Sandbox API key.** Previous: [Add test funds](https://business.nasfampay.com/docs/add-test-funds). Next: [Learn recipient lookup](https://business.nasfampay.com/docs/confirm-recipient).

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.

Full page: [Create a Sandbox API key](https://business.nasfampay.com/docs/sandbox.md)

## Idempotency and safe retries

How to retry any request, including one that changes your balance, without ever paying twice.

Networks fail after the server has acted. A timeout does not tell you whether the order was created, so the API lets you ask the same question again: send the same request with the same `Idempotency-Key`, and you get the operation it created, never a duplicate.

Full page: [Idempotency and safe retries](https://business.nasfampay.com/docs/idempotency.md)

## Orders and statuses

The ways to create an order, the four states it can be in, and where your money is in each.

An order is one delivery of Stars or Premium to one Telegram username. It is created in one request and accepted with 202, with its amount held on your balance. It then moves on its own: the amount is captured if the order succeeds and released if it fails. The order record is what you reconcile against: the API has no receipt object.

Availability: **Available**. Live and verified in production.

Full page: [Orders and statuses](https://business.nasfampay.com/docs/orders.md)

## Funding your account

How a business account is funded, how the balance is held, and how to read every movement on it.

Fund your account with crypto. Once your deposit is verified, your available balance is updated. Your balance is prepaid service credits in USD. Orders are paid from that prepaid balance: the API holds the amount of each order while it is delivered, captures it on success and releases it on failure.

Availability: **Available**. Live and verified in production. In the sandbox the balance holds test money, added with **Add test funds** in your dashboard or a simulated GRAM deposit.

Full page: [Funding your account](https://business.nasfampay.com/docs/funding.md)

## Webhooks

Be told when an order ends or money arrives, instead of polling.

Register an HTTPS endpoint and the events you want. Each event carries the full snapshot of the order, funding or deposit it is about, and each delivery is signed with your endpoint's secret. Every attempt to deliver it is recorded, a failed attempt is retried, and any delivery can be replayed. The same events are also in the event log for 30 days, so nothing is lost if your endpoint is down.

Availability: **Available**. Live and verified in production.

> **Warning.** Verify the signature over the raw body, exactly as it arrived, before you parse it. A body parsed and written out again is not the bytes that were signed, and the check fails.

Full page: [Webhooks](https://business.nasfampay.com/docs/webhooks.md)

## Errors

Every error is a problem document with a stable code. Find a code, its usual cause and how to recover.

When a request cannot be served, the response is an RFC 9457 problem with the media type `application/problem+json`. Branch on `code`, show `detail` to a person, and keep `request_id` for support. Any status other than the ones an operation lists for success is an error of this shape.

Full page: [Errors](https://business.nasfampay.com/docs/errors.md)

## Rate limits

What the API does when you send too much, and how to back off.

Requests past the limit are refused with 429 and the code `rate_limited`. The response carries a `Retry-After` header with the number of seconds to wait. Some 503 responses carry it too. A successful response says how much of your budget is left, so you can slow down before you are refused.

Full page: [Rate limits](https://business.nasfampay.com/docs/rate-limits.md)
