Please wait....
Back
Documentation
Last update: 29th October 2020
Web Offerwall
Offers API
Setting up Postback
1. Introduction

Welcome to MediumPath's documentation page, an account is required in order to use any of our tools.

2. Creating an app

An application is required to use any of our tools. Once you have created an app you will have an API KEY and a SECRET KEY that will be used for integration purpose (But before it, you will have to wait until your app get approved).

You can create an app easily by following steps below:

1. Login to your MediumPath Account.

2. Navigate to App >> Submit new app.

3. Choose type of app that you are intrested in.

3. Complete the form's fields and press Submit button.

4. You can check your submitted app by navigate to Apps >> My apps

5. Once your app got Approved, you will be able to see the API Key and Secret Key of your app that will be used for integration purpose in the My apps page.

3. Web Offerwall API

Iframe example

Offerwall parameters

[api_key]

*Required. You must replace this parameter by your app's API Key. If you don't have it yet, create an app with type "Web Offerwall" and wait until it's approved to get it.

[user_id]

*Required. You must replace this parameter by user id value of your app.

[subid]

Optional. The value of this parameter will be returned in the postback as subid parameter.

[subid2]

Optional. The value of this parameter will be returned in the postback as subid2 parameter.

[subid3]

Optional. The value of this parameter will be returned in the postback as subid3 parameter.

4. Offers API

JSON

To fetch the offers, make a call to

Change [API_KEY] by your app's API Key to fetch the offers. If you don't have it yet, create an app with type "Offers API" and wait until it's approved to get it.

Note: You should use API Key of "Offers API" app or it will not work.

Possible HTTP Response code

200

Everything is working correctly.

202

The API key is not valid.

203

The API Key is not set.

204

Everything is ok but no offers shown. This indicate some mistake in your filtering value or just no offers for your filtering requirement.

Tracking link parameters

[unique_user]

*Required. You must replace this parameter by user id value of your app.

[transaction]

*Required. The value of this parameter will be returned in the postback as subid parameter.

[subid2]

Optional. The value of this parameter will be returned in the postback as subid2 parameter.

[subid3]

Optional. The value of this parameter will be returned in the postback as subid3 parameter.

[iOS_Advertising_Identifier]

Optional. This is Identifier for Advertisers (IDFA) that created by Apple for advertising purpose and this will be available in iOS devices. If you put the offers in an iOS app then you can get this IDFA value and you should send the user's IDFA to us by replacing this parameter by the user's IDFA.

[Android_Advertising_Identifier]

Optional. This is Google Advertising ID (AAID) that created by Google for advertising purpose and this will be available in Android devices. If you put the offers in an Android app then you can get this AAID value and you should send the user's AAID to us by replacing this parameter by the user's AAID.

Definition of each value in each offer

id

Id of the offer

title

Title of the offer

conversion_goal

Requirement to complete the offer

payout_usd

Earning that will be credited to your account each time the offer completed

tracking_url

URL that will be used in order to access the offer

icon_optimized

Offers's creative that you can use for promotion purpose, and the file size is small (Optimized)

icon_hd

Offers's creative that you can use for promotion purpose, and the file is High Quality

target_countries

Countries that allowed to acces the offer

categories

The offer's categories for filtering and sorting purpose

completion_limit

The offer's completion limit. Example: "3, Daily" mean Max. 3 conversions per user daily. Example 2: "1, Lifetime" mean Max 1 conversion per user.

start_date

The date where the offer started

end_date

The date where the offer will be expired

Filtering (JSON)

categories

You can filter the offers by category, if you wanna show offer from multiple categories just seperate them by comma ','. Example:

devices

You can filter the offers by device (Available devices are: Desktop, Phone(android), Tablet(android), Android, iOS, iPad, iPhone, iPod), if you wanna show offer from multiple devices just seperate them by comma ','. Example:

countries

You can filter the offers by country in ISO 3166-2 format (country code with length of 2 characters), if you wanna show offer from multiple countries just seperate them by comma ','. Example:

5. Setting up Postback

Whenever a user makes a conversion, we will send you a URL request called 'Server to Server Postback' with some information. Using this information, you can reward the user who performed the action accordingly. The postback will be sent to the postback URL you have defined in your MediumPath's App/Website. in Default we sent all datas in POST method but if you need GET method, you can simply include "pb_method=GET" into your postback URL, example:

https://www.example.com/pb.php?pb_method=GET&var1=var1_value&var2=var2_value

We recommend to you save the transId called in database, if the transId ever called before then you can deny the request cause possibly it's multiple call for same conversion.

Postback Parameters (POST method -- Default)

user_id This is the app/website's user that complete the offer.
transId Unique identification code of the transaction made by your user on Mediumpath.
reward The amount of your virtual currency to be credited to your user.
currency The name of your virtual currency.
signature MD5 hash that can be used to verify that the call has been made from our servers. The value is MD5 HASH of user_id + transId + reward + Secret Key.
status Determines whether to add or subtract the amount of the reward. "SUCCESS" is when the virtual currency should be added to the user and "ERROR" when it should be subtracted. This may be because the advertiser has canceled the user's transaction, either because he/she committed fraud or because it has been a mistake entering the data needed to complete the campaign.
userIp The user's IP address who completed the action.
campaign_name Name of the completed offer.
campaign_id ID of the completed offer.
country Country (ISO-3166-1: Alpha-2 country code format) from the lead comes.
subid Custom tracking link parameter.
subid2 Custom tracking link parameter.
subid3 Custom tracking link parameter.

Postback Parameters (GET method)

{user_id} This is the app/website's user that complete the offer.
{transId} Unique identification code of the transaction made by your user on Mediumpath.
{reward} The amount of your virtual currency to be credited to your user.
{currency} The name of your virtual currency.
{signature} MD5 hash that can be used to verify that the call has been made from our servers. The value is MD5 HASH of user_id + transId + reward + Secret Key.
{status} Determines whether to add or subtract the amount of the reward. "SUCCESS" is when the virtual currency should be added to the user and "ERROR" when it should be subtracted. This may be because the advertiser has canceled the user's transaction, either because he/she committed fraud or because it has been a mistake entering the data needed to complete the campaign.
{userIp} The user's IP address who completed the action.
{campaign_name} Name of the completed offer.
{campaign_id} ID of the completed offer.
{country} Country (ISO-3166-1: Alpha-2 country code format) from the lead comes.
{subid} Custom tracking link parameter.
{subid2} Custom tracking link parameter.
{subid3} Custom tracking link parameter.

We have examples for postback below (intended for understanding only, we recommend you add some additional code for security reason)

PHP example

IP addresses that need to be whitelisted

67.205.42.19

2607:F298:5:6004::E87:CBE4

67.205.41.134

173.236.129.24

2018-2022 © MediumPath