Skip to content
TradeSafe Documentation

Tokens

User tokens allow you to capture personal user data without needing to store the data in your application. When a token is created the api provides a unique ID to associate with a user account in your application.

A user token consists of 4 parts:

  • User information
  • Organization Information (If business)
  • Bank Account Information (Optional for buyers)
  • Payment Settings

List tokens

The tokens query is used to get a list of tokens that you have created. By default your organization already has a token generated as part of the signup process.

query tokens {
    tokens {
        data {
            id
            name
            reference
            user {
                givenName
                familyName
                email
                mobile
            }
            organization {
                name
                tradeName
                type
                registration
                taxNumber
            }
        }
    }
}

Retrieve a token

You can retrieve a token using the token query.

query token {
    token(id: "abc...xyz") {
        data {
            id
            name
            reference
            balance
            user {
                givenName
                familyName
                email
                mobile
            }
            organization {
                name
                tradeName
                type
                registration
                taxNumber
            }
        }
    }
}

Create a token

A token is created using the tokenCreate mutation.

All user details are required when creating a token.

Organization information, banking details and settings are optional and can be added at a later stage if/when needed.

Banking details can only be added to a token once and cannot be updated. When updating banking details you will need to recreate the token for the user. If you have active transactions they will use the token you provided when you created the transaction and can only be changed by contacting support.

Example of tokenCreate

mutation tokenCreate {
    tokenCreate(input: {
        user: {
            givenName: "First Name",
            familyName: "Last Name",
            email: "email@example.net",
            mobile: "+27000000000",
        }
        organization: {
            name: "Org Name"
            tradeName: "Trading As name"
            type: PRIVATE
            registrationNumber: "0000/000000/00"
            taxNumber: "000000000"
        }
        bankAccount: {
            accountNumber: "0000000000",
            accountType: CHEQUE,
            bank: SBSA
        }
        settings: {
            payout: {
                interval: IMMEDIATE,
                refund: WALLET,
            }
        }
    }) {
        id
        name
    }
}

In the above example an ID is returned, you can store this ID as part of your users profile and use it to update the token as needed.

Update a token

To updating a token only the ID and fields that require an update need to be submitted.

Example of tokenUpdate

mutation tokenUpdate {
    tokenUpdate(id: "abc...xyz", input: {
        user: {
            email: "email@example.net",
            mobile: "+27000000000"
        }
        organization: {
            tradeName: "Trading As name"
        }
    }) {
        id
        name
    }
}

Get the payment history of a token

You can get a payment history of a token by using the tokenStatement query. This data can be used to present a list of debits and credits to a user or be used for data reconciliation.

The statement works as a simple leger listing debits and credits.

query statement {
    tokenStatement(id: "abc...xyz" first: 10, page: 1) {
        data {
            type
            amount
            status
            reference
            createdAt
            updatedAt
        }
    }
}

There are several fields available in the query.

  • Type: The type of transaction Debit (Remove money) or Credit (Add money)
  • Amount: lists the value of the entry
  • Status: The status of the transaction in most cases this will be accepted (ACSP). In the event of a withdrawal or payout this may show pending (PDNG), this means that the pay-out has been scheduled and will transition to accepted once payment has been confirmed by our bank.
  • Reference: A description of where the funds are going or came from.
{
    "data": {
        "tokenStatement": {
            "data": [
                {
                    "type": "CREDIT",
                    "amount": 10000,
                    "status": "ACSP",
                    "reference": "ESCROW",
                    "createdAt": "2023-08-25 08:25:21",
                    "updatedAt": "2023-08-25 08:25:25"
                }
            ]
        }
    }
}

Withdraw funds from token wallet

If a user would like to have funds withdrawn and paid out to their bank account. The tokenAccountWithdraw mutation can be used.

Once created the request will appear as a debit entry in the statement.

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

The mutation will return a true if the request was successful and false if it was not.

{
    "data": {
        "tokenAccountWithdraw": true
    }
}

Real Time Clearance (Instant EFT)

To trigger a real time clearance set rtc to true

mutation withdraw {
  tokenAccountWithdraw(id: "abc..xyz", value: 500.00, rtc: true)
}

Testing payments with token Wallets

To help test wallet payments. Funds can be added to a token using the tokenUpdateFunds mutation.

mutation updateBalance {
  tokenUpdateBalance(id: "abc...xyz", value: 500.00, type: CREDIT) {
    id
    balance
  }
}