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"
                }
            ]
        }
    }
}

Deposit funds into token wallet

Users can deposit funds into their wallet using a link generated using the tokenDeposit mutation.

When a user visits the link they will be prompted for a deposit amount. Once they have entered the amount that they would like to be deposited they can then use one of the payment options to make the deposit.

mutation deposit {
    tokenDeposit(id: "abc..xyz", embed: false) {
        id
        url
        expiresAt
    }
}
{
    "data": {
        "tokenDeposit": {
          "id": "UGF5bWVudEludGVudDowMTkyYTAzZS1jYjg3LTcwZTItYWRmMS0zNjVlY2VkMjNmMjQ=",
          "url": "https:\/\/pay-sandbox.tradesafe.dev\/ZtCX4HYqjRN",
          "expiresAt": "2024-10-18 16:28:42"
        }
    }
}

You can also limit the payment methods available to a user by setting the paymentMethods field.

The timeout for the deposit page can be set using the minutes field.

mutation deposit {
    tokenDeposit(id: "abc..xyz", embed: true, paymentMethods: [CARD, EFT], minutes: 10) {
        id
        url
        expiresAt
    }
}

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

Transferring funds between tokens

Funds can be transferred between wallets. The source wallet needs to have enough funds for a transfer to be successful.

  • The sourceId is the wallet with the funds
  • The destinationId is where the funds will be sent to
  • Value is the amount that will be transferred
  • Reason is a description of the transfer, this will also appear on the destination wallet statement
mutation tokenTransferFunds {
  tokenTransferFunds(sourceId: "abc...xyz", destinationId: "abc...xyz", value: 100, reason: "Reason for transfer")
}

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
    }
}