What is an offer callback for?

To receive only Offer callbacks, or to set a separate endpoint specifically for Offers, you can use the Offer Callback field instead of the standard Reward Callback field.

How to set up offer callbacks

To set up the offer callbacks, visit the Publisher Dashboard -> Apps -> Your App -> Integration -> Offer Reward Callback:

IMPORTANT: You can enable the stateful offer callbacks, which have the following effects:

• Offer callbacks for all states will be sent now (Before only COMPLETED and RECONCILED would be sent)
  • Please configure the Offer Reward Callback and the Offer Reconciliation Callback separately.
• The transaction ID for each state change will be the same
• The TYPE parameter will return the type COMPLETE for COMPLETED or PENDING states or RECONCILIATION for RECONCILED state.
  • It is recommended not to use TYPE for offers.
• Reconciliation callbacks are no longer negative

If you don't enable stateful callbacks, the transaction IDs for reconciled callbacks will have an or prefix instead of just o. You can reference back to the initial callback by looking up the ref parameter.

To configure a new URL, press the cog wheel to open the callback URL configurator:

Multiple fields have to be filled out:

• Callback URL Host: Enter the callback endpoint URL you have set up.
• Protocol: In most cases, you want to leave it as is.
• Callback Parameter: Here you can add all the parameters you need to process the callbacks correctly. We highly recommend that you have the following parameters in there: UID, TX, VAL, and RAW.
  • For offers, we also recommend to add the following parameters: offer_id, task_id and offer_state. offer_state will return the state of an offer: PENDING, RECONCILED, COMPLETED. Learn more about the offer states here.
• Custom Parameter: In case you want to attach a parameter yourself, you can add it here. However, it does only support static parameters.
• Example URL: This shows you an example callback URL that you would receive. Keep in mind the hash in the example is not a valid one!

Here is an example of how a callback URL could be configured:

Press the Save button and then the Save Changes button in the top right.

Callback batches

In rare cases, event attribution issues may occur, leading us to send batches of callbacks. Your system might mistakenly flag this as fraud.

🚧

If you encounter any discrepancies, please contact our team for clarification.

Offer states

Each offer callback will have a different state. The following states are available:

Completed

The COMPLETED callback will be sent when an offer task is completed. A COMPLETED callback can also be sent if a user completes an install task, which usually gives a $0 reward.

Pending

A PENDING callback will be sent when an offer is completed, but the reward is still pending. This can be the case when delayed crediting (a security feature) is enabled. After a PENDING callback was sent, a COMPLETED or RECONCILED can follow.

Reconciled

A RECONCILED callback is sent when an offer reward is adjusted, either due to a reconciliation or a rejected event completion.

If a reward is deducted (e.g., due to fraud), the deducted amount will be included in the VAL and RAW fields.

While most reconciliations (around 95%) occur within the first 30 days after completion, they can technically happen at any time.

A RECONCILED callback can occur in the following cases:

• After a PENDING or COMPLETED callback: when a previously granted reward needs to be deducted or adjusted due to fraud.
• Without a prior PENDING or COMPLETED callback: when the event is reconciled directly, for example, due to a timeout or rejection.

The reconciliation amount can be 0 if:

• The reconciled event was non-rewarded (e.g., an install event), or
• The event was rejected, such as when a user completes it after the ttc_minutes (time-to-complete) limit expired. TTC dictates how much time the user has to complete an event after the install.

It is important to know that a reconciliation will no longer be negative, and the transaction ID for every state change will be the same if stateful offer callbacks are enabled.

If stateful callbacks are disabled, every reconciliation callback has a unique transaction ID that differs from the transaction ID of the complete callback. If you need the transaction ID of the complete callback instead, look at the [%REF%] parameter.

We offer a dedicated callback field to receive reconciliation callbacks on a separate endpoint.

Multi-Conversion

In some cases, the same event may be converted multiple times. This does not indicate a state change but rather represents a multi-convertible event. To prevent duplicate processing, always check the transaction ID and implement deduplication logic accordingly.

🚧

Make sure to only reward users for offer_state=COMPLETED callbacks!

Ban callbacks

In case of fraud, our system bans users. To help you recognize it, we will send a ban callback:

You can paste in the following URL while replacing publisher.com to match your endpoint. Keep in mind that, as for all callbacks, a hash for validation will be attached at the end.

<https://publisher.com?uid=[%UID%]&ban_reason=[%BAN_REASON%]&ban_state=[%BAN_STATE%]>

This will ban the user from all games and offers and only games and offers. They will still be able to complete surveys and upload receipts.

In-App purchases

Our callback system supports In-App purchase events. When a user makes a purchase in a game, you'll receive a callback event with the purchase amount. It functions like a standard offer task completion callback but includes additional details.

The following callback parameters will help you identify the In-App purchase events:

You can test in-app purchase callbacks using the callback tester on the dashboard. To do this, simply click the "$1 Offer Completion" button.

Special cases

• In some cases, In-App purchase events will be sent via two callbacks. The first is for the event completion, and the second is for the IAP data. This depends on the advertiser's setup.
• When we don't get the USD value from an IAP from an advertiser, then [%OFFER:TASK:IAP:USD%] will be empty.
• IAP events can be reconciled due to various reasons.

Offer parameters

For offers, we do provide additional parameters for additional information:

For a full list of all parameters, click here.

How to test offer callbacks

We offer a callback tester on the dashboard to test your configured callback endpoints. Learn more about it here.

Testing with real offers

To test with a real offer you can visit the offer wall, select a game, and install it. This way you will either receive a COMPLETED offer callback or a PENDING one, depending on whether delayed crediting is enabled or not.

Frequently Asked Questions

Find a list of frequently asked questions.

I'm getting a 3103 error when testing

This issue can appear due to many factors. Please contact your account manager for more insights, and make sure to provide your user ID.