# 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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ayetstudios.com/v/product-docs/callbacks-and-testing/callbacks/surveywall-callbacks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.