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

{danger} 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: ACCOUNT,
            }
        }
    }) {
        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
    }
}