Developers

API Reference

Complete reference for TapRain's postback endpoint and offerwall embed integration.

Postback Reference

Server-to-server conversion notification endpoint.

TapRain receives conversion signals via a server-to-server postback (S2S callback). Your network or tracker fires this URL when a user completes an offer.

bash

GET https://taprain.com/api/postback/cpa

The request must originate from a pre-approved server IP address. Requests from unknown IPs are rejected with 403 Forbidden. Contact support to whitelist your postback server's IP.

Note

TapRain processes postbacks over HTTPS only. Plain HTTP requests will be redirected or rejected.

Query Parameters

All parameters are passed as URL query string values.

key

stringrequired

Security key assigned to your account. Never expose this in client-side code or URLs visible to end users.

external_identifier

stringrequired

The TapRain publisher ID to credit. This is the account that receives the payout.

amount

integerrequired

Payout in cents (not dollars). Example: 250 = $2.50. Must be a positive integer.

offer_name

string

Display name of the completed offer. Appears in reports and the live admin feed.

offer_id

string

Your internal offer identifier for cross-referencing.

status

integer

Conversion status. Pass 1 for approved. Other values may apply per network agreement.

country_code

string

ISO 3166-1 alpha-2 country code of the end-user (e.g. US, DE, GB). Used for analytics and quality scoring.

ip

string

End-user IP address. Used for fraud/quality scoring.

unix

integer

Unix timestamp (seconds) of the conversion event. Defaults to server receive time if omitted.

lead_id

string

Your network's internal lead or transaction ID. Stored for reconciliation.

click_id

string

Click-level tracking ID passed through from your traffic source.

s2

string

Secondary sub-ID (e.g. template ID, placement ID). Passed through to reporting.

Example request

bash

curl "https://taprain.com/api/postback/cpa?key=YOUR_SECURITY_KEY&external_identifier=6422f1b3e8a0000012345678&amount=350&offer_name=Shein+Shopping+App&country_code=US&ip=203.0.113.45&status=1&lead_id=abc123"

Response Codes

HTTP responses

200

Conversion received and processed. Response body: {"message":"ok"}. A 200 does not always mean the conversion was credited - quality checks run silently.

400

Bad Request

Missing required parameters (key, external_identifier, amount) or invalid amount value.

401

Unauthorized

Invalid or missing security key.

403

Forbidden

Request not authorized. Ensure your postback server IP has been approved. Contact support if needed.

404

Not Found

Publisher ID (external_identifier) does not match any account.

500

Internal Server Error

Unexpected server error. Retry with exponential backoff. Contact support if the error persists.

Note

A 200 response confirms the postback was received and processed. Conversion crediting is subject to quality review.

Success response body

JSON

{ "message": "ok" }

Error response body

JSON

{ "message": "Unauthorized" }

Offerwall Embed

Embed a TapRain offerwall as an iframe on any webpage.

Each offerwall has a unique share URL generated from the dashboard. Use it as the src of an iframe.

HTML

<iframe
  src="https://taprain.com/o/YOUR_OFFERWALL_ID"
  width="100%"
  height="600"
  frameborder="0"
  style="border-radius: 16px; border: none;"
></iframe>

Replace YOUR_OFFERWALL_ID with the ID shown on your Offerwalls page.

Embed URL parameters

s1

string

Publisher sub-ID for referral tracking. Used to attribute conversions to the referring publisher.

s2

string

Secondary sub-ID (placement, template, etc.). Passed through in postback.

country

string

Override country for offer filtering (ISO 3166-1 alpha-2). Defaults to the user's detected country.

device

string

Override device type: "desktop" or "mobile". Defaults to auto-detect from user agent.

Example with sub-IDs

HTML

<iframe
  src="https://taprain.com/o/abc123?s1=mysite&s2=homepage&country=US"
  width="100%"
  height="600"
  frameborder="0"
></iframe>