Playtem Integration Guide

Build an endpoint page for items credit

In order to credit virtual items, you need to develop an endpoint page. The Playtem platform is going to send all transaction details to this endpoint whenever users complete a purchase.

1 - Receive our request

All transaction details are appended to the HTTP GET parameters sent to your endpoint such as this example:

The payload contains all transaction details. For security purpose it is encoded in base64:

Payload = base64(JSON(AppId+AppName+UserId+Items+TransactionId+Signature))

To retrieve all transaction details you have to:

  1. Base64 decode the payload
  2. Parse the JSON
  3. Check the signature

Then you will get the transaction details in JSON format. For example:

        'AppId' : 3,
        'AppName' : 'GameName',
        'UserId' : 859895322,
        'Items' : [ 584, 388, 412 ],
        'TransactionId' : '42b64fa56-a50d2c12f',
        'Signature' : '71397F9C818642506C6CA47D0091BB6B7C9D6B76'

The table below describes all transaction details parameters:

Parameters Description

Specifies the game id where the item must be credited (useful if you have more than one game)

Example Values: 3


Specifies the game name where the item must be credited

Example Values: GameName


The Facebook user id for whom the item should be credited

Example Values: ab_59c


Specifies the list of item IDs to credit. Our engine will use IDs provided in the listing that you sent us in step 2.

Example Values: gh584xyz


Specifies the unique transaction identifier for the current request

Example Values: 42b64fa56-a50d2c12f

Signature: string

Use this security signature to ensure the authenticity of the current request. The way to compute this hash is explained in Signature section

Example Values: 71397F9C818642506C6CA47D0091BB6B7C9D6B76

2 - Validate the signature

The signature ensures the authenticity of the request. Every time you receive a request you should verify its authenticity by computing the signature and by comparing it with the one sent by our platform.

The signature is computed as:

Signature = HMAC-SHA1(AppId + UserId + Items + TransactionId)

If your computed signature doesn’t match with ours, ignore the request and return the appropriate error status code (see Step 3).

3 - Create the response

Once you received the information and parsed the json, you could reward your user. Then you respond to us:

  • If the item is successfully credited to the user, return a blank page and a HTTP 200 status code.
  • If an error occurred, return an HTTP 500 status code and put the error details in the ErrorMessage field.

Please set the HTTP content type response to “application/json”. The error details must be in JSON format as described below:

        "ErrorCode" : 402,
        "ErrorMessage" : "Item #4242 doesn't exist"

Here are the error codes you have to implement:

Error Code Mandatory error codes
400 Returns the 400 error code when an error not listed below occurred
402 Returns the 402 error code when the item requested doesn’t exist
407 Returns the 407 error code when the payload decode failed or in case of signature mismatch
408 Returns the 408 error code when the user Id doesn’t exist in your database


If your server is secured by a firewall, you may unblock our IP addresses in order to allow the communication between our servers:

Playtem’s server