Share Tokens

The Kigo API allows users to share tokens with others, enabling them to transfer ownership or access to various digital assets like gift cards, offers, or other tokens.

Prerequisites

Before performing the share action on a token, ensure that the necessary user-level session token has been obtained. This token is required to authenticate API requests and can be acquired by following the User Client Level Authentication.

Steps to Implement

1. Sharing a Token

   • Purpose: The share action generates a claim code that the recipient can use to claim the token. This functionality is useful for sending tokens like gift cards or offers to other users.
   • Usage: The application should only present the share option if the token can be shared, as indicated by the flags.is_shareable property in the token’s response data.

2. Determining If a Token Can Be Shared

   • flags.is_shareable Property: The ability to share a token is determined by the flags.is_shareable property in the token’s response data. If this property is set to true, the token is eligible to be shared. If it is false, the token cannot be shared, and the share option should not be presented to the user.

3. Handling Shared Tokens

   • Claim Code: After sharing a token, the application should securely display the claim code to the user. The recipient will use this code to claim the token into their account.
   • Token Transfer: Once the token is claimed using the provided claim code, it is removed from the original user’s wallet and transferred to the recipient’s wallet. The original user will no longer have access to the token.
   • Cancelling a Share: If the token has not yet been claimed, the original user has the option to cancel the share. This can be done using the Cancel a pending shared token. API call, which will invalidate the claim code and prevent the recipient from claiming the token.

API Call

To share a token, use the API endpoint associated with sharing tokens. Refer to Share a token. for specific details on the API request and response structure.

Key Considerations

1. Claim Code Security: The claim code generated when sharing a token is sensitive information. Ensure it is transmitted securely to the intended recipient.
2. Token Transfer: Once a token is claimed, it is removed from the original user’s wallet and placed into the recipient’s wallet, effectively transferring ownership.

Example Workflow

1. User decides to share a token: The user selects a token from their wallet that they want to send to someone else.
2. The application checks the token’s flags.is_shareable property: The application checks this property in the token’s response data to determine if the token can be shared.
3. The token is shared: The application makes the Share a token. API call. A claim code is returned and displayed to the user.
4. Recipient claims the token: The recipient uses the claim code to add the token to their account by following the process outlined in the Claim a token. documentation.
5. Optionally, the user can cancel the share: If the token has not yet been claimed, the user can cancel the share using the Cancel a pending shared token. API call.