> For the complete documentation index, see [llms.txt](https://docs.ayetstudios.com/v/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ayetstudios.com/v/product-docs/callbacks-and-testing/callbacks/surveywall-callbacks.md).

# Surveywall Callbacks

{% hint style="info" %}
For Web Surveywalls, you have to manually manage your users' currencies on your own servers.
{% endhint %}

## Adding your Callback URL

You can configure a conversion callback URL in our publisher dashboard.\
To do so, navigate to **Placements / Apps**, edit your placement and set the **Callback URL** to your server's postback URL:

<figure><img src="/files/4R0DlPMkC8wvffvtdyiU" alt=""><figcaption></figcaption></figure>

If this is the callback URL you set for your offerwall placement:

```
https://your-server.com/callback?network=ayetstudios&amount={currency_amount}&external_identifier={external_identifier}&payout_usd={payout_usd}
```

A typical conversion callback sent by our server will look like this:

```
https://your-server.com/callback?network=ayetstudios&amount=360&external_identifier=username&payout_usd=0.36
```

{% hint style="warning" %}
This assumes you set external\_identifier to **username** in the original Offerwall URL for that user, the currency conversion rate in your placement was 1000 per $1 and the user completed an offer with a $0.36 payout.
{% endhint %}

{% hint style="danger" %}
**Important:** Your server must always reply with an HTTP 200 status code to our postbacks. Otherwise we will resend the postback 12 times over a span of one hour before giving up.
{% endhint %}

## Enabling & Processing Reversal Callbacks

You can automatically process Reversals made to your account and placements by enabling **Reversal Callbacks.**

Simply navigate to **Placements / Apps**, edit your placement and check the box **Enable Reversal Callbacks**.

![](/files/Bx4Op9SndNwlw6nyGtnr)

Once enabled we will send reversal callbacks directly to the callback URL you set up for your placements.

The unique **transaction ID** we send for each conversion will carry an **"r-"** prepended to the ID for each reversal callback.

{% hint style="info" %}
For chargebacks the original transaction ID of a conversion is prepended with "**r-**".

**Example Transaction IDs:**

&#x20;   381f99333613b41392b15183d69a7240308e8461    ->   Regular Callback

**r-**&#x33;81f99333613b41392b15183d69a7240308e8461     ->   Reversal Callback
{% endhint %}

Below is a list of all relevant parameters to use in order to distinguish reversal callbacks from regular callbacks.

<table><thead><tr><th width="310">Variable</th><th width="145">Type</th><th>Description</th></tr></thead><tbody><tr><td>{transaction_id}</td><td>string</td><td>Unique transaction ID - use for duplicate checks. For chargebacks the original tid is prepended with "<strong>r-</strong>".</td></tr><tr><td>{is_chargeback}</td><td>int</td><td>Either 0 or 1. Indicator if the callback is a conversion (0) or a chargeback (1).</td></tr><tr><td>{chargeback_reason}</td><td>string</td><td>Reason why chargeback created. Only available if is_chargeback set to 1.</td></tr><tr><td>{chargeback_date}</td><td>string</td><td>Date of chargeback creation. Only available if is_chargeback set to 1.</td></tr></tbody></table>

## **Available Macros for Callback URLs**

{% hint style="info" %}
**Note:** If the parsing capabilities of your callback endpoint are limited, each of the parameters below is also available in a sanitized version. By suffixing any of the parameters below with `_sanitized` (for example `{external_identifier_sanitized}`), any character that is not in `0-9 a-z A-Z - _` will be removed. Whitespaces will be replaced by underscores.
{% endhint %}

{% hint style="danger" %}
**Important:**\
To ensure each conversion is granted only once to your users, always use {transaction\_id}.\
\
Occasional callback resends may occur for various reasons. Utilizing {transaction\_id} prevents granting conversions more than once.
{% endhint %}

<table><thead><tr><th width="318.3333333333333">Variable</th><th width="180">Type</th><th>Description</th></tr></thead><tbody><tr><td>{transaction_id}</td><td>string</td><td>Unique transaction ID - use for duplicate checks. For chargebacks the original tid is prepended with "<strong>r-</strong>".</td></tr><tr><td>{payout_usd}</td><td>float</td><td>The actual conversion payout in USD. If chargeback value is negative.</td></tr><tr><td>{currency_amount}</td><td>float</td><td>The amount of currency the user earned (taken from your offerwall currency configuration). If chargeback value is negative.</td></tr><tr><td>{is_screenout}</td><td>integer</td><td>Either 1 or 0. Indicates whether the conversion is a screenout reward (1) or a regular conversion (0).</td></tr><tr><td>{is_survey}</td><td>integer</td><td>Either 1 or 0. Always 1 for surveywall related conversions. 0 for offer conversions (e.g. when using the offerwall).</td></tr><tr><td>{external_identifier}</td><td>string</td><td>The user identifier (EXTERNAL IDENTIFIER) originally passed in the web offerwall link.</td></tr><tr><td>{user_id}</td><td>integer</td><td>Our internal ID for this offerwall user</td></tr><tr><td>{placement_identifier}</td><td>string</td><td>The placement_identifier for which the conversion occured</td></tr><tr><td>{survey_id}</td><td>unsigned int64</td><td>Survey ID of the completed survey</td></tr><tr><td>{loi}</td><td>float</td><td>Length of interview - the time it took the user to complete the survey in minutes</td></tr><tr><td>{adslot_id}</td><td>int</td><td>The ID of the adslot for which the conversion occured</td></tr><tr><td>{sub_id}</td><td>string</td><td>The ID of the Placement for which the conversion occured<br>[PL-1...n]</td></tr><tr><td>{ip}</td><td>string</td><td>Converting device's IP address if known, 0.0.0.0 otherwise</td></tr><tr><td>{offer_id}</td><td>int</td><td>Offer ID of the converting offer</td></tr><tr><td>{offer_name}</td><td>string</td><td>Name / title of the converting offer</td></tr><tr><td>{device_uuid}</td><td>string</td><td>ayeT-Studios internal device identificator</td></tr><tr><td>{device_make}</td><td>string</td><td>Device manufacturer</td></tr><tr><td>{device_model}</td><td>string</td><td>Device model</td></tr><tr><td>{advertising_id}</td><td>string</td><td>Device advertising id (GAID/IDFA) if known, otherwise empty</td></tr><tr><td>{sha1_android_id}</td><td>string</td><td>Device sha1 hashed android id if known, otherwise empty</td></tr><tr><td>{sha1_imei}</td><td>string</td><td>Device sha1 hashed IMEI, if known, otherwise empty</td></tr><tr><td>{is_chargeback}</td><td>int</td><td>Either 0 or 1. Indicator if the callback is a conversion (0) or a chargeback (1).</td></tr><tr><td>{chargeback_reason}</td><td>string</td><td>Reason why chargeback created. Only available if is_chargeback set to 1.</td></tr><tr><td>{chargeback_date}</td><td>string</td><td>Date of chargeback creation. Only available if is_chargeback set to 1.</td></tr><tr><td>{currency_identifier}</td><td>string</td><td>Shows virtual currency name as set in adslot.</td></tr><tr><td>{currency_conversion_rate}</td><td>decimal</td><td>Shows currency conversion rate used to calculate user currency for the given conversion.</td></tr><tr><td>{custom_1}</td><td>string</td><td>Custom parameter to pass variables to the conversion callbacks.</td></tr><tr><td>{custom_2}</td><td>string</td><td>Custom parameter to pass variables to the conversion callbacks.</td></tr><tr><td>{custom_3}</td><td>string</td><td>Custom parameter to pass variables to the conversion callbacks.</td></tr><tr><td>{custom_4}</td><td>string</td><td>Custom parameter to pass variables to the conversion callbacks.</td></tr><tr><td>{custom_5}</td><td>string</td><td>Custom parameter to pass variables to the conversion callbacks.</td></tr></tbody></table>