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 | |
|---|---|
| Network | TON. |
| Asset you deposit | Native GRAM, the coin of TON, formerly Toncoin (TON). No other asset is credited. See Funding with GRAM. |
| What the balance is | Prepaid service credits in USD. See Balances and reference rates. |
The three figures
| Figure | Meaning |
|---|---|
| Availableavailable | What new orders can be paid from. |
| Heldheld | Reserved by orders in progress or under review. Returns to available if they fail, is captured if they succeed. |
| Pending fundingpending_ | Money 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.
// 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.
| Status | Meaning |
|---|---|
| Pendingpending | Received, not yet credited (counted in pending_funding). |
| Creditedcredited | On the balance. Raises one funding.credited event. |
| Heldheld | Kept back, not credited. No event is raised for it. |
| Rejectedrejected | Not 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.
// 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:
| Type | Meaning |
|---|---|
| Funding creditfunding_ | A funding credited to the balance. |
| Order reserveorder_ | An order's amount moved from available to held. |
| Order captureorder_ | A held amount taken for a delivered order. |
| Order releaseorder_ | A held amount returned after a failed order. |
| Adjustmentadjustment | A correction to the balance. |
| Reversalreversal | A movement that reverses an earlier one. |
| Gram conversiongram_ | A 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.
// 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_fundingas money to spend. Onlyavailablepays for an order. - Adding
heldtoavailable. 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.
Related guides
- Create a test order: add test funds, then watch the hold.
- Orders and statuses: what each status does to the held amount.
- Sandbox scenarios: where the money is in every case.
