Skip to content

Integration guides

Every guide to integrating Nasfam Business, by what you are building.

Each guide explains one part of an integration and links to the operations it uses in the API reference. Start with authentication if this is your first integration.

Authentication

  • Authentication and keys: One bearer key per environment, sent on every request.
  • API keys: Create, rotate and revoke keys in your dashboard. The API itself never makes a key.
  • Idempotency and safe retries: How to retry any request, including one that changes your balance, without ever paying twice.
  • Rate limits: What the API does when you send too much, and how to back off.
  • Versioning: The version in the address, the version of the contract, and what can change under your integration.

Environments

  • Sandbox scenarios: What you can make the sandbox do, what only it decides, and where the money is in each case.

Telegram Stars

  • Telegram Stars: 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.
  • First Stars order: One Telegram Stars order from your key to delivery: look the recipient up, confirm, order, track, retry safely and handle the webhook.
  • Accepting or delivering Stars: 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.

Telegram Premium

  • Telegram Premium: 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.
  • First Premium order: One Telegram Premium order from your key to delivery: look the recipient up, confirm, order, track, retry safely and handle the webhook.

Pricing

  • Pricing and costs: What each request costs, where the price of an order comes from, and what to do when your balance is short.
  • Quotes: Check a recipient and hold a price for up to 60 seconds, before any money moves.

Funding

  • Funding: How a business account is funded, how the balance is held, and how to read every movement on it.
  • Balances and rates: What your balance is, how a deposit becomes USD credits, and how fresh a reference rate must be.
  • GRAM deposits: The asset, your deposit address, what is safe to send, and when a deposit is credited.
  • Networks and assets: The one network and the one asset that fund an account, and what must never be sent.

Orders and statuses

  • Recipient lookup: Show your customer the Telegram account behind a username, with its name and photo, before you quote Stars or Premium.
  • Orders and statuses: The ways to create an order, the four states it can be in, and where your money is in each.
  • Order lifecycle: Every transition an order can make, the money movement and the event that goes with each, and what ends it.
  • Statuses: Every status an order or a funding can have, where your money is in each, and how to read a status change.

Webhooks

  • Webhooks: Be told when an order ends or money arrives, instead of polling.
  • Testing webhooks: Prove your endpoint verifies a delivery and handles a failure, a repeat and a replay, using only what the contract defines.

Errors and troubleshooting

  • Errors: Every error is a problem document with a stable code. Find a code, its usual cause and how to recover.
  • Failure recovery: What to do when a request fails or its answer never arrives, case by case, with where your money is in each.
  • FAQ: Short answers: live access, how funding works, and what a timeout means.

Crypto Payouts

  • Overview: Send crypto from your Nasfam Business USD balance to an approved wallet, priced first and followed until it is final.
  • Get started: The first payout from a server: read the pairs, check the address, quote, send and follow it.
  • Supported pairs: Which networks and assets a payout can be sent on, in each environment, and how to tell: the server says.
  • Authentication: Payouts take the same secret key as every other request, from your server only, with one of two scopes.
  • Validate an address: Check an address's form for its network, and whether it is an approved destination. A valid address is not a safe one.
  • Screening: Who a payout may be sent to: your approved destinations, each screened before it is paid.
  • Estimate: A quote fixes what your balance will be charged for what the recipient receives, for up to 60 seconds. It holds nothing.
  • Create: Send a payout to an approved destination. It holds money from your balance: one key, one payout.
  • Track: Read where a payout is, what happened on its network and where its charge is.
  • Webhooks: 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.
  • Errors: Every refusal a payout request can answer, and what to do about each.
  • Safe retries: One key, one payout. How to send again without ever paying twice.
  • Fees and limits: What a payout costs is on its quote, in four parts. What it may be is your workspace's limits, read from the server.
  • Testing in the sandbox: How payouts are tested on synthetic money before any real money moves.
  • Production readiness: What has to be true before a payout moves real money, on our side and on yours.

Tools

  • SDKs and tools: No SDK is published. The API is plain HTTP and JSON, with examples in the languages you already use.
  • API explorer: 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.