What is a Magic Receipt callback?

A magic receipt callback is a specific callback only sent for magic receipt state changes (also called stateful magic receipt callbacks). The magic receipt callbacks work differently from the general reward callbacks since you will receive all the different states of a receipt as well as additional information about the receipt.

How to set up Magic Receipts callbacks

To set up the magic receipt stateful callbacks, visit the Publisher Dashboard -> Apps -> Your App -> Integration -> Magic Receipts Callback:

IMPORTANT: Enable the Stateful Magic Receipts Callbacks, otherwise you will not be able to receive the magic receipts state in the callbacks.

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 magic receipts, we also recommend to add the magic_receipt_state parameter. magic_receipt_state will return the state of a receipt: PENDING, REVIEWING, RECONCILED, COMPLETED. Learn more about the magic receipt 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.

Magic Receipt states

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

COMPLETED: The COMPLETED callback will be sent when a receipt is approved.

PENDING: A PENDING callback will be sent when a reward for a magic receipt is pending. After a PENDING callback was sent, a COMPLETED or RECONCILED can follow.

REVIEWING: A REVIEWING callback will be sent when a receipt goes into manual review. A support person takes a look at the receipt. After a REVIEWING callback was sent, a COMPLETED or RECONCILED can follow.

RECONCILED: A RECONCILED callback will be sent when a magic receipt is rejected. You can use the reason and reason id macros to learn more about the rejection.

Magic Receipt parameters

For magic receipts we do provide additional parameters for additional information:

For a full list of all parameters click here.

How to test Magic Receipt callbacks

Currently, we do not offer a way to test the magic receipts callbacks end-to-end. The only way to test if your system can process a callback, is to simulate it. You can simulate a callback by following these steps:

1. Set up the magic receipts callback
2. Copy the URL in the configuration modal at the bottom
3. Replace the hash in the URL with the real hash according to this page
4. Replace the reward amount, state and user ID with the correct ones
5. Open the URL in the web browser

This will send you a callback with which you can test your system.