Magic Receipt callbacks
This page describes on how to utilize callbacks for different magic receipt states.
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: 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 typestate_change
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
, andRAW
.- 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.
- For magic receipts, we also recommend to add the
- 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.
Magic Receipt parameters
For magic receipts we do provide additional parameters for additional information:
Parameter | Type | Description |
---|---|---|
[%MAGIC_RECEIPT_STATE%] | String | It can only be used when using Stateful Magic Receipts Callbacks. One of: COMPLETED , PENDING , RECONCILED , REVIEWING |
[%MAGIC_RECEIPT_REASON%] | String | Returns the reason why a receipt got rejected or approved. |
[%MAGIC_RECEIPT_REASON_ID%] | Integer | Returns the id of the reason. |
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:
- Set up the magic receipts callback
- Copy the URL in the configuration modal at the bottom
- Replace the hash in the URL with the real hash according to this page
- Replace the reward amount, state and user ID with the correct ones
- Open the URL in the web browser
This will send you a callback with which you can test your system.
Updated about 2 months ago