Skip to content

Funding your account

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

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

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.

At a glance

What it is
NetworkTON.
Asset you depositNative GRAM, the coin of TON, formerly Toncoin (TON). No other asset is credited. See Funding with GRAM.
What the balance isPrepaid service credits in USD. See Balances and reference rates.

The three figures

FigureMeaning
AvailableavailableWhat new orders can be paid from.
HeldheldReserved by orders in progress or under review. Returns to available if they fail, is captured if they succeed.
Pending fundingpending_fundingMoney received and not yet credited.

GET /balance returns the three with updated_at, and a gram section when the workspace holds GRAM. The three are integers in cents of their currency; usd carries them exactly, in micro-dollars, and gram in nanogram. Money fields says what every field holds. An order larger than available is refused with insufficient_funds.

Code for The three figures
GET /v1/balanceSandbox, test key
// npm install axiosimport axios from 'axios';try {  const { status, data: balance } = await axios.get(    'https://sandbox-api.nasfampay.com/v1/balance',    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,      },    },  );  console.log(status, balance);} catch (error) {  if (!axios.isAxiosError(error) || !error.response) throw error;  const problem = error.response.data;  throw new Error(`${problem.status} ${problem.code}: ${problem.title} (request ${problem.request_id})`);}

Fundings

GET /fundings lists each credit, newest first, with its amount, received_at, credited_at and a status. Add test funds appears here. A GRAM deposit has a list of its own, GET /funding/deposits; see Funding with GRAM.

StatusMeaning
PendingpendingReceived, not yet credited (counted in pending_funding).
CreditedcreditedOn the balance. Raises one funding.credited event.
HeldheldKept back, not credited. No event is raised for it.
RejectedrejectedNot accepted.

payer_name_masked, when present, is a masked form of the sender's name. The contract does not say how long a funding stays pending, or why one is held or rejected.

Code for Fundings
GET /v1/fundingsSandbox, test key
// npm install axiosimport axios from 'axios';try {  const { status, data: fundings } = await axios.get(    'https://sandbox-api.nasfampay.com/v1/fundings',    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,      },    },  );  console.log(status, fundings);} catch (error) {  if (!axios.isAxiosError(error) || !error.response) throw error;  const problem = error.response.data;  throw new Error(`${problem.status} ${problem.code}: ${problem.title} (request ${problem.request_id})`);}

Statement

GET /balance/transactions is every movement on the balance, newest first. Each carries a signed amount, the change to available (an order_capture moves held money and shows 0), the available_after it left, and the order_id or funding_id it belongs to. The contract lists the types without describing them; the meanings follow their names:

TypeMeaning
Funding creditfunding_creditA funding credited to the balance.
Order reserveorder_reserveAn order's amount moved from available to held.
Order captureorder_captureA held amount taken for a delivered order.
Order releaseorder_releaseA held amount returned after a failed order.
AdjustmentadjustmentA correction to the balance.
ReversalreversalA movement that reverses an earlier one.
Gram conversiongram_conversionA GRAM deposit credited to the balance, at the rate recorded with the deposit.

Reconcile by walking the statement: each order appears as an order_reserve and later as an order_capture or an order_release, each naming its order_id. A GRAM deposit that became credits is on it as a gram_conversion. GRAM a workspace still holds as GRAM is not: read gram on GET /balance, and GET /funding/deposits.

Code for Statement
GET /v1/balance/transactionsSandbox, test key
// npm install axiosimport axios from 'axios';try {  const { status, data: transactions } = await axios.get(    'https://sandbox-api.nasfampay.com/v1/balance/transactions',    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,      },    },  );  console.log(status, transactions);} catch (error) {  if (!axios.isAxiosError(error) || !error.response) throw error;  const problem = error.response.data;  throw new Error(`${problem.status} ${problem.code}: ${problem.title} (request ${problem.request_id})`);}

Low balances

balance.low is sent when your low-balance alert fires, and only if you chose the webhook channel for that alert; it names no amount, so read GET /balance for the figures. Without an alert nothing tells you: read GET /balance before a batch of orders, and subscribe to funding.credited to be told when a funding arrives. deposit.confirmed says a GRAM deposit is confirmed, before it is credited: read GET /funding/deposits for its status.

Common mistakes

  • Counting pending_funding as money to spend. Only available pays for an order.
  • Adding held to available. A held amount belongs to an order in progress. It returns only if that order fails.
  • Converting a figure yourself. Store the integers, and show the decimal strings the server sends as they are. Money fields says which field is which.