# WordPress Plugin

> Add the offerwall to your WordPress site without code. The Moonetix Offerwall plugin signs the link for every logged-in user, credits rewards from postbacks to a built-in balance, myCRED, GamiPress, or the WooCommerce wallet, and shows everything in your admin.

Source: https://docs.moonetix.com/wordpress

## How it works

1. A logged-in user opens your Earn page. The plugin builds their signed offerwall link on your server and shows the offerwall.
2. The user completes an offer. Moonetix sends a postback to your site.
3. The plugin checks the postback hash with your postback secret key and credits the reward once, to the place you chose: its own balance, myCRED, GamiPress, or the TeraWallet WooCommerce wallet.
4. If a reward is reversed later, the plugin takes it back. Every postback shows up on the Postbacks tab.

You need no code and no developer. Everything is set up in Settings, Moonetix Offerwall.

## Before you start

- WordPress 6.3 or newer and PHP 7.4 or newer.
- Your site uses HTTPS. The offerwall only loads on https pages.
- An approved offerwall for this website in your Moonetix dashboard. The website you registered must be this site, because the offerwall only loads inside frames on that site and its subdomains.
- Your users log in to your site. Rewards need an account to land in, so logged-out visitors see a login message instead of the offerwall.

## Install the plugin

Download [moonetix-offerwall-1.0.0.zip](https://moonetix.com/downloads/moonetix-offerwall-1.0.0.zip). In your WordPress admin, go to Plugins, Add New Plugin, Upload Plugin, choose the file, click Install Now, then Activate.

The plugin has been submitted to the WordPress.org plugin directory and is waiting for review. Once it is listed, you can also search for **Moonetix Offerwall** under Plugins, Add New Plugin, and updates arrive in your admin.

After activation, a notice with a **Set it up** button takes you to the settings.

## Connect your offerwall

Open Settings, Moonetix Offerwall, and fill in step 1 with the values from your Moonetix dashboard:

| Field | Where to find it | What it does |
| --- | --- | --- |
| App ID | Offerwalls: click **Copy ID** next to your offerwall. Pasting your whole offerwall link works too. | Tells Moonetix which offerwall to show. |
| Link hash salt | Offerwalls, open your offerwall, Integration, **2. Link security**: click Copy next to Link hash salt. | Signs the offerwall link of every user, so nobody can open it as someone else. See [Build the hash](https://docs.moonetix.com/offerwall-link#build-the-hash). |
| Postback secret key | **Postback** in the menu: copy the Postback secret key of this offerwall. | Checks every postback, so only Moonetix can credit points. See [Postbacks](https://docs.moonetix.com/postbacks). |

Saved keys are never shown again. To change one, type the new key over it. To keep the keys out of the database, define them in `wp-config.php` instead, as in the box on the right. The settings page then shows them as set in wp-config.php.

## Add your postback URL

1. On the settings page, click **Copy** next to Your postback URL.
2. In your Moonetix dashboard, open **Postback** in the menu, paste it into the Postback URL field of this offerwall, and save.
3. Open Send a test postback there and send one. The test shows up on the Postbacks tab of the plugin.

The URL already has every macro the plugin needs, so do not change it. If your site has no pretty permalinks, the URL uses `?rest_route=` instead of `/wp-json/`. Both work.

The status box at the top of the settings checks your keys, HTTPS, your points plugin, and whether postbacks arrive. Click **Test the postback URL** to check that your site can be reached. When everything is ready, it says **Everything is set up**. The same check is in Tools, Site Health.

## Show the offerwall

The quickest way: click **Create the Earn page** in the settings. It makes a draft page with the balance, the offerwall, and the reward history. Check it and publish it. The same layout is in the block inserter as the **Earn page** pattern.

Or add the parts one by one, with a block or a shortcode:

| Block | Shortcode | Shows |
| --- | --- | --- |
| Moonetix Offerwall | `[moonetix_offerwall]` | The offerwall for the logged-in user. Optional: `height="900"` in pixels, from 400 to 3000. |
| Moonetix Balance | `[moonetix_balance]` | The balance of the logged-in user, for example in your header or menu. |
| Moonetix Reward History | `[moonetix_history]` | The user’s rewards, newest first, with reversed ones struck through. Optional: `limit="20"`, up to 100. |

Logged-out visitors see your login message with a login link instead. You can change the message under Display.

### Open it from your menu or a button

Turn on **Open the offerwall window from your own menu items and buttons** under Display. Then add the CSS class `moonetix-ow-open`:

- **Classic menus:** Appearance, Menus. Open Screen Options at the top, tick CSS Classes, and enter the class on your Earn menu item.
- **Blocks:** select a Button or a Navigation link block, open Advanced in the sidebar, and enter the class under Additional CSS classes.

A click opens the offerwall in a window over the current page. Point the link to your Earn page: visitors who cannot earn, for example because they are logged out, follow the link as usual.

### Floating Earn button and reward notices

- **Floating Earn button:** a button with the user’s balance in the corner of every page. It opens the offerwall in a window, so users find it from anywhere. Choose its text, side, and color under Display.
- **Where it shows:** on all devices, only on phones and small tablets, or only on computers. Tick the pages where it stays hidden. It is always hidden on pages that already show the offerwall, and with WooCommerce it is hidden on the cart, the checkout, and My account unless you turn that off.
- **Reward notices:** after a reward, the user sees a short notice such as “+250 Coins” on the next page they open. On by default.

The look of the offerwall itself, its colors, your currency name, and its icon, is set in your Moonetix dashboard, in your offerwall’s settings.

## Where rewards go

| Option | How it works |
| --- | --- |
| Built-in balance | The plugin keeps a balance for every user. Set its name, for example Coins, under Rewards. Use the same name as your Moonetix currency. |
| myCRED | Shows up when myCRED is active. Rewards go to the point type you choose, with a log entry for each one. |
| GamiPress | Shows up when GamiPress is active. Rewards go to the points type you choose. GamiPress counts whole points, so use a whole-number currency in your dashboard, for example 1,000 points per dollar. |
| TeraWallet | Shows up when TeraWallet, the WooCommerce wallet plugin, is active. Rewards are added to the user’s wallet as money in your store currency, and users spend them at checkout. See [The WooCommerce wallet](https://docs.moonetix.com/wordpress#wallet). |

The reward is the amount Moonetix sends in `{reward}`, already in your currency. See [Rewards](https://docs.moonetix.com/rewards) for how it is calculated.

### How much your users get

Your users’ share is set in your Moonetix dashboard, under your offerwall, Rewards: the conversion rate turns $1 of your earnings into your currency, and the split to user is the share in percent your users get. The rest is yours. For example, an offer that earns you $0.50, with a conversion rate of 1000 and a 50% split, gives your user 250 points, and you keep $0.25.

The plugin credits exactly what Moonetix sends, so there is nothing to set twice. Under Settings, Rewards, a calculator shows the result for your own numbers before you change them in the dashboard. Full details: [Rewards and currency](https://docs.moonetix.com/rewards).

### The WooCommerce wallet

The wallet holds money, so the plugin converts every reward with your rate: **Points for 1 unit** of your store currency. With 1000 for EUR, a 250-point reward adds 0.25 EUR. Amounts are rounded to the decimals of your store prices, and a reward too small to reach one cent adds nothing.

- To skip the conversion, make your Moonetix currency your store currency: set the currency name to EUR, for example, and the conversion rate to how many euros you pass on for each $1 you earn, then enter 1 as the rate in the plugin.
- A reversal takes back exactly the amount that was added, even if you changed the rate since, and even if the user already spent it, so a wallet can go below zero.
- If TeraWallet refuses a reward, for example because the user’s wallet is locked, the plugin answers 503 and Moonetix sends the postback again later. The settings page shows a notice.

### Paying your users

Moonetix pays you for every completed offer. You decide how your users redeem their points, for example cash, gift cards, or store coupons, and you pay them yourself. With TeraWallet, users spend the wallet at checkout. With myCRED or GamiPress, use their redeem features. With the built-in balance, open the user’s profile, enter a negative number and a reason under Moonetix Offerwall, and save. The user sees the change and the reason in their reward history.

### Reversals

When an advertiser reverses a completion, Moonetix sends a postback with status 2. The plugin takes back exactly the reward it credited for that transaction, even if the user already spent it, so a balance can go below zero. A reversal for a transaction that was never credited is logged and ignored. See [Credits and reversals](https://docs.moonetix.com/credits-and-reversals).

## Who can earn

By default, every logged-in user sees the offerwall. Under **Who can earn**, choose **Only users with these roles** and tick the roles, for example Customer or the role of your membership plugin. Everyone else sees your message instead of the offerwall, with no offerwall link in the page, and no floating button.

- Administrators always see the offerwall, with a short note, so they can test it.
- Rewards for offers a user already completed are still credited, even if their role changed since.
- Developers can decide it per user with the `moonetix_offerwall_can_earn` filter.

## The Postbacks tab

Every postback is listed with the user, the offer, the country, the device, the reward, your earnings, and what the plugin did with it. Search by user, email, transaction ID, or offer. From a user’s profile, See all postbacks shows only theirs.

| Result | Meaning | Answer to Moonetix |
| --- | --- | --- |
| Credited | The reward was added. | 200 |
| Reversed | A credited reward was taken back. | 200 |
| Reversal without a credit, ignored | The transaction was never credited, so nothing was taken. | 200 |
| No such user on this site | No WordPress user has this ID, for example because the account was deleted. | 200 |

A postback that arrives twice is credited once. The repeat gets 200 and changes nothing.

A postback the plugin refuses is not listed and changes nothing: 403 when the hash does not match, 503 when the postback secret key is not set or the plugin chosen for rewards is not active. Moonetix sends it again later, so once you fix the setting, the reward still arrives.

## Page caching

Pages with a user’s offerwall, balance, history, floating button, or notices tell browsers and page cache plugins not to store them, so one user never sees another user’s link or balance. This works with every cache plugin that respects `DONOTCACHEPAGE`. If your CDN caches whole pages, bypass the cache for logged-in users.

## For developers

| Hook | Type | Use |
| --- | --- | --- |
| `moonetix_offerwall_user_id` | Filter | Change the user ID sent to Moonetix. Default: the WordPress user ID. Arguments: the ID as a string, the WordPress user ID. |
| `moonetix_offerwall_postback_user` | Filter | Map the user ID in a postback back to a WordPress user ID. Use it together with the filter above. Arguments: the WordPress user ID or 0, the user ID from Moonetix. |
| `moonetix_offerwall_can_earn` | Filter | Whether a logged-in user sees the offerwall and the floating button. Arguments: the result of the Who can earn setting, the WordPress user ID. |
| `moonetix_offerwall_show_floating` | Filter | Whether the floating button shows on the current page. Argument: the result of the visibility settings. |
| `moonetix_offerwall_postback` | Action | Runs after every postback that passed the hash check. Arguments: the result, the WordPress user ID, the signed values. |
| `moonetix_offerwall_balance_changed` | Action | Runs when the built-in balance changes. Arguments: the WordPress user ID, the change, the transaction ID. |

If you change the user ID, keep it stable and never use an email address. See [Link format](https://docs.moonetix.com/offerwall-link#link-format).

## Troubleshooting

| Problem | Fix |
| --- | --- |
| The offerwall shows a login message | You are logged out. Log in and open the page again. |
| Users see “available to members only” | Their role is not ticked under Who can earn. Tick it, or choose All logged-in users. |
| The menu item opens a new page instead of the window | Turn on menu links under Display, check that the class is exactly `moonetix-ow-open`, and clear your page cache. |
| Only administrators see “add your App ID” | Enter the App ID under Settings, Moonetix Offerwall. |
| Link not valid | The link hash salt does not match. Copy it again from Integration, Link security. |
| The offerwall frame stays empty or refuses to load | The website registered for your offerwall is not this site, or the page is not on https. Check the website in your offerwall’s settings. |
| VPN detected | Offers are not shown over VPNs or proxies. Test from a normal home or mobile connection. See [Testing](https://docs.moonetix.com/testing#vpn). |
| Test postbacks do not show up on the Postbacks tab | Click Test the postback URL in the status box. If it says the URL is blocked, a security plugin, a firewall, or your host blocks the WordPress REST API. Allow the `moonetix-offerwall` route. |
| Postbacks arrive but nothing is credited | Check the status box. A red line for the postback secret key or the points plugin tells you what to fix. The settings page also shows a warning after a failed postback. |

## Privacy

The reward history of a user is part of the WordPress personal data export and erase tools in Tools. The plugin also adds a suggested paragraph to Settings, Privacy, for your own privacy policy. The plugin sends no data to Moonetix from your server. It only answers the postbacks Moonetix sends.

Under Display, you can turn on an optional “Rewards by Moonetix” link under the offerwall. Paste your referral link from the Referrals page of your dashboard, or only its code. Publishers who sign up within 30 days of clicking it count as your referrals. It is off by default.

## Remove the plugin

Deactivating or deleting the plugin keeps your settings, reward history, and balances, in case you install it again. To remove everything when you delete it, tick Delete all plugin data under Data first.

## Quick reference

### Shortcodes

```
[moonetix_offerwall]
[moonetix_offerwall height="900"]
[moonetix_balance]
[moonetix_history limit="20"]
```

### Postback URL

```
https://yoursite.com/wp-json/moonetix-offerwall/v1/postback?user_id={user_id}&transaction_id={transaction_id}&reward={reward}&status={status}&hash={hash}&offer_name={offer_name}&offer_id={offer_id}&payout={payout}&country={country}&device={device}
```

Copy yours from Settings, Moonetix Offerwall. It already has your site address in it.

### wp-config.php

```
define( 'MOONETIX_OFFERWALL_LINK_SALT', '...' );
define( 'MOONETIX_OFFERWALL_POSTBACK_KEY', '...' );
```

Need a hand? Use the live chat in your dashboard, or write to [partners@moonetix.com](mailto:partners@moonetix.com).