Skip to content
LaunchOfferwall

Developers

Offerwall integration reference

Everything a publisher needs to show a network's offerwall and credit users: the wall URL, the iframe embed, the JSON offers API and the server postback. Every network on LaunchOfferwall uses the same parameters on its own domain.

Start free trialHow postbacks work

Before you start

In these examples, offers.yournetwork.com stands for your network's host: either its launchofferwall.com subdomain or a custom domain the network has connected. APP_ID is the app ID shown in the publisher portal once the network approves the app, and USER_ID is your own identifier for the signed-in user, up to 128 characters. Use a stable, non-guessable ID, never an email address.

Each approved app in the portal also shows its postback secret. Keep it on your server only.

Integration options

There is no SDK to install. Choose one of three web integrations, or combine them.

  • Hosted wall: link or redirect users to the wall URL, or open it in a mobile web view.
  • iframe: embed the same URL in your page.
  • JSON API: fetch eligible offers and render them in your own UI.

1 and 2. Hosted wall and iframe

Wall URL and embed snippet

Required: app and user. Optional: category, to open the wall on one category tab. The wall shows only offers available in the user's country and on their device, highest payout first, and allows framing from any site; offer clicks open in a new tab. Responses: 400 when app or user is missing, 404 when the app is not active.

index.htmlhtml
1<!-- Hosted wall: link, redirect or open in a web view -->2https://offers.yournetwork.com/wall?app=APP_ID&user=USER_ID3https://offers.yournetwork.com/wall?app=APP_ID&user=USER_ID&category=Games4 5<!-- iframe embed -->6<iframe7  src="https://offers.yournetwork.com/wall?app=APP_ID&user=USER_ID"8  style="width:100%;height:100vh;border:0"9></iframe>

3. JSON API

GET /wall/api/offers

Same app and user parameters. Cross-origin requests are allowed. reward values are integers in the app's currency, already converted from the publisher's share. Send users to clickUrl when they choose an offer. Errors: 400 {"error":"missing_app_or_user"}, 404 {"error":"not_available"}.

response.jsonjson
1// GET https://offers.yournetwork.com/wall/api/offers?app=APP_ID&user=USER_ID2{3  "currency": "Coins",4  "offers": [5    {6      "id": "off_8f2k1x",7      "title": "Reach level 10 in Example Quest",8      "description": "Install and play the new fantasy RPG.",9      "instructions": "New players only. Reach level 10 within 14 days.",10      "iconUrl": "https://cdn.example.com/icon.png",11      "categories": ["Games"],12      "reward": 1400,13      "goals": [14        { "id": "gol_1", "name": "Install", "reward": 200 },15        { "id": "gol_2", "name": "Level 10", "reward": 1200 }16      ],17      "clickUrl": "https://offers.yournetwork.com/c/off_8f2k1x?app=APP_ID&user=USER_ID"18    }19  ]20}

Click links

Offer clicks go through /c/OFFER_ID?app=APP_ID&user=USER_ID on the network's host. We issue a signed click ID and answer with a 302 redirect to the advertiser. Always use the link from the wall or the clickUrl from the JSON API rather than building your own.

Other responses: 400 when app or user is missing, 404 when the app is not active, 410 when the offer is no longer available, and 403 with a short explanation page when the network's fraud rules block the user's country or connection.

Server postbacks

Set a postback URL for each app in the publisher portal. When a conversion is approved we call it with an HTTP GET, replacing macros with the conversion's values. Macros can be written as {user_id} or [USER_ID]; values are URL-encoded.

Respond with any 2xx status to acknowledge. Anything else, or no response within 10 seconds, is retried: after 1 minute, then 2, 4, 8 and so on, capped at once an hour, until 72 hours after the conversion. Requests carry the user agent LaunchOfferwall-Postback/1.0.

If a conversion is later reversed by the partner or the network, we call the same URL again with the same transaction_id, status=rejected, and negative reward and payout. Deduct the reward from the user.

Postback macros

Aliases on the same row return the same value.

FeatureValue
{user_id}Your USER_ID from the wall URL
{transaction_id}Unique conversion ID; the same on a reversal
{reward} / {reward_value}Integer amount of your currency; negative on reversal
{payout} / {payout_value}Your earnings in USD, e.g. 1.4; negative on reversal
{status}completed or rejected
{offer_id}Offer ID
{offer_name}Offer title
{event_id}Goal ID for multi-event offers, otherwise empty
{event_name}Goal name for multi-event offers, otherwise empty
{user_ip} / {ip}User IP if the partner reported it, otherwise empty
{country} / {country_code}Country code if reported, otherwise empty
{hash}sha256(user_id + offer_id + transaction_id + secret), hex

Verify

Check the hash before crediting

Concatenate user_id, offer_id and transaction_id exactly as received, append your app's postback secret, and compare the SHA-256 hex digest with {hash}. Your postback URL must include {offer_id} (or keep the offer ID another way) so you can recompute it. Store transaction_id and ignore repeats; reversals reuse it with status=rejected. In PHP the check is hash_equals(hash('sha256', $user . $offer . $txn . $secret), $hash).

server.jsjavascript
1// Postback URL template set in the portal:2// https://api.yourapp.com/offerwall/postback?user={user_id}&amount={reward}&txn={transaction_id}&offer={offer_id}&status={status}&hash={hash}3 4import { createHash, timingSafeEqual } from "node:crypto";5 6export function verifyPostback(query, secret) {7  const { user, offer, txn, hash } = query;8  const expected = createHash("sha256")9    .update(String(user) + offer + txn + secret)10    .digest("hex");11  const a = Buffer.from(expected);12  const b = Buffer.from(String(hash ?? ""));13  return a.length === b.length && timingSafeEqual(a, b);14}15 16// Then: if status === "completed", credit `amount` once per txn;17// if status === "rejected", deduct it.

For networks: incoming postbacks

Partner connections each get their own URL in the console, of the form /pb/p/CONNECTION_ID?key=KEY&click_id=...&txn=..., with the partner's macros already filled in. impact.com needs none, because conversions are pulled.

For direct advertisers on manual offers, use the network-wide manual postback URL from Settings. Put {click_id} in the offer's tracking URL where the advertiser expects our click ID; if you do not, we append click_id to the URL. Both endpoints accept GET, or POST with JSON or form bodies, and answer OK once the postback is stored and queued.

  • key: your network's manual postback key (required)
  • click_id (or clickid): the click ID we passed to the advertiser (required)
  • txn (or transaction_id): the advertiser's unique conversion ID (required)
  • payout: amount in USD; defaults to the goal's or offer's payout
  • status: approved by default; reversed, rejected, chargeback, -1 or 0 reverse the conversion
  • goal (or event): the goal's external ID, for multi-event offers
  • ip and country: the user's IP and country, if known, for fraud checks

Advertiser click URL macros

When we redirect a click, these macros in an offer's tracking URL are replaced: {click_id}, {user_id}, {app_id}, {offer_id}, {publisher_id}, {country} and {device} (android, ios or desktop).

Ready to build on your own network?

Start free trialContact us