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 and 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: You can enable the stateful magic receipts callbacks which have the following effects:

• Magic receipt callbacks for all states will be sent now (Before only COMPLETED would be sent)
• The transaction ID for each state change will be the same
• The TYPE parameter will return the type state_change
  • It is recommended not to use TYPE for magic receipts.

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. This is the only final state and can not change.

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. REVIEWING can only occur once after a RECONCILIED was fired. A specific receipt submission can only be once in REVIEWING.

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. A RECONCILED state is never final and can change to a COMPLETED or REVIEWING.

🚧

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

Magic Receipt parameters

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

For a full list of all parameters click here. For more information on the magic receipt reasons, click here.

How to test Magic Receipt callbacks

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

Legacy way of testing

🚧

The following part of the documentation explains how callbacks were tested before the callback tester on the dashboard existed. We highly recommend not using the following method anymore!

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.

Magic Receipt Reasons and Reason IDs

In the following table you can see all the different reason IDs and descriptions.