{
    "info": {
        "name": "Offerwall.GG Publisher API",
        "description": "Fill in `publicKey` and `secretKey` under the collection's Variables tab — everything else is wired up.\n\nBoth are on your placement's page in the dashboard: https://offerwall.gg/publisher/apps\n\nThe **Postback** folder is not a request you send us; it is the callback we send you. It is here so you can fire a realistic one at your own endpoint while you build it — the pre-request script signs it exactly the way we do.",
        "version": "1.0.0",
        "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
    },
    "auth": {
        "type": "apikey",
        "apikey": [
            {
                "key": "key",
                "value": "X-Api-Key",
                "type": "string"
            },
            {
                "key": "value",
                "value": "{{secretKey}}",
                "type": "string"
            },
            {
                "key": "in",
                "value": "header",
                "type": "string"
            }
        ]
    },
    "variable": [
        {
            "key": "baseUrl",
            "value": "https://offerwall.gg",
            "type": "string",
            "description": "The API host. Leave as is."
        },
        {
            "key": "publicKey",
            "value": "",
            "type": "string",
            "description": "Your placement's 32-character public key."
        },
        {
            "key": "secretKey",
            "value": "",
            "type": "string",
            "description": "Your placement's secret key. Never ships in client code."
        },
        {
            "key": "userId",
            "value": "user-1234",
            "type": "string",
            "description": "Any one of your own user ids, for testing."
        },
        {
            "key": "offerId",
            "value": "",
            "type": "string",
            "description": "Fill from the id of any offer the list call returns."
        },
        {
            "key": "postbackUrl",
            "value": "https://you.example/callback",
            "type": "string",
            "description": "Your own callback, for the Postback folder."
        }
    ],
    "item": [
        {
            "name": "Offers",
            "description": "The inventory available to one placement, already targeted.",
            "item": [
                {
                    "name": "List the offers available to one user",
                    "request": {
                        "method": "GET",
                        "description": "Returns only what this placement may show: the offer targets the user's country and device, it is above your payout floor, and it is not on any of your blocklists.\n\nPass `userId` to get a ready-to-use `clickUrl` on every offer. Without it you get the catalogue but no click URLs — an unattributed click cannot become a conversion, so we do not hand one out.",
                        "header": [],
                        "url": {
                            "raw": "{{baseUrl}}/api/v1/offers",
                            "host": [
                                "{{baseUrl}}"
                            ],
                            "path": [
                                "api",
                                "v1",
                                "offers"
                            ],
                            "query": [
                                {
                                    "key": "appId",
                                    "value": "{{publicKey}}",
                                    "description": "Your placement's public key. Safe to expose — it identifies, it does not authenticate.",
                                    "disabled": false
                                },
                                {
                                    "key": "userId",
                                    "value": "{{userId}}",
                                    "description": "Your own id for this user. Stable and opaque; we never see your usernames.",
                                    "disabled": false
                                },
                                {
                                    "key": "country",
                                    "value": "DE",
                                    "description": "Override the detected country (ISO 3166-1 alpha-2).",
                                    "disabled": true
                                },
                                {
                                    "key": "device",
                                    "value": "android",
                                    "description": "Override the detected device. Read from `userAgent` when that is sent instead.",
                                    "disabled": true
                                },
                                {
                                    "key": "ip",
                                    "value": "93.184.216.34",
                                    "description": "The user's public IPv4 or IPv6 address. Your call comes from your server, so without it the offers matched to one person (PTC ads, articles, surveys and some app offers) are asked for your server's address and usually come back empty. Private and reserved ranges are refused.",
                                    "disabled": true
                                },
                                {
                                    "key": "userAgent",
                                    "value": "Mozilla/5.0 (Linux; Android 14) AppleWebKit/537.36 Chrome/126.0 Mobile Safari/537.36",
                                    "description": "The user's browser user agent. Send it with `ip`: a server's own user agent (curl, a PHP client) is treated as a bot and gets no per-user offers.",
                                    "disabled": true
                                },
                                {
                                    "key": "category",
                                    "value": "games",
                                    "description": "Filter to one category key from /categories.",
                                    "disabled": true
                                },
                                {
                                    "key": "type",
                                    "value": "singlestep",
                                    "description": "Filter by offer shape.",
                                    "disabled": true
                                },
                                {
                                    "key": "search",
                                    "value": "coin",
                                    "description": "Free-text match on the offer name.",
                                    "disabled": true
                                },
                                {
                                    "key": "sort",
                                    "value": "recommended",
                                    "description": "Ordering. Defaults to recommended: offers ranked by what they actually earn per click on our traffic in the user's country, with offers the user already completed or keeps abandoning last. payout orders by the headline payout.",
                                    "disabled": true
                                },
                                {
                                    "key": "page",
                                    "value": "1",
                                    "description": "1-based page number.",
                                    "disabled": true
                                },
                                {
                                    "key": "limit",
                                    "value": "50",
                                    "description": "Offers per page.",
                                    "disabled": true
                                }
                            ],
                            "variable": []
                        }
                    },
                    "response": []
                },
                {
                    "name": "One offer, with its goal ladder",
                    "request": {
                        "method": "GET",
                        "description": "The same object `/offers` returns, plus `goals` — the steps of a multi-step offer and what each one pays. A single-step offer has an empty goal list. Blocked and inactive offers 404 here even if you have the id.",
                        "header": [],
                        "url": {
                            "raw": "{{baseUrl}}/api/v1/offers/:offer",
                            "host": [
                                "{{baseUrl}}"
                            ],
                            "path": [
                                "api",
                                "v1",
                                "offers",
                                ":offer"
                            ],
                            "query": [
                                {
                                    "key": "appId",
                                    "value": "{{publicKey}}",
                                    "description": "Your placement's public key. Safe to expose — it identifies, it does not authenticate.",
                                    "disabled": false
                                },
                                {
                                    "key": "userId",
                                    "value": "{{userId}}",
                                    "description": "Include to receive a `clickUrl`.",
                                    "disabled": false
                                }
                            ],
                            "variable": [
                                {
                                    "key": "offer",
                                    "value": "{{offerId}}",
                                    "description": "Our numeric offer id, from `id` in the list response."
                                }
                            ]
                        }
                    },
                    "response": []
                },
                {
                    "name": "The category vocabulary, with live counts",
                    "request": {
                        "method": "GET",
                        "description": "Everything you need to build a filter UI. The counts are for this placement and this user's targeting, so a category with 0 offers can be hidden rather than shown empty.",
                        "header": [],
                        "url": {
                            "raw": "{{baseUrl}}/api/v1/categories",
                            "host": [
                                "{{baseUrl}}"
                            ],
                            "path": [
                                "api",
                                "v1",
                                "categories"
                            ],
                            "query": [
                                {
                                    "key": "appId",
                                    "value": "{{publicKey}}",
                                    "description": "Your placement's public key. Safe to expose — it identifies, it does not authenticate.",
                                    "disabled": false
                                },
                                {
                                    "key": "country",
                                    "value": "US",
                                    "description": "Count against this country instead of the detected one.",
                                    "disabled": true
                                },
                                {
                                    "key": "device",
                                    "value": "android",
                                    "description": "Count against this device instead of the detected one.",
                                    "disabled": true
                                }
                            ],
                            "variable": []
                        }
                    },
                    "response": []
                }
            ]
        },
        {
            "name": "Conversions",
            "description": "Completed offers. For reconciliation — real-time delivery is the postback.",
            "item": [
                {
                    "name": "Completed offers, for reconciliation",
                    "request": {
                        "method": "GET",
                        "description": "Use this to reconcile, not to deliver rewards. The postback is the real-time channel; polling this endpoint will always be behind it.\n\nA `reversed` conversion is one a network charged back. If you already paid the user, this is where you find out.\n\nPass `transactionId` to look up one conversion by the id its postback carried. A reversal re-sends the **same** `transactionId` with `status: reversed`, so one id addresses one conversion for its whole life — this is the authoritative source for `payoutUsd`, which is not covered by the postback signature.",
                        "header": [],
                        "url": {
                            "raw": "{{baseUrl}}/api/v1/conversions",
                            "host": [
                                "{{baseUrl}}"
                            ],
                            "path": [
                                "api",
                                "v1",
                                "conversions"
                            ],
                            "query": [
                                {
                                    "key": "appId",
                                    "value": "{{publicKey}}",
                                    "description": "Your placement's public key. Safe to expose — it identifies, it does not authenticate.",
                                    "disabled": false
                                },
                                {
                                    "key": "transactionId",
                                    "value": "e794d89342e0c468f6dd81205999425b",
                                    "description": "Look up one conversion by the id its postback carried. Unique, so this returns at most one row.",
                                    "disabled": true
                                },
                                {
                                    "key": "userId",
                                    "value": "{{userId}}",
                                    "description": "Restrict to one of your users.",
                                    "disabled": false
                                },
                                {
                                    "key": "status",
                                    "value": "credited",
                                    "description": "Restrict to one status.",
                                    "disabled": true
                                },
                                {
                                    "key": "page",
                                    "value": "1",
                                    "description": "1-based page number.",
                                    "disabled": true
                                },
                                {
                                    "key": "limit",
                                    "value": "50",
                                    "description": "Rows per page.",
                                    "disabled": true
                                }
                            ],
                            "variable": []
                        }
                    },
                    "response": []
                }
            ]
        },
        {
            "name": "Reporting",
            "description": "Daily rollups and totals.",
            "item": [
                {
                    "name": "Daily series and totals for one placement",
                    "request": {
                        "method": "GET",
                        "description": "Read from the daily rollup table, so it is cheap to poll hourly. `payoutUsd` is what you earned, in USD.",
                        "header": [],
                        "url": {
                            "raw": "{{baseUrl}}/api/v1/stats",
                            "host": [
                                "{{baseUrl}}"
                            ],
                            "path": [
                                "api",
                                "v1",
                                "stats"
                            ],
                            "query": [
                                {
                                    "key": "appId",
                                    "value": "{{publicKey}}",
                                    "description": "Your placement's public key. Safe to expose — it identifies, it does not authenticate.",
                                    "disabled": false
                                },
                                {
                                    "key": "days",
                                    "value": "30",
                                    "description": "How many days back, ending today.",
                                    "disabled": true
                                }
                            ],
                            "variable": []
                        }
                    },
                    "response": []
                }
            ]
        },
        {
            "name": "Wall",
            "description": "The hosted offerwall and its click tracker. HTML and redirects, not JSON.",
            "item": [
                {
                    "name": "The hosted offerwall (HTML, for an iframe)",
                    "request": {
                        "method": "GET",
                        "description": "This is the whole integration for most publishers. Put it in an iframe:\n\n```html <iframe src=\"https://offerwall.gg/wall/PUBLIC_KEY?userId=user-1234\"         style=\"width:100%;height:800px;border:0\"         allow=\"clipboard-write\"></iframe> ```\n\nNo cookies are set on this page — it is served to *your* users, not ours, and a third-party cookie would be blocked anyway. The public key in the URL is the credential.\n\nWithout a `userId` the wall still renders but clicking is refused. That is preview mode, and it is what to use while you are building.\n\nIf you set **allowed domains** on the placement, we send `Content-Security-Policy: frame-ancestors` naming them, so the wall will only render inside your own pages.",
                        "header": [],
                        "url": {
                            "raw": "{{baseUrl}}/wall/:publicKey",
                            "host": [
                                "{{baseUrl}}"
                            ],
                            "path": [
                                "wall",
                                ":publicKey"
                            ],
                            "query": [
                                {
                                    "key": "userId",
                                    "value": "{{userId}}",
                                    "description": "Your id for this user. Omit for preview mode.",
                                    "disabled": false
                                },
                                {
                                    "key": "signature",
                                    "value": "",
                                    "description": "Required when the placement has \"require signature\" on. See the SignedQuery scheme.",
                                    "disabled": true
                                },
                                {
                                    "key": "ts",
                                    "value": "",
                                    "description": "Unix seconds. Required alongside `signature` only when expiring links are enabled.",
                                    "disabled": true
                                }
                            ],
                            "variable": [
                                {
                                    "key": "publicKey",
                                    "value": "{{publicKey}}",
                                    "description": "Your placement's 32-character public key."
                                }
                            ]
                        }
                    },
                    "response": []
                },
                {
                    "name": "Record a click and redirect to the advertiser",
                    "request": {
                        "method": "GET",
                        "description": "Send the user here, never straight to the advertiser. The click row is written **before** the redirect and it is the only thing that makes a conversion attributable days later.\n\nIf you are drawing your own wall, this is the `clickUrl` the API already gave you — use it verbatim rather than building it yourself.",
                        "header": [],
                        "url": {
                            "raw": "{{baseUrl}}/wall/:publicKey/click/:offer",
                            "host": [
                                "{{baseUrl}}"
                            ],
                            "path": [
                                "wall",
                                ":publicKey",
                                "click",
                                ":offer"
                            ],
                            "query": [
                                {
                                    "key": "userId",
                                    "value": "{{userId}}",
                                    "description": "Required — there is nobody to attribute an anonymous click to.",
                                    "disabled": false
                                }
                            ],
                            "variable": [
                                {
                                    "key": "publicKey",
                                    "value": "{{publicKey}}",
                                    "description": "Your placement's public key."
                                },
                                {
                                    "key": "offer",
                                    "value": "{{offerId}}",
                                    "description": "Our numeric offer id."
                                }
                            ]
                        }
                    },
                    "response": []
                }
            ]
        },
        {
            "name": "Surveys",
            "description": "Paid surveys matched to one user by the survey panels. Called from your server with the user's IP, country and user agent.",
            "item": [
                {
                    "name": "List the surveys one user can take now",
                    "request": {
                        "method": "GET",
                        "description": "Survey panels decide per person: what a user is offered depends on their IP, device and the profile the panel already holds. Call this from YOUR server and pass the user's own `ip`, `country` and `userAgent` — the request's IP is your server's, and a panel asked with it answers for your data centre.\n\nEvery survey carries what it pays twice: `payoutUsd` is what you earn in US dollars, and `reward` is the same amount converted into your currency at your rate — the number to show the user and to credit them when the postback arrives.\n\nSend the user to `clickUrl` from their own browser. The list is kept for a few minutes per user, so calling again straight away returns the same surveys without asking the panels.",
                        "header": [],
                        "url": {
                            "raw": "{{baseUrl}}/api/v1/surveys",
                            "host": [
                                "{{baseUrl}}"
                            ],
                            "path": [
                                "api",
                                "v1",
                                "surveys"
                            ],
                            "query": [
                                {
                                    "key": "appId",
                                    "value": "{{publicKey}}",
                                    "description": "Your placement's public key. Safe to expose — it identifies, it does not authenticate.",
                                    "disabled": false
                                },
                                {
                                    "key": "userId",
                                    "value": "{{userId}}",
                                    "description": "Your own id for this user.",
                                    "disabled": false
                                },
                                {
                                    "key": "ip",
                                    "value": "93.184.216.34",
                                    "description": "The user's public IPv4 or IPv6 address. Private and reserved ranges are refused.",
                                    "disabled": false
                                },
                                {
                                    "key": "country",
                                    "value": "DE",
                                    "description": "The user's country (ISO 3166-1 alpha-2), from your own geo lookup.",
                                    "disabled": false
                                },
                                {
                                    "key": "userAgent",
                                    "value": "Mozilla/5.0 (Linux; Android 14) AppleWebKit/537.36 Chrome/126.0 Mobile Safari/537.36",
                                    "description": "The user's browser user agent. Strongly recommended: panels use it to match the device.",
                                    "disabled": true
                                },
                                {
                                    "key": "device",
                                    "value": "android",
                                    "description": "Set the device instead of reading it from `userAgent`.",
                                    "disabled": true
                                },
                                {
                                    "key": "page",
                                    "value": "1",
                                    "description": "1-based page number.",
                                    "disabled": true
                                },
                                {
                                    "key": "limit",
                                    "value": "50",
                                    "description": "Surveys per page.",
                                    "disabled": true
                                }
                            ],
                            "variable": []
                        }
                    },
                    "response": []
                }
            ]
        },
        {
            "name": "Traffic Tasks",
            "description": "Timed visits: the user keeps a sponsored site open for a set time on our view page, then passes a quick check. Completion sends the same postback as an offer.",
            "item": [
                {
                    "name": "List the Traffic Tasks one user can start now",
                    "request": {
                        "method": "GET",
                        "description": "Timed visits for this user, targeted like offers. A task this user completed inside its repeat window, or has open in another tab, is left out.\n\nDraw the list however you like; the task itself always runs on our view page (`offerwall.gg/view.php`), because the timer and the check have to run where we can count them. Send the user to `startUrl` in a NEW TAB. On completion you receive the same postback as for an offer — same parameters, same signature, the reward in your currency.\n\nWithout `userId` you get the catalogue and no `startUrl`. PTC ads and articles are matched to one person at one address, so pass the user's own `ip` and `userAgent` too, or they are asked for your server and the list comes back without them.",
                        "header": [],
                        "url": {
                            "raw": "{{baseUrl}}/api/v1/traffic",
                            "host": [
                                "{{baseUrl}}"
                            ],
                            "path": [
                                "api",
                                "v1",
                                "traffic"
                            ],
                            "query": [
                                {
                                    "key": "appId",
                                    "value": "{{publicKey}}",
                                    "description": "Your placement's public key. Safe to expose — it identifies, it does not authenticate.",
                                    "disabled": false
                                },
                                {
                                    "key": "userId",
                                    "value": "{{userId}}",
                                    "description": "Your own id for this user.",
                                    "disabled": false
                                },
                                {
                                    "key": "country",
                                    "value": "DE",
                                    "description": "Override the detected country (ISO 3166-1 alpha-2).",
                                    "disabled": true
                                },
                                {
                                    "key": "device",
                                    "value": "android",
                                    "description": "Override the detected device. Read from `userAgent` when that is sent instead.",
                                    "disabled": true
                                },
                                {
                                    "key": "ip",
                                    "value": "93.184.216.34",
                                    "description": "The user's public IPv4 or IPv6 address. Your call comes from your server, so without it the offers matched to one person (PTC ads, articles, surveys and some app offers) are asked for your server's address and usually come back empty. Private and reserved ranges are refused.",
                                    "disabled": true
                                },
                                {
                                    "key": "userAgent",
                                    "value": "Mozilla/5.0 (Linux; Android 14) AppleWebKit/537.36 Chrome/126.0 Mobile Safari/537.36",
                                    "description": "The user's browser user agent. Send it with `ip`: a server's own user agent (curl, a PHP client) is treated as a bot and gets no per-user offers.",
                                    "disabled": true
                                },
                                {
                                    "key": "limit",
                                    "value": "50",
                                    "description": "Most tasks to return.",
                                    "disabled": true
                                }
                            ],
                            "variable": []
                        }
                    },
                    "response": []
                }
            ]
        },
        {
            "name": "Postback (we call you)",
            "description": "Not a request to us — a simulation of the callback we send you.\n\nPoint `postbackUrl` at your own endpoint and press Send. The pre-request script signs the payload with your `secretKey` exactly as we do, so if your verification accepts this, it will accept ours.\n\nThen change one character of `currencyAmount` in the sent URL and confirm your endpoint REJECTS it. A postback you do not verify is a postback anyone can forge.\n\n`test=1` on both requests: never credit a user from a test.",
            "event": [
                {
                    "listen": "prerequest",
                    "script": {
                        "type": "text/javascript",
                        "exec": [
                            "// Sign the simulated postback the way Offerwall.GG signs a real one:",
                            "//   HMAC-SHA256 of \"userId:transactionId:currencyAmount\", keyed with the",
                            "//   placement's secret. Only those three fields, in that order.",
                            "const url = pm.request.url;",
                            "const get = (k) => { const p = url.query.find(q => q.key === k); return p ? p.value : ''; };",
                            "",
                            "// Resolve Postman's own dynamic variables first, or we would sign the",
                            "// literal text '{{$guid}}' and the receiver would see a different id.",
                            "const resolve = (v) => v && v.startsWith('{{') ? pm.variables.replaceIn(v) : v;",
                            "const userId = resolve(get('userId'));",
                            "const txId   = resolve(get('transactionId'));",
                            "const amount = resolve(get('currencyAmount'));",
                            "",
                            "url.query.each(q => {",
                            "    if (q.key === 'transactionId') { q.value = txId; }",
                            "    if (q.key === 'userId')        { q.value = userId; }",
                            "});",
                            "",
                            "const secret = pm.collectionVariables.get('secretKey') || pm.variables.get('secretKey');",
                            "if (!secret) { throw new Error('Set the secretKey collection variable first.'); }",
                            "",
                            "const signature = CryptoJS.HmacSHA256(userId + ':' + txId + ':' + amount, secret)",
                            "    .toString(CryptoJS.enc.Hex);",
                            "pm.variables.set('postbackSignature', signature);"
                        ]
                    }
                }
            ],
            "item": [
                {
                    "name": "Conversion — credited",
                    "request": {
                        "method": "GET",
                        "auth": {
                            "type": "noauth"
                        },
                        "header": [],
                        "url": {
                            "raw": "{{postbackUrl}}",
                            "host": [
                                "{{postbackUrl}}"
                            ],
                            "query": [
                                {
                                    "key": "userId",
                                    "value": "{{userId}}"
                                },
                                {
                                    "key": "transactionId",
                                    "value": "{{$guid}}"
                                },
                                {
                                    "key": "offerId",
                                    "value": "32-21022-15575424"
                                },
                                {
                                    "key": "offerName",
                                    "value": "World of Sea Battle"
                                },
                                {
                                    "key": "goalId",
                                    "value": ""
                                },
                                {
                                    "key": "currencyAmount",
                                    "value": "1750"
                                },
                                {
                                    "key": "currencyName",
                                    "value": "Gems"
                                },
                                {
                                    "key": "payoutUsd",
                                    "value": "1.750000"
                                },
                                {
                                    "key": "status",
                                    "value": "credited"
                                },
                                {
                                    "key": "test",
                                    "value": "1"
                                },
                                {
                                    "key": "timestamp",
                                    "value": "{{$timestamp}}"
                                },
                                {
                                    "key": "signature",
                                    "value": "{{postbackSignature}}"
                                }
                            ]
                        }
                    },
                    "response": []
                },
                {
                    "name": "Conversion — reversed (chargeback)",
                    "request": {
                        "method": "GET",
                        "auth": {
                            "type": "noauth"
                        },
                        "header": [],
                        "url": {
                            "raw": "{{postbackUrl}}",
                            "host": [
                                "{{postbackUrl}}"
                            ],
                            "query": [
                                {
                                    "key": "userId",
                                    "value": "{{userId}}"
                                },
                                {
                                    "key": "transactionId",
                                    "value": "{{$guid}}"
                                },
                                {
                                    "key": "offerId",
                                    "value": "32-21022-15575424"
                                },
                                {
                                    "key": "offerName",
                                    "value": "World of Sea Battle"
                                },
                                {
                                    "key": "goalId",
                                    "value": ""
                                },
                                {
                                    "key": "currencyAmount",
                                    "value": "-1750"
                                },
                                {
                                    "key": "currencyName",
                                    "value": "Gems"
                                },
                                {
                                    "key": "payoutUsd",
                                    "value": "-1.750000"
                                },
                                {
                                    "key": "status",
                                    "value": "reversed"
                                },
                                {
                                    "key": "test",
                                    "value": "1"
                                },
                                {
                                    "key": "timestamp",
                                    "value": "{{$timestamp}}"
                                },
                                {
                                    "key": "signature",
                                    "value": "{{postbackSignature}}"
                                }
                            ]
                        }
                    },
                    "response": []
                }
            ]
        }
    ]
}