Publisher Integration Guide

Overview

This guide provides a comprehensive walkthrough for integrating the Torox wall and API into your application, enabling new monetization and retention channels through our Loyalty Platform.

Which integration is right for you?

There are two ways to connect. Both show the same offers and reward users the same way — they differ in how much you build yourself and how the wall looks inside your product.

The journey, end to end

Estimated time per stage

Glossary

A few terms used throughout this guide:

Create your source

As the first stage, register your app in the Torox dashboard. The process typically takes 15–30 minutes and will provide the two credentials required for integration: your source_id and token.

1. Open App Placements
   Go to torox.io and sign in, then open App Placements and click Add App.
2. Name your source and add its URL
   Enter a recognizable source name and your app or website URL, then click Next.
3. Choose your monetization tool
   Select Offerwall or API depending on how you plan to integrate (see which integration is right for you). If you want a standalone integration that allows you to pull specific offers from us, you should choose the API option. SDK options shown here are deprecated — don't choose them. Click Next.
4. Set your currency and exchange rate
   Enter your currency name and exchange rate. The exchange rate is the number of currency units a user sees for every $1 of value — already adjusted for the share you pay out. Enter the final amount you want users to see, not the raw revenue. See the example below for help. Click Next.
   Worked example Suppose your currency is configured so that $1 = 100 units, and you want users to receive 70% of the revenue generated from completed offers. Since $1 is worth 100 units, users should receive 70% of that value: 100 × 0.7 = 70. Enter 70 as the payout multiplier. As a result, users earn 70 units for every $1 of revenue generated, while you retain the remaining 30%. The dashboard calculator shows live examples as you type.
   
5. Customize the design (Offerwall only)
   If you chose Offerwall, you can customize the look so it matches your app. Your CSM can also remove the Torox logo, add a header, or set a branded currency icon. Click Next.
6. Configure postback settings
   Leave the S2S and reversal checkboxes unchecked (these are defaults Torox doesn't recommend enabling). If you enable the Minimal Parameter Postback option, Torox will send postbacks containing only the required parameters list. You can opt out of postback email notifications and set how many times Torox retries a failed postback. Then enter your postback URL — see the postback section for how to build it.
7. Finish
   Click Finish. Your placement is created. You can re-open it any time to edit details, choose an Offerwall design template, open Wall Customization, set up promotions (do this with your CSM), and run the postback tester.
8. Test Postback
   Click Postback tester. When using the tester, the Offer ID field must contain a valid offer ID from the Torox inventory. You can obtain an offer ID from the Offer Gallery by selecting any active offer and copying its ID. The Postback Tester is limited to 20 attempts per day. All Postback Tester requests are sent with conversion_id=100.

   Postback sent successfully:

   

   Postback send failed:

   

Before you start (developers)

You will need the two credentials from your source setup and the API URL below.

Option A — Offerwall (iFrame)

The Offerwall uses a server-authenticated flow. Your server asks Torox for a one-time wall link tied to a specific user, and you display that link in an iframe. The link carries only a random token, so no user data is exposed in the URL.

Why this version

• Fast load — around 1-second load times.
• Secure — the URL exposes only a random token; you're the only party that can make a token for a user. Malicious users/actors would not be able to see and play with other players' wall.
• Data signals — enhanced data signals for deeper user insights and future personalization.
• Cleaner traffic — no "ghost" users, and other actors can't view or tamper with a user's wall.
• Better UX — higher-quality creatives, smart filtering between games and tasks, and clearer offer progress.

Step 1 — Create a session (server-side)

From your server, request a wall URL for the user:

POST https://api.wall.torox.io/partner/session
     ?placement_id=<YOUR_PLACEMENT_ID>&token=<YOUR_APP_TOKEN>

{
  "player": {
    "uid": "<YOUR_USER_ID>"
  }
}

Step 2 — Read the response

{
  "ok": true,
  "wall_url": "https://wall.torox.io/<PLAYER_TOKEN>"
}

Option B — API

The API solution gives you the ability to integrate the offers natively inside your product. All requests are HTTPS GET and return JSON. Every request needs your source_id and token.

The typical flow

1. Fetch campaigns for your placement and render them as a list.
2. When a user taps one, fetch that campaign's details for their location.
3. When they're ready to start, generate a click URL and redirect them to it.
4. Optionally, show users their own reward history.

1 · Get Campaigns — required

All available campaigns for your placement. goals=all adds the reward events on multi-reward campaigns. No user ID needed.

https://api.wall.torox.io/partner/campaigns?source_id={YOUR_SOURCE_ID}&
token={YOUR_TOKEN}&goals=all

The list can also be filtered and sorted. These are optional, combine with AND logic, accept comma-separated values, and may appear only once in the URL.

https://api.wall.torox.io/partner/campaigns?source_id={SOURCE_ID}&token={TOKEN}&
goals=all&os=android&geo=US&min_payout=1&sort=payout-DESC

[
  {
    "offerId": 19661864,
    "name": "Legend of Mushroom",
    "description": "Play the game and complete all events.",
    "callToAction": "Play the game and complete all events.",
    "disclaimer": null,
    "os": "ios",
    "geos": "US",
    "packageId": "id6475333787",
    "landingUrl": "https://apps.apple.com/us/app/id6475333787",
    "image": "https://static.offertoro.com/uploads/offers_image/d91dad7c....jpg",
    "coverImage": "https://static.offertoro.com/uploads/offers_image/84db2701....jpg",
    "payout": 144.01,
    "amount": 864060,
    "payoutType": "CPI",
    "hasAbsolutePayout": 0,
    "rating": 501519,
    "completions": 670,
    "userRatingAvg": 0,
    "userRatingCount": 0,
    "isMr": 1,
    "verticalNames": "Gaming - RPG",
    "verticalIds": "30",
    "pinned": false,
    "promoted": false,
    "events": [
      {
        "eventId": 1,
        "orderId": 1,
        "eventName": "Open the game",
        "callToAction": "",
        "payout": 0.01,
        "amount": 60,
        "timeframeMin": 0,
        "timeframeMax": 0,
        "isRecurring": 0,
        "recurringFrequency": null,
        "offerId": 19661864
      },
      ...
    ]
  },
  ...
]

2 · Get Campaign Details — required

One campaign, resolved for a specific user and location. Use it for a campaign info page or to show the country-specific payout.

https://api.wall.torox.io/partner/user/campaign?source_id={SOURCE_ID}&token={TOKEN}&
uid={USER_ID}&geo={GEO}&campaign_id={CAMPAIGN_ID}

{
  "offerId": 19661864,
  "name": "Legend of Mushroom",
  "os": "ios",
  "isMr": 1,
  "description": "Play the game and complete all events.",
  "callToAction": "Play the game and complete all events.",
  "disclaimer": null,
  "image": "https://static.offertoro.com/uploads/offers_image/d91dad7c....jpg",
  "coverImage": "https://static.offertoro.com/uploads/offers_image/84db2701....jpg",
  "completions": 670,
  "verticalNames": "Gaming - RPG",
  "verticalIds": "30",
  "payout": 144.01,
  "amount": 864060,
  "events": [
    {
      "eventId": 1,
      "orderId": 1,
      "eventName": "Open the game",
      "callToAction": "",
      "payout": 0.01,
      "amount": 60,
      "timeframeMin": 0,
      "timeframeMax": 0,
      "isRecurring": 0,
      "recurringFrequency": null,
      "offerId": 19661864
    }
  ]
}

3 · Get Click URL — required

The tracking URL to open for the user. Call it the moment they start the campaign — that click is what attributes the reward.

https://api.wall.torox.io/partner/user/click?source_id={SOURCE_ID}&token={TOKEN}&
uid={USER_ID}&geo={GEO}&campaign_id={CAMPAIGN_ID}

{
  "ok": true,
  "clickUrl": "https://torox.io/click_track/track/19661864/0/0/16444
               ?player_uid=user-001&xvs=<SIGNATURE>"
}

{
  "ok": false,
  "error": "..."
}

4 · Get User Activity — optional

The campaigns a user has engaged with and how far they have got. Useful for "My Rewards," "Pending Credits," or "Completed Offers" screens.

https://api.wall.torox.io/partner/user/activity?source_id={SOURCE_ID}&token={TOKEN}&
uid={USER_ID}

[
  {
    "offerId": 19661864,
    "name": "Legend of Mushroom",
    "os": "ios",
    "isMr": 1,
    "image": "...",
    "coverImage": "...",
    "description": "...",
    "packageId": "id6475333787",
    "landingUrl": "https://apps.apple.com/us/app/id6475333787",
    "clickSt": 1758500000,
    "tasksCount": 16,
    "completedTasksCount": 3,
    "completionDays": 30,
    "totalAmount": 960,
    "totalPayout": 0.16,
    "status": "InProgress",
    "events": [
      {
        "eventId": 1,
        "eventName": "Open the game",
        "orderId": 1,
        "payout": 0.01,
        "amount": 60,
        "completionTime": 1758500123,
        "completionCount": 1,
        "status": "Rewarded",
        "mcrStatus": 1,
        "fromEventId": null
      }
    ]
  }
]

5 · Testing Environment

We recommend using the staging environment to test your integration. Add the word stage after wall in the base URL:

https://api.wall.stage.torox.io/partner/campaigns?source_id={YOUR_SOURCE_ID}&
token={YOUR_TOKEN}

Postback — how users get rewarded

When a user completes an action and it's verified, Torox sends a server-to-server message to your postback URL. Your endpoint reads it and credits the user. Without a working postback, users complete offers but never receive rewards — so this is the most important part to get right. The following is a list of all the parameters which are passed to you for every postback:

(*) Those parameters are included in the Minimal Parameter Postback and will always be sent when this option is enabled.

If you would like to pass those additional subids in your iframe based OfferWall, they can be passed in the following way:

https://torox.io/ifr/show/YOUR_PUB_ID/UserID/YOUR_APP_ID/0/0/subid1/subid2/subid3

1 · Set your postback URL

You enter your postback URL during app placement setup (or later, by editing the source). It's an endpoint on your server that Torox calls with reward details as query parameters. A valid URL looks like:

http://www.Your-Site.com/pb/?OID=123&user_id=JohnSmith&Amount=10...

2 · Respond correctly

Your endpoint should accept the request, credit the user, and return a success response so Torox knows the reward was delivered.
We expect a "1" (without quotes) as a response to a successfully received postback and a "0" (without quotes) to indicate that the postback was received incorrectly. If we have not received a "1" as a reply, we will try to send the postback up to 5 times, based on the app settings. After 5 failed tries, we will send you an email with the data of the conversion so you can process it manually.

3 · Postback IPs

All of our postbacks shall be sent from the following Torox IP: 44.212.211.226. Please white-list this IP as this is the ONLY IP we'll be sending postbacks from.

4 · Reversal Postbacks

By default, all reversal postbacks are disabled. You can choose to enable it by going to the settings page on one of your app placements.
All reversal postbacks will have a negative amount or payout. Each reversal is delivered as a new postback with a different ID, rather than a modification of the original postback.

Example: Standard Postback

https://api.Your-Site.com/tasks/torox/pb?userId=5010a38c-7f28-[…].3867&reward=19315.0000&hash=9cafe5efe43e69919811d1353229e3e8

Example: Reversal Postback:

https://api.Your-Site.com/tasks/torox/pb?userId=5010a38c-7f28-[…]=-24.3867&reward=-19315&hash=9cafe5efe43e69919811d1353229e3e8

Set up or update your billing details

To receive payments from Torox, add your billing and bank details in the dashboard. This is handled through Tipalti, our payments provider, and only needs to be done once.

1. Open Billing
   In the Torox dashboard at torox.io, open Billing from the left-hand menu, then click Payment details on the Payment Details panel.
2. Enter your address
   Click Edit and fill in your details. Click Next.
3. Add your payment method
   Enter your bank details — name on account, bank name, routing code, and account number — then click Next to finish.

App promos

The App promo feature lets you increase the app currency presented to your users! This modification can be done for a limited, known-ahead time and lets you choose targeted countries as well. Applying these changes over API offers can also be modified by you.

To access App Promos, select the App in the Overview section and press Edit:

Go to the App Promos section:

Explanation of fields — App Promos:

• Activate Increased Currency Promo: Check this if you wish to run the Promo at the specified date, time and duration. During the duration of the Promo, the currency amount given to your users will be increased.
• % Increase: The percentage of currency increase for the duration. The minimum increase is 0%, with 150% as the maximum. If you need to set a higher percentage, please contact your assigned Account Manager.
• No. of Hours: Specifies the duration of the Promo in hours (HH:mm format). For example, if you intend to run the Promo for 6 hours you can simply write 6. If you need to run the promo for 24 hours and 30 minutes, simply write 24:30.
• Start Date/Time: Specifies the starting date and time of the Promo. Click anywhere in the textbox to select the date or time. Date and Time should be in EST timezone.
• Allow in API/SDK Offers: Select this option to apply the Promo to API offers.
• Apply To Specific Countries Only? Select this option to apply the Promo to specific countries only. Once selected, a textbox will appear for you to select the countries. You can add, or remove, multiple countries as you like.

After filling up all the information, click Save. Clicking Clear will disable and clear all fields in the current session. Click Save to persist the data.

Offer notification service

In order to be notified about offer changes you should subscribe to the notification service. Torox will send you a notification by email for the next events:

• Offer has been paused
• Offer has been reactivated
• Offer payout has been changed
• Offer cap has been changed

To subscribe for an offer notification enter the Offers Gallery and choose the app placement. After choosing the app placement a list of all available offers will be presented. Tick the Notify box next to the offer you would like to subscribe and get notifications for, or untick the box in order to remove the subscription.

Another possibility available is to tick the Enable Notification tick box via the offer view.

Notification Email Address

Notifications will be sent to the email address you are logging into the Torox system with by default. Changing the notification email address can be done under Account Info. Click on My Account then on Account Info. On the Edit Account Information section enter the desired mail address for notification subscription in the Notifications Email Address field.