Managing Funds for a Token


Retrieving the balance for a token

The available balance for a token and be retrieved by adding the balance field when querying a token.

query token {
    token(id: "abc...xyz") {
        id
        name
        reference
        balance
        user {
            givenName
            familyName
            email
            mobile
        }
    }
}

Result:

{
    "data": {
        "token": {
            "id": "abc...xyz",
            "name": "Example (Pty) Ltd",
            "reference": "XCK69M3Z",
            "balance": 946979.4,
            "user": {
                "givenName": "Jane",
                "familyName": "Doe",
                "email": "jane.doe@example.com",
                "mobile": "+27123456789"
            }
        }
    }
}

Managing how payouts and refunds are handled

When configuring a token there are two settings for managing how an entity is paid.

The first is payout which manages how a seller, agent or beneficiary is paid out.

This field can only be modified if the token contains the following information:

  • An ID Number ID or an Organisation Registration Number (ID number if a Sole Prop)
  • Banking details


The following options are available (Weekly, Bi-monthly and Monthly pay-outs occur on a Friday):

  • ACCOUNT - Pay out funds to the escrow account for use in another transaction to be manually withdrawn at a later stage.
  • IMMEDIATE - Pay out funds as soon as possible
  • DAILY - Pay out funds the next work day
  • WEEKLY - Pay out funds once a week
  • BIMONTHLY - Pay out funds twice a per month
  • MONTHLY - Pay out funds once a month


The second field is refund which manages how a buyer is refunded.

The following options are available:

  • ACCOUNT - Pay out funds to the escrow account for use in another transaction to be manually withdrawn at a later stage.
  • IMMEDIATE - Pay out funds as soon as possible

Updating the payout and refund options are done in a similar way:

mutation tokenUpdate {
    tokenUpdate(id: "abc...xyz", input: {
        settings: {
            payout: {
                interval: WEEKLY
                refund: IMMEDIATE
            },
        }
    }) {
        id
        name
        settings {
            payout {
                interval
                refund
            }
        }
    }
}

Requesting a withdrawal

If funds have either been paid out or refunded to the escrow account. A withdrawal request can be initiated and will result in the requested value to be paid out in the next payment run.

{info} After a withdrawal has been successfully requested the balance reported will be the amount less the requested value. i.e. if the token has a balance of R1000 and a withdrawal of R700 is made the balance will show the remaining funds which would be R300.

A withdrawal can be requested as follows and will return true if request was successful:

mutation tokenAccountWithdraw {
    tokenAccountWithdraw(id: "abc...xyz", value: 1000)
}