# 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. Contract 1.0.0-draft.10. The [OpenAPI document](https://business.nasfampay.com/docs/openapi.json) is the only source of endpoints, fields, statuses and errors: an operation or a field it does not define does not exist. 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. A developer creates a sandbox key in the dashboard; a live key exists only once the business is activated for live. - Every page below is Markdown: the page's own address with `.md`. - [skill.md](https://business.nasfampay.com/docs/skill.md): the rules for a coding assistant that integrates this API. - [llms-full.txt](https://business.nasfampay.com/docs/llms-full.txt): an index of the full text of every page below, which is 21 files by task, each under 96 KB. ## Start here - [Build with Nasfam Business](https://business.nasfampay.com/docs/introduction.md): Order digital products, fund your balance with crypto, and follow every order, through one API. - [Getting started](https://business.nasfampay.com/docs/getting-started.md): Your first order in five steps: get a key, choose Stars or Premium, write the body, send it, and track it. - [Integration guides](https://business.nasfampay.com/docs/guides.md): Every guide to integrating Nasfam Business, by what you are building. - [API reference](https://business.nasfampay.com/docs/reference.md): Every operation in contract 1.0.0-draft.10, generated from the pinned OpenAPI document. ## Follow the onboarding steps - [Create your account](https://business.nasfampay.com/docs/developer-account.md): Sign up in the dashboard and verify your email. - [Set up your workspace](https://business.nasfampay.com/docs/workspace.md): Name the organisation your keys, balance, orders and webhooks belong to, and add your team. - [Add test funds](https://business.nasfampay.com/docs/add-test-funds.md): Credit your Sandbox balance with test money, so your test orders have something to spend. - [Complete the guided test order](https://business.nasfampay.com/docs/guided-test-order.md): Place one Sandbox order from the dashboard, step by step, and see every part of an order before you write code. - [Send your own API order](https://business.nasfampay.com/docs/first-request.md): One request that creates a sandbox order for Telegram Stars or Premium, then the order read back by its id. - [Create a test order](https://business.nasfampay.com/docs/quickstart.md): Add test funds, see the amount held, and create one order that a retry can never duplicate. - [Verify order status](https://business.nasfampay.com/docs/responses-and-webhooks.md): An order finishes after the response. Read its final state, receive the event, and retry without creating a second order. ## Authenticate and make safe requests - [Authentication and keys](https://business.nasfampay.com/docs/authentication.md): One bearer key per environment, sent on every request. - [Create and manage API keys](https://business.nasfampay.com/docs/api-keys.md): Create, rotate and revoke keys in your dashboard. The API itself never makes a key. - [Idempotency and safe retries](https://business.nasfampay.com/docs/idempotency.md): How to retry any request, including one that changes your balance, without ever paying twice. - [Errors](https://business.nasfampay.com/docs/errors.md): Every error is a problem document with a stable code. Find a code, its usual cause and how to recover. - [Rate limits](https://business.nasfampay.com/docs/rate-limits.md): What the API does when you send too much, and how to back off. - [Versioning](https://business.nasfampay.com/docs/versioning.md): The version in the address, the version of the contract, and what can change under your integration. - [Recovering from failures](https://business.nasfampay.com/docs/failure-recovery.md): What to do when a request fails or its answer never arrives, case by case, with where your money is in each. ## Choose a product - [Telegram Stars](https://business.nasfampay.com/docs/telegram-stars.md): Deliver Telegram Stars to a Telegram account from your prepaid balance: find the account, have your customer confirm it, then order and follow it to delivery. - [Telegram Premium](https://business.nasfampay.com/docs/telegram-premium.md): Gift Telegram Premium subscriptions of 3, 6 or 12 months to a Telegram account from your prepaid balance: find the account, have your customer confirm it, then order and follow it to delivery. - [List products](https://business.nasfampay.com/docs/reference/list-products.md): `GET /products`. List products. ## Build a first order, step by step - [Choose Stars or Premium](https://business.nasfampay.com/docs/choose-a-product.md): The two products you can order, what each is bought by, and the tutorial that takes each to a delivered Sandbox order. - [Learn recipient lookup](https://business.nasfampay.com/docs/confirm-recipient.md): Show your customer the Telegram account behind the username they typed, and order only once they confirm it. - [Your first Telegram Stars order](https://business.nasfampay.com/docs/first-stars-order.md): One Telegram Stars order from your key to delivery: look the recipient up, confirm, order, track, retry safely and handle the webhook. - [Your first Telegram Premium order](https://business.nasfampay.com/docs/first-premium-order.md): One Telegram Premium order from your key to delivery: look the recipient up, confirm, order, track, retry safely and handle the webhook. ## Confirm the recipient and price the order - [Recipient lookup and confirmation](https://business.nasfampay.com/docs/recipient-lookup.md): Show your customer the Telegram account behind a username, with its name and photo, before you quote Stars or Premium. - [Quotes](https://business.nasfampay.com/docs/quotes.md): Check a recipient and hold a price for up to 60 seconds, before any money moves. - [Pricing and costs](https://business.nasfampay.com/docs/pricing.md): What each request costs, where the price of an order comes from, and what to do when your balance is short. - [Create recipient lookup](https://business.nasfampay.com/docs/reference/create-recipient-lookup.md): `POST /recipient-lookups`. Look up a Telegram recipient before quoting. - [Lookup recipient](https://business.nasfampay.com/docs/reference/lookup-recipient.md): `GET /recipients/lookup`. Check a Telegram username before ordering (optional). - [Create quote](https://business.nasfampay.com/docs/reference/create-quote.md): `POST /quotes`. Verify a recipient and lock a price for up to 60 seconds. ## Place and follow an order - [Orders and statuses](https://business.nasfampay.com/docs/orders.md): The ways to create an order, the four states it can be in, and where your money is in each. - [Order lifecycle](https://business.nasfampay.com/docs/order-lifecycle.md): Every transition an order can make, the money movement and the event that goes with each, and what ends it. - [Transaction statuses](https://business.nasfampay.com/docs/statuses.md): Every status an order or a funding can have, where your money is in each, and how to read a status change. - [List orders](https://business.nasfampay.com/docs/reference/list-orders.md): `GET /orders`. List orders. - [Create order](https://business.nasfampay.com/docs/reference/create-order.md): `POST /orders`. Create an order (funds are reserved before the response). - [Get order](https://business.nasfampay.com/docs/reference/get-order.md): `GET /orders/{id}`. Retrieve an order. ## Fund your account - [Funding your account](https://business.nasfampay.com/docs/funding.md): How a business account is funded, how the balance is held, and how to read every movement on it. - [Funding with GRAM](https://business.nasfampay.com/docs/gram-funding.md): The asset, your deposit address, what is safe to send, and when a deposit is credited. - [Networks and assets](https://business.nasfampay.com/docs/networks-and-assets.md): The one network and the one asset that fund an account, and what must never be sent. - [Add real funds](https://business.nasfampay.com/docs/fund-with-crypto.md): Fund your account with crypto, sent to your own deposit address. Your balance is updated once the deposit is verified. - [List fundings](https://business.nasfampay.com/docs/reference/list-fundings.md): `GET /fundings`. Incoming transfers and their state. - [Get deposit address](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. - [List gram deposits](https://business.nasfampay.com/docs/reference/list-gram-deposits.md): `GET /funding/deposits`. GRAM deposits to your address, and their state. ## Read the balance and the rates - [Balances and reference rates](https://business.nasfampay.com/docs/balance-and-rates.md): What your balance is, how a deposit becomes USD credits, and how fresh a reference rate must be. - [List prices](https://business.nasfampay.com/docs/reference/list-prices.md): `GET /prices`. The USD price book in effect, with indicative GRAM figures. - [Get rates](https://business.nasfampay.com/docs/reference/get-rates.md): `GET /rates`. The GRAM/USD reference rate GRAM quotes are priced at, and display rates. - [Get balance](https://business.nasfampay.com/docs/reference/get-balance.md): `GET /balance`. Available, held and pending-funding balances. - [List balance transactions](https://business.nasfampay.com/docs/reference/list-balance-transactions.md): `GET /balance/transactions`. Every movement on the balance. ## Read statements and spending limits - [List statements](https://business.nasfampay.com/docs/reference/list-statements.md): `GET /statements`. The workspace's statements, newest first. - [Create statement](https://business.nasfampay.com/docs/reference/create-statement.md): `POST /statements`. Request an account statement for whole local days. - [Get statement](https://business.nasfampay.com/docs/reference/get-statement.md): `GET /statements/{id}`. One statement, its state and, once ready, its reconciled summary. - [Get limits](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. ## Receive events - [Webhooks](https://business.nasfampay.com/docs/webhooks.md): Be told when an order ends or money arrives, instead of polling. ## Manage webhook endpoints - [List webhook endpoints](https://business.nasfampay.com/docs/reference/list-webhook-endpoints.md): `GET /webhook-endpoints`. List webhook endpoints. - [Create webhook endpoint](https://business.nasfampay.com/docs/reference/create-webhook-endpoint.md): `POST /webhook-endpoints`. Create a webhook endpoint (the secret is returned once). - [Get webhook endpoint](https://business.nasfampay.com/docs/reference/get-webhook-endpoint.md): `GET /webhook-endpoints/{id}`. - [Update webhook endpoint](https://business.nasfampay.com/docs/reference/update-webhook-endpoint.md): `PATCH /webhook-endpoints/{id}`. - [Delete webhook endpoint](https://business.nasfampay.com/docs/reference/delete-webhook-endpoint.md): `DELETE /webhook-endpoints/{id}`. - [Rotate webhook secret](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. - [List webhook deliveries](https://business.nasfampay.com/docs/reference/list-webhook-deliveries.md): `GET /webhook-endpoints/{id}/deliveries`. - [Replay webhook delivery](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. - [Send webhook test event](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. ## Test deliveries and read the event log - [Testing webhooks](https://business.nasfampay.com/docs/webhook-testing.md): Prove your endpoint verifies a delivery and handles a failure, a repeat and a replay, using only what the contract defines. - [List events](https://business.nasfampay.com/docs/reference/list-events.md): `GET /events`. Event log (30-day retention). - [Get event](https://business.nasfampay.com/docs/reference/get-event.md): `GET /events/{id}`. Retrieve an event. ## Choose an environment - [Sandbox and Live](https://business.nasfampay.com/docs/environments.md): Two hosts, two kinds of key and two balances. What is the same, what differs, and how to tell where a request went. ## Test in the sandbox - [Create a Sandbox API key](https://business.nasfampay.com/docs/sandbox.md): Create a sandbox key, keep it safe, and be sure the sandbox is where your requests go. - [Sandbox scenarios](https://business.nasfampay.com/docs/sandbox-scenarios.md): What you can make the sandbox do, what only it decides, and where the money is in each case. - [Create sandbox gram deposit](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). - [Create sandbox deposit](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). - [List sandbox test runs](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. - [Create sandbox test run](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. - [Get sandbox test run](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. ## Prepare for launch - [Continue to Live](https://business.nasfampay.com/docs/continue-to-live.md): What the Sandbox must show before Live opens, how you move across, and what stays behind. - [Complete Live activation](https://business.nasfampay.com/docs/going-live.md): How a workspace reaches Live: the four tiers, the automated checks, and what a restriction means. - [Create a Live API key](https://business.nasfampay.com/docs/live-key.md): The key that moves real money, once your workspace is activated for Live. - [Send real orders](https://business.nasfampay.com/docs/live-request.md): The same code, the Live host and your Live key. A first read proves them, then the checklist, then your first real order. - [Your first Live order](https://business.nasfampay.com/docs/first-live-order.md): One real Telegram Stars order on the Live host, a step at a time, from your key to the money it moved. - [Your first Live order as one program](https://business.nasfampay.com/docs/live-order-program.md): Every step of a first Live order in one program for your server, for Telegram Stars or Telegram Premium. - [Get account](https://business.nasfampay.com/docs/reference/get-account.md): `GET /account`. ## Monitor Live orders - [Monitor orders and webhooks](https://business.nasfampay.com/docs/monitor-orders.md): Register your Live webhook endpoint, follow every order to its end, and reconcile the money each day. ## Plan crypto payouts (sandbox) - [Crypto Payouts](https://business.nasfampay.com/docs/payouts.md): Send crypto from your Nasfam Business USD balance to an approved wallet, priced first and followed until it is final. - [Get started with Crypto Payouts](https://business.nasfampay.com/docs/payouts-get-started.md): The first payout from a server: read the pairs, check the address, quote, send and follow it. - [Supported pairs](https://business.nasfampay.com/docs/payouts-networks.md): Which networks and assets a payout can be sent on, in each environment, and how to tell: the server says. - [Authentication for payouts](https://business.nasfampay.com/docs/payouts-authentication.md): Payouts take the same secret key as every other request, from your server only, with one of two scopes. - [Payout fees and limits](https://business.nasfampay.com/docs/payouts-fees-and-limits.md): What a payout costs is on its quote, in four parts. What it may be is your workspace's limits, read from the server. ## Send and follow a crypto payout (sandbox) - [Validate an address](https://business.nasfampay.com/docs/payouts-address-validation.md): Check an address's form for its network, and whether it is an approved destination. A valid address is not a safe one. - [Screening and approved destinations](https://business.nasfampay.com/docs/payouts-screening.md): Who a payout may be sent to: your approved destinations, each screened before it is paid. - [Estimate a payout](https://business.nasfampay.com/docs/payouts-quotes.md): A quote fixes what your balance will be charged for what the recipient receives, for up to 60 seconds. It holds nothing. - [Send a payout](https://business.nasfampay.com/docs/payouts-create.md): Send a payout to an approved destination. It holds money from your balance: one key, one payout. - [Track a payout](https://business.nasfampay.com/docs/payouts-tracking.md): Read where a payout is, what happened on its network and where its charge is. - [Following a payout](https://business.nasfampay.com/docs/payouts-webhooks.md): Each change of a payout is sent to an endpoint that subscribes to its events. Order them by version and read the payout before acting. ## Make crypto payouts safe (sandbox) - [Payout errors](https://business.nasfampay.com/docs/payouts-errors.md): Every refusal a payout request can answer, and what to do about each. - [Retrying a payout safely](https://business.nasfampay.com/docs/payouts-idempotency.md): One key, one payout. How to send again without ever paying twice. - [Test payouts in the sandbox](https://business.nasfampay.com/docs/payouts-sandbox.md): How payouts are tested on synthetic money before any real money moves. - [Production readiness for payouts](https://business.nasfampay.com/docs/payouts-going-live.md): What has to be true before a payout moves real money, on our side and on yours. ## Optional - [Accepting Stars or delivering them](https://business.nasfampay.com/docs/stars-delivery-vs-bot-payments.md): Telegram's Bot Payments API lets your bot accept Stars. Delivering Stars to a user's account is a different job. Which one you need, and why. - [Changelog](https://business.nasfampay.com/docs/changelog.md): Every change to the contract these pages are built from. - [SDKs and tools](https://business.nasfampay.com/docs/sdks.md): No SDK is published. The API is plain HTTP and JSON, with examples in the languages you already use. - [API explorer](https://business.nasfampay.com/docs/api-explorer.md): Create an order from your dashboard with no code: in the sandbox on test money, or in Live as a real order you confirm first. - [Frequently asked questions](https://business.nasfampay.com/docs/faq.md): Short answers: live access, how funding works, and what a timeout means.