Redeem token

From ePrize Developers Wiki

Current revision

API Home Page :: Games and Awards

Summary

Redeem token and play the instant win game. If the token is valid, the result of this POST will be a win or non-winning message for the instant win game.

Win responses will contain a prize identifier in the awards node. Non-winning responses will not contain a prize identifier and have an empty awards node. The prize identifiers can be used with the fetch prize resource to find out more information on the prize (such as a description). This can be used to show the user a win or non-win scenario on the front-end.

Resource

/v1/{apikey}/game/{game}/token/{token}

Valid Methods

POST

Resource Arguments

Note: resource arguments are always required.

apikey: Your API Key.

gameId: Game Identifier for the Sweepstakes into which the entry will be awarded. (A constant value provided to you by HelloWorld)

token: Token ID retrieved from response from awarding a token

Parameters Required

None

Note: some user have had difficulty with empty POST requests. Adding a random name/value pair (foo=foo) to the request representation can avoid this problem.

Extra Notes

A successful redemption changes the representation of the token. Tokens awarded are available on the fetch token resource until they are redeemed.

Example: Redeem Token / Earn Prize

Summary

This demonstrates a good request to redeem a token that exists, and the user wins a prize as a result.

Response

HTTP Status Code: 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<result ver="1.0">
  <token>
    <id>{token}</id>
    <profile>{profile}</profile>
    <game>{game}</game>
    <redeemed>true</redeemed>
    <awards>
      <prizes>
        <prize>/v1/{apikey}/game/{game}/prize/{prize}</prize>
      </prizes>
    </awards>
  </token>
</result>

Example: Redeem Token / Earn New Token

Summary

This demonstrates a good request to redeem a token that exists, and the user wins another token as a result.

Response

HTTP Status Code: 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<result ver="1.0">
  <token>
    <id>{token}</id>
    <profile>{profile}</profile>
    <game>{game}</game>
    <redeemed>true</redeemed>
    <awards>
      <tokens>
        <token>/v1/{apikey}/game/{game}/token/{token2}</token>
      </tokens>
    </awards>
  </token>
</result>

Example: Redeem Token / Earn Nothing :(

Summary

This demonstrates a good request to redeem a token that exists, and the user wins nothing as a result.

Response

HTTP Status Code: 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<result ver="1.0">
  <token>
    <id>{token}</id>
    <profile>{profile}</profile>
    <game>{game}</game>
    <redeemed>true</redeemed>
    <awards/>
  </token>
</result>

Example: Redeem Token That Doesn't Exist

Summary

This demonstrates a good request to redeem a token that doesn't exist.

Response

HTTP Status Code: 404 Not Found

<?xml version="1.0" encoding="UTF-8"?>
<result ver="1.0">
  <status>0</status>
</result>

Example: Attempt to Redeem a Token That Has Already Been Redeemed

Response

HTTP Status Code: 404 Not Found

<?xml version="1.0" encoding="UTF-8" ?>
<result/>

Example: Attempt to Redeem a Token Beyond Game's Limit

Summary

If tokens are accumulated without redemption it might be possible to attempt to play the game more than is allowed based on the game's limit.

Response

HTTP Status Code: 403 Forbidden

<?xml version="1.0" encoding="UTF-8" ?>
<result/>

Example: Invalid Request

Summary

Request is not well-formed or contains other invalid inputs