> For the complete documentation index, see [llms.txt](https://sdk-doc.tyrads.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sdk-doc.tyrads.com/getting-started/postback-payout-s2s-and-setup.md).

# Postback Payout (S2S) and Setup

In order for users to redeem their accumulated rewarded plays, they must be disbursed. Each reward can only be claimed once.

## 1.  Server to Server (S2S) Payout

To utilize server-to-server payout, you must establish an endpoint on your server. This endpoint will be requested by us to notify you of the user's rewards. Upon receiving the notification, it will be your responsibility to deliver it to the user.

We strongly advise implementing server-to-server payout for rewards, as it offers increased security and enhanced transparency on your part.

{% hint style="info" %}
Please contact TyrAds team for dashboard access and setup your endpoint URL within our Solutions dashboard.
{% endhint %}

## 1.1 Postback Setup in Solutions Dashboard

{% stepper %}
{% step %}

### Login

Log in to the Solutions Dashboard and navigate to Monetization > SDK Integration.
{% endstep %}

{% step %}

### Adding Media Asset

Click Add App or select Edit on an existing Media Asset.
{% endstep %}

{% step %}

### Postback URL&#x20;

Under Step 2: Adding Ad Unit, locate the Postback URL field.
{% endstep %}

{% step %}

### Setup

Enter your endpoint URL. This is the most critical part of the setup required to track user activity and reward users.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Please refer to the guide below for more information and details on integration setup within Solutions dashboard. Please also note that API credentials can be found within the Media Asset/App after the integration setup in dashboard is done.
{% endhint %}

{% file src="/files/Jh2j2ZLdsOxN1Dq0N8J3" %}

## 1.2 HTTP Request Structure

Your endpoint will be invoked via `HTTP` request with `GET` method.  The parameters of the request are as follows:

<table><thead><tr><th width="257.0078125">Paramater</th><th width="120">Data Type</th><th>Description</th></tr></thead><tbody><tr><td><code>conversion_status</code></td><td>enum</td><td>The status of conversion. Enum: <code>approved</code>, <code>rejected(if set up)</code>, <code>flagged</code>, <code>invalid</code>,<code>pending</code></td></tr><tr><td><code>conversion_type</code></td><td>enum</td><td>The type of conversion: Enum: <code>install</code>, <code>event</code></td></tr><tr><td><code>cost</code></td><td>decimal</td><td>The payout amount you earn from Tyrads in U.S. Dollars. </td></tr><tr><td><code>user_payout_converted</code></td><td>decimal</td><td>The payout amount the user earns based on the currency conversion set.</td></tr><tr><td><code>timestamp</code></td><td>integer</td><td>The UNIX timestamp of the conversion </td></tr><tr><td><code>publisher_user_id</code><sup><strong>*Mandatory</strong></sup></td><td>string</td><td>The unique user id of the publisher used to identify the user</td></tr><tr><td><code>conversion_id</code></td><td>integer (format: <code>int64</code>)</td><td>The unique conversion ID can be used for deduplication if the <code>conversion_type</code> is <code>install</code> or <code>event</code>. </td></tr><tr><td><code>postback_id</code></td><td>integer (format: <code>int64</code>)</td><td>The unique postback ID can be used for deduplication.</td></tr><tr><td><code>app_name</code></td><td>string</td><td>The name of the app</td></tr><tr><td><code>event_name</code></td><td>string</td><td>The name of the event</td></tr><tr><td><code>sub3</code></td><td>string</td><td>The sub3 value, this can be any value you want and can be used to send to us on the click.</td></tr><tr><td><code>sub4</code></td><td>string</td><td>The sub4 value, this can be any value you want and can be used to send to us on the click.</td></tr><tr><td><code>ad_unit_id</code></td><td>string</td><td>The unique ad unit identifier </td></tr><tr><td><code>currency_name</code></td><td>string</td><td>The name of the currency </td></tr><tr><td><code>fraud</code><sup><strong>*Recommended</strong></sup></td><td>boolean</td><td><code>true</code> when the conversion was rejected for a fraud reason (for example Anomaly detection, Purchase fraud). <code>false</code> for other rejections and for approved conversions.</td></tr><tr><td><code>reversal</code><sup><strong>*Recommended</strong></sup></td><td>boolean</td><td><code>true</code> only when an event we previously approved is now rejected. Deduct anything you credited for that <code>conversion_id</code>. <code>false</code> in every other case.</td></tr><tr><td><code>payable</code><sup><strong>*Recommended</strong></sup></td><td>boolean</td><td><code>true</code> when the conversion is approved and has a payout greater than 0. <code>false</code> for rejected and flagged conversions. Use this, not <code>cost</code>, to decide whether a conversion is paid.</td></tr></tbody></table>

Example of Postback URL Setup:

{% tabs %}
{% tab title="Example Postback URL Setup" %}
[https://examplepostbackurl.com?conversion\_id={conversion\_id}\&conversion\_status={conversion\_status}\&conversion\_type={conversion\_type}\&event\_name={event\_name}\&app\_name={app\_name}\&app\_event\_id={app\_event\_id}\&payout={cost}\&timestamp={timestamp}\&publisher\_user\_id={publisher\_user\_id}\&user\_payout={user\_payout\_converted}\&postback\_id={postback\_id}\&sub3={sub3}\&sub4={sub4}\&ad\_unit\_id={ad\_unit\_id}\&fraud={fraud}\&reversal={reversal}\&payable={payable}](https://examplepostbackurl.com/?conversion_id={conversion_id}\&conversion_status={conversion_status}\&conversion_type={conversion_type}\&event_name={event_name}\&app_name={app_name}}\&app_event_id={app_event_id}\&payout={cost}\&timestamp={timestamp}\&publisher_user_id={publisher_user_id}\&user_payout={user_payout_converted}\&rewarded_play_id={rewarded_play_id}\&postback_id={postback_id}\&sub3={sub3}\&sub4={sub4}\&ad_unit_id={ad_unit_id}\&fraud={fraud}\&reversal={reversal}\&payable={payable})
{% endtab %}
{% endtabs %}

{% hint style="info" %}
Please note that variables like \&payout on the left can be adjusted to match your parameters. Meanwhile, the macros on the right, such as {cost}, need to adhere to the macro names listed in the table above.

Unused macros such as sub2, sub3, or sub4 can be omitted if no values are being passed through them during initialization of SDK.
{% endhint %}

### Suggestions on postback handling

The postback that we sent are recommended to be handled in this logic. They keep your user rewards and your totals in line with our reports.

1. **Have a record on every postback that we sent.** Store each postback with its `conversion_id` and `postback_id`. You'll need these records to reconcile with us and to raise support tickets.&#x20;
2. **`reversal=true`: deduct.** We approved this conversion earlier and are now rejecting it. Deduct what you credited for this `conversion_id` .
3. **`payable=true`: reward.** Credit the user once per `conversion_id`.
4. **`payable=false`: keep as a record, do not reward.** This covers rejected and flagged conversions, and approved conversions with no payout. If a later postback for the same `conversion_id` arrives with `payable=true` (for example after a review), reward it then.
5. **`fraud=true`: do not reward.** The conversion was rejected by our fraud checks. You can also use this to review the user's activity on your side.

A reversal applies only to the `conversion_id` in that postback. Don't reverse other events of the same user or campaign unless you receive a reversal for them too.

**At month end**, reconcile against the conversions where the latest postback has `payable=true`. That total should match the approved conversions in our reports.

{% code title="Example logic" %}

```
on postback:
    if postback_id already processed: stop
    save postback (conversion_id, postback_id, conversion_status, fraud, reversal, payable, cost)

    if reversal == "true":
        deduct the amount credited for conversion_id
    else if payable == "true":
        reward the user for conversion_id (once only)
    else:
        no reward; keep as record
```

{% endcode %}

#### What each combination means

| **What happened**                                               | **`conversion_status`** | **`fraud`** | **`reversal`** | **`payable`** | **What to do**                                     |
| --------------------------------------------------------------- | ----------------------- | ----------- | -------------- | ------------- | -------------------------------------------------- |
| Approved, with payout                                           | approved                | false       | false          | true          | Credit the user.                                   |
| Approved, no payout (for example the install of a CPE campaign) | approved                | false       | false          | false         | Keep as record. No reward for this conversion.     |
| Flagged                                                         | flagged                 |             |                | false         | Keep as record. Do not reward.                     |
| Rejected for fraud, never approved                              | rejected                | true        | false          | false         | Keep as record. Do not reward. Nothing to deduct.  |
| Approved earlier, now rejected for fraud                        | rejected                | true        | true           | false         | Deduct what you credited for this `conversion_id`. |
| Rejected for a non-fraud reason (for example Duplicate Event)   | rejected                | false       | false          | false         | Keep as record. Do not reward.                     |
| Rejected earlier, now approved after review                     | approved                | false       | false          | true          | Credit the user.                                   |

Example of a fraud rejection that reverses an earlier approval:

`conversion_status=rejected&publisher_revenue=2.00&fraud=true&reversal=true&payable=false`

{% hint style="warning" %}
**Rejected postbacks are enabled by the TyrAds team.** To receive rejections, ask your integration contact to enable rejected postbacks and share the URL they should be sent to. Add `{fraud}`, `{reversal}` and `{payable}` to that URL as well.
{% endhint %}
