Skip to content

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):

  • WALLET - 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:

  • WALLET - 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)
}