Reversals

https://your-site.com/reversal?key=YOUR_SECRET&user_id={user_id}&tx={transaction_id}&event={event_id}&coins={coins}&points={points}&payout={payout}&reason={reason}&status={status}

// ONE handler for both channels. Save the SAME base URL in BOTH Settings
// fields; the payload's {status} says which channel is calling:
//   Postback URL : https://your-site.com/postback?key=…&user_id={user_id}&tx={transaction_id}&points={points}&payout={payout}&offer_id={offer_id}&status={status}&event={event_id}
//   Reversal URL : https://your-site.com/postback?key=…&user_id={user_id}&tx={transaction_id}&points={points}&payout={payout}&offer_id={offer_id}&status={status}&event={event_id}&reason={reason}
app.get("/postback", async (req, res) => {
  if (req.query.key !== process.env.LOOTHQ_POSTBACK_SECRET) {
    return res.status(403).send("forbidden");
  }
  const { user_id, tx, reason, status, points, payout } = req.query;
  const event = req.query.event || "";

  // A macro we don't substitute on a given channel arrives PRESENT AND EMPTY
  // ("", with the param still there), never missing. So "points ?? payout" and
  // "points != null" both pick the empty string and quietly credit 0.
  const has = (v) => v !== undefined && v !== "";

  // Branch on {status}: it is "approved" on every primary-URL delivery and
  // "reversed" on every reversal-URL delivery, with no third value. Do NOT
  // branch on whether `event` is set: it is also set on approvals (the
  // goal id there). And what does NOT work at all, and what a first
  // integration usually assumes, is waiting for a negative payout on the
  // primary URL. It never arrives.
  if (status === "reversed") {
    // ---- reversal ----
    // Dedupe on {event_id}: on THIS channel it is a fresh UUID per delivery.
    // NOT on tx: on a reversal, tx is the ORIGINAL conversion's id, so it
    // repeats for every reversal of that conversion and every retry of this
    // one.
    if (await db.Reversals.findOne({ event })) {
      return res.status(200).send("already reversed");
    }
    await db.Reversals.create({ event, tx, user: user_id, reason: reason || "unknown" });

    // {points}/{payout} carry the FULL value the approval postback told you
    // to credit: {points} in your currency on wall conversions, 0 on Offers
    // API conversions (no coin layer, so take {payout} in USD instead).
    // Take back exactly that amount. Your own wallet is settled by us
    // either way (see "When you earn").
    const undo = Number(points) > 0
      ? Number(points)
      : usdToYourCurrency(Number(payout));
    if (undo > 0) await debitUser(user_id, undo);
    return res.status(200).send("ok");
  }

  // ---- approval: the only thing the primary URL ever sends ----
  // WHAT TO CREDIT depends on the placement, and the payload tells you which:
  //   hosted wall / prize → {points} is ALREADY your currency. Credit as-is.
  //   Offers API          → no coin step, so {points} is empty and {payout}
  //                         is USD. Convert it yourself.
  const amount = has(points)
    ? Number(points)
    : usdToYourCurrency(Number(payout));

  // IDEMPOTENCY: the (tx, event) pair, unique per credit on every channel.
  // Wall and Offers API conversions alike: tx is the CLICK id and repeats
  // for every goal of a multi-goal offer; event (the goal id) is what
  // separates them, so keying on tx alone would drop every goal after the
  // first. Prize redemptions: tx is unique by itself and event is "", so
  // the pair degrades to tx.
  if (await db.Conversions.findOne({ tx, event })) {
    return res.status(200).send("already processed");
  }
  await db.Conversions.create({ tx, event, user: user_id, credited: amount, status });
  await creditUser(user_id, amount);
  return res.status(200).send("ok");
});