> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stellarium.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Account: spend a payable contract's balance

> Reference for sh.stellarium.money.Account, the built-in resource payable contracts use to read their balance, earmark funding, pay payees and refund funders.

`sh.stellarium.money.Account` is the resource a [payable contract](https://docs.stellarium.sh/concepts/payable-contracts.md) uses to read and spend its own balance. Every node serves it itself, with the operator keeping the balance, so there is no peer to find and no other node that could answer for it. Bind it like any resource:

```kotlin theme={null}
const account: sh.stellarium.money.Account
```

A contract's balance is made of **funding**: how much each organization sent it, under which key, with which payees. Every outflow spends one organization's funding under one key, so one funder's money never pays for another's.

| Function | Parameters | Returns |
| - | - | - |
| [`balance`](#balance) | none | `int64` |
| [`earmark`](#earmark) | `key: string` | `void` |
| [`fundingOf`](#fundingof) | `org: string`, `key: string` | `int64` |
| [`canReceive`](#canreceive) | `org: string` | `boolean` |
| [`pay`](#pay) | `to: string`, `amount: int64`, `from: string`, `key: string` | `int64` |
| [`tryPay`](#trypay) | `to: string`, `amount: int64`, `from: string`, `key: string` | `boolean` |
| [`refund`](#refund) | `to: string`, `amount: int64`, `key: string` | `int64` |

Amounts are micro-USD (1 USD = 1,000,000). Pass `null` as `key` for funding that was never earmarked.

## Rules for every call

* **Only a running contract has a balance.** A call from a request script fails.
* **Each call evaluates to `{ value, error }`**, like any resource call. Read results with `.value`.
* **A failed call fails the run**, even if the contract ignores its `error`. The run's state changes are dropped and no money moves. Calls fail when they would spend more than the named funding, pay an organization that isn't one of its payees, pay one that can't receive payouts (except with `tryPay`), or use an amount that isn't a whole number greater than `0`.
* **Nothing moves while the contract runs.** Changes are staged, and apply only when the run that started everything succeeds. See [When money moves](https://docs.stellarium.sh/concepts/payable-contracts.md#when-money-moves).
* **Reads include the run's staged changes**, so `balance` after a `pay` in the same run shows the payment.
* **Calls are free.** The functions have no price. The operator takes the platform fee from `pay` itself.

## balance

Returns the contract version's balance, including what this run has received and spent so far.

```kotlin theme={null}
const left = account.balance().value
```

## earmark

Labels the money attached to this call with `key`, so it can be spent apart from the same funder's other money. Call it at most once per call, and only when `payment.amount` is more than `0`. A contract that holds several jobs for one buyer earmarks each payment with its job id, and then each job can spend only its own money.

```kotlin theme={null}
if (payment.amount > 0) {
    account.earmark(key: jobId)
}
```

## fundingOf

Returns how much of `org`'s funding under `key` is unspent, including this run's changes. Read it instead of keeping your own record of what was paid in: the [time limit](https://docs.stellarium.sh/concepts/payable-contracts.md#time-limit) can return money without running the contract.

```kotlin theme={null}
const due = account.fundingOf(org: payer, key: jobId).value
```

## canReceive

Returns whether `org` can be paid now: it has finished [payout setup](https://docs.stellarium.sh/concepts/payments.md#getting-paid), and it isn't frozen, banned or closed. Check it before you accept money for a payee.

## pay

Pays `amount` to `to` out of `from`'s funding under `key`, and returns what's left of that funding. `to` must be one of the funding's payees. The amount, less the 1% platform fee (rounded up), goes to the payee's payable balance and is paid out through Stripe Connect.

```kotlin theme={null}
account.pay(to: payee, amount: due, from: payer, key: jobId)
```

## tryPay

Like `pay`, but when `to` can't receive payouts, it pays nothing and returns `false`, so the run carries on. Use it when a contract pays several organizations in one run, so one payee that loses payout setup can't block the others, and keep or refund what it couldn't pay.

```kotlin theme={null}
if (account.tryPay(to: "org_data", amount: share, from: payment.from, key: null).value == false) {
    account.refund(to: payment.from, amount: share, key: null)
}
```

## refund

Returns `amount` of `to`'s funding under `key`, with no fee, and returns what's left of that funding. The money goes one step back: to `to`'s prepaid balance if a request script sent it, or to the balance of the contract that sent it, under the same funder, key and payees. No code runs on the way back.

```kotlin theme={null}
account.refund(to: payer, amount: due, key: jobId)
```

## Sending money to another contract

`Account` has no function for it. Attach the money to a call instead, naming whose funding it comes from:

```kotlin theme={null}
const job: com.example.Job@1
job.run{amount: due, from: buyer, key: orderId, payees: [provider]}(action: "fund", jobId: "", provider: provider, arbiter: arbiter)
```

The receiving contract sees `payment.from` as `buyer`. `payees` can narrow the funding's payees, never add to them. See [Attaching money to a call](https://docs.stellarium.sh/concepts/payable-contracts.md#attaching-money-to-a-call).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.