Integration guide

S2S postback

Server-to-server reward callbacks, macros, and security.

How it works

When a user completes an offer, PrismAds sends an HTTP GET to each enabled URL under Publisher → Reports → Postbacks.

You configure a postback URL with macros
We fill macros and call your server
You verify signature, credit the user once, return 200

Next: Signature verification · Test postback

Live vs test (important)

Path	Where you configure the URL	When it fires
Live rewards	Publisher → Reports → Postbacks	Real conversions
Test endpoint	Postback URL on the placement	Only `GET /api/v1/postback/test`

The test API does not call your Reports postbacks. Passing a test fire does not prove live S2S is configured, and the reverse is also true.

Setup (live)

Open Publisher → Reports → Postbacks
Create a postback URL template
Copy the one-time signing secret and store it securely

Example URL:

code

https://your-app.com/postback?user_id={user_id}&payout={payout}&value={value}&txid={txid}&offer_id={offer_id}&status={status}&signature={signature}

Request format

Rule	Detail
Method	Always GET
Body	None — all data is in the query string
Encoding	Macro values are URL-encoded
Header	`User-Agent: PrismAds-Postback/1.0`

Sample:

code

GET /postback?user_id=u_99&payout=0.75&value=75&txid=tx_abc&offer_id=offer_1&status=approved&signature=...

Macros

Macro	Meaning
`{user_id}`	End-user id from the wall
`{payout}`	Publisher payout in USD
`{value}`	Virtual currency amount
`{currency}`	Currency code
`{txid}` / `{token}`	Unique transaction id
`{offer_id}`	Offer id
`{offer_name}`	Offer title
`{status}`	approved / pending / chargeback
`{event}`	Goal name (`payout`, `install`, …)
`{click_id}`	Click id
`{country}`	ISO country
`{ip}`	End-user IP
`{placement_id}`	Placement id
`{sub1}` `{sub2}` `{sub3}`	Optional subs
`{signature}`	HMAC-SHA256 authenticity hash

payout is USD. value is in-app currency (payout × exchange rate). Signature uses truncated value.

Your response

Your HTTP status	Our action
200–299	Delivered
other / timeout	Retry (up to 5 times with exponential backoff)

Store txid uniquely. If the same txid arrives again, return 200 without re-crediting.

Security

Verify signature with your Reports postback signing secret — see Signature verification
Keep the secret server-side only
Whitelist our postback source IPs on your firewall / WAF so only PrismAds can hit your URL (set POSTBACK_SOURCE_IPS on the platform; ask support for the current list)
Never credit rewards from the client alone — always wait for S2S

Inbound provider S2S to PrismAds can also be IP-locked per provider (ipAllowlist / enforceIp) or globally via S2S_IP_ALLOWLIST. Requests from any other IP return 403 IP_NOT_ALLOWED.

Chargebacks

status=chargeback means reverse the prior credit for the same txid when possible. See Chargebacks.

Example handler (PHP)

php

$user = $_GET['user_id'];
$value = (int)$_GET['value'];
$token = $_GET['txid'] ?? $_GET['token'];
$sig = $_GET['signature'];
$message = $user . '.' . $value . '.' . $token;
$expected = hash_hmac('sha256', $message, $secret);
if (!hash_equals($expected, $sig)) { http_response_code(403); exit; }
// credit once using $token
http_response_code(200); echo 'OK';

Dry-run a placement URL

The test endpoint fires the placement postback URL (not Reports). Full steps: Test postback.

iOS

Signature verification