{"__v":23,"_id":"54333089b7eae9080053eb05","category":{"__v":22,"_id":"542998547a6b690800768072","pages":["542a3de5e677b0080050898f","544e8298de6bac1000236fe9","542998547a6b690800768074","542ab90154d88d140075fbd4","5433300867f20a080097a04b","5433302067f20a080097a04d","544e7ae6de6bac1000236fb5","54330b4990d63b1c0030c129","543da24b31ca981a00a6ffe7","54333238a807e208003e72d2","544e8305bd51b9080037f9cb","54332b234aeeef0800410a73","5433306067f20a080097a051","543db19f31ca981a00a70053","543d31d6a10ab32000b3aa70","54a1f0af50465f1f00bfa3e8","54cfc5925ff7e617002bbda5","54f4f09158e9df0d00917b3e"],"project":"542998547a6b69080076806e","version":"542998547a6b690800768071","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-09-29T17:35:16.267Z","from_sync":false,"order":0,"slug":"getting-started","title":"Getting Started"},"is_link":false,"parentDoc":null,"project":"542998547a6b69080076806e","user":"542998207a6b690800768069","version":{"__v":9,"_id":"542998547a6b690800768071","project":"542998547a6b69080076806e","createdAt":"2014-09-29T17:35:16.249Z","releaseDate":"2014-09-29T17:35:16.249Z","categories":["542998547a6b690800768072","5433027990d63b1c0030c0f1","5433028190d63b1c0030c0f2","5433028d9a2b451a00ad4508","5433055790d63b1c0030c10a","5461417d37e5bc200049e1e4","54624066ddd31b0800a58db4","54625de66d1f1010002f3901","54d309955616470d0013cc55"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":["5706a109b2943d0e00085af6","5781179d6a18cd0e00db01ac"],"next":{"pages":[],"description":""},"createdAt":"2014-10-07T00:15:05.203Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"basic_auth":false,"results":{"codes":[]},"try":true,"auth":"never","params":[],"url":""},"isReference":false,"order":6,"body":"After every successful user transaction, whether it is a payment or an [offer lead](doc:basics-how-offers-work), our system will post a notification to your system, so that you can take the right actions and credit your users.\n\nBelow we describe what information to expect, and how your script or app should respond.\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"Notification postbacks are one of the most critical parts of integrating with us, so if you run into trouble please contact us at [info:::at:::superrewards.com](mailto:info@superrewards.com).\",\n  \"title\": \"Key Process\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"How about a sample?\",\n  \"body\": \"You can see two working examples of PHP postback scripts on our GitHub: [superrewards-postback](https://github.com/Playerize/superrewards-postback).\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Setup\"\n}\n[/block]\nYour *Postback URL* is set in your [Dashboard](https://pub.superrewards.com/login), in the settings for each app.  \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/gg268XqQUyB3RZeBQX7S_Screenshot%201:12:15,%2010:00%20AM.png\",\n        \"Screenshot 1:12:15, 10:00 AM.png\",\n        \"734\",\n        \"218\",\n        \"#5c88a0\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\nIn order to be able to receive these postbacks, you will need the `secret key` displayed in the app settings as well.  This key is different for every app, so if you have more than one app, make sure you're using the correct key.\n\nFor example: \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/tko6C0i8SBiAuNlGzxAN_Screenshot%201:12:15,%2010:02%20AM.png\",\n        \"Screenshot 1:12:15, 10:02 AM.png\",\n        \"738\",\n        \"156\",\n        \"#5c88bf\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Security\"\n}\n[/block]\nOur postbacks to you are signed using your app's `secret key`, which you can find in your [Dashboard](https://pub.superrewards.com/login).  Details of the signing are below.  If you test the signing properly, it will be impossible for any fake postbacks to be sent to your system.\n\nWe *highly* recommend that you only accept postbacks from our server IPs.  Currently the only valid IP addresses that should hit your script are:\n* 54.85.0.76\n* 54.84.205.80\n* 54.84.27.163\n\nIt is recommended that you use a SSL-secured (HTTPS) URL for your Postback URL, to ensure that it cannot be intercepted between our servers and yours.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Fields and Formats\"\n}\n[/block]\nPostbacks are sent from our server to yours using a HTTP GET request with these fields in the query string:\n\n* `id`: the ID of this transaction, unique to this user event.\n* `uid`: the ID of the user, that you passed us at the beginning of their session.\n* `oid`: the numeric ID of the offer or payment method that they used.\n* `new`: total number of new in-game currency that the user has earned by completing this event.  This amount is calculated based on the [VC Ratio](TODO) that you set for this app.\n* `total`: total number of in-game currency that this user has earned on this app.\n* `sig`: the security hash that proves that this postback comes from us.\n\nUse your app's `secret key` to calculate a matching security hash (MD5) with the method here, and compare it to the value we sent in `sig`.  They should match, if they do not match you should ignore this postback.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"sig = md5(id:new:uid:SECRET_KEY)\",\n      \"language\": \"text\",\n      \"name\": \"Pseudocode\"\n    },\n    {\n      \"code\": \"$sig = md5($_REQUEST['id'].':'.$_REQUEST['new'].':'.$_REQUEST['uid'].':'.$SECRET_KEY);\",\n      \"language\": \"php\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"PayPage Postbacks\",\n  \"body\": \"In many cases, postbacks generated from purchases made through PayPage will not have a `new` value, as there will be no virtual currency in the purchase. In these cases, we send a `product_code` value in the postback, which will be used to generate the postback signature instead of `new`.\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"sig = md5(id:product_code:uid:SECRET_KEY);\",\n      \"language\": \"text\",\n      \"name\": \"Pseudocode\"\n    },\n    {\n      \"code\": \"$sig = md5($_REQUEST['id'].':'.$_REQUEST['product_code'].':'.$_REQUEST['uid'].':'.$SECRET_KEY);\",\n      \"language\": \"php\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Transaction ID field\",\n  \"body\": \"`id` is unique for the user transaction, if we resend a postback it will have the same `id` value.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Custom Fields?\",\n  \"body\": \"If there are other fields you would like passed back to you, check out the [Custom Fields section of our Web Integration Options](web-integration-reference#custom)\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Response Values\"\n}\n[/block]\nOur system will retry postbacks up to 30 times if we don't get a valid response. This happens over the next 24 hours, with longer delays between each attempt.\n\nYou must tell us you've received our postback by having your script or app output a value of of 1 (Success) or 0 (Try sending again later). No tags, just a 1 byte reply.\n* 1 - If you were able to update your system successfully.\n* 0 - If there is a problem. (We'll wait and resend the postback again later)\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"if ($success) {\\n   print(\\\"1\\\\n\\\");\\n}\\nelse {\\n   print(\\\"0\\\\n\\\");\\n}\\nexit;\",\n      \"language\": \"php\"\n    }\n  ]\n}\n[/block]\nIf your web server (eg. Apache) responds with an HTTP result code other than 200, our system will consider it a failed postback and try again later.\n\nBe prepared for duplicate postbacks! In case of duplicate postbacks from us (you've already seen and handled one with the same `id` value), please respond with 1 so our system knows that you've processed it, otherwise we will continue re-sending it.\n\n**Below are other postback codes you might see under certain circumstances:** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Pending = 0;\\nSuccess = 1;\\nBad Url = 3;\\nNo AlphaUID = 4; // Could not find alpha uid conversion\\nNo Total Points = 5; // No points\\nNo App = 6; // App not found\\nNo UID = 7;\\nNo Points = 8;\\nNo Secret Key = 9;\\nResend Pending = 10;\\nResend Success = 11;\\nResend Failure = 13;\\nAmount Too High = 15;\\nBroken AlphaUid = 16;\\nMismatch SID = 17;\\nTest Completed Offer Postback = 99;\",\n      \"language\": \"text\",\n      \"name\": null\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Testing\"\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/qtqrNUetQeq1PEJcoWNY_Screenshot%201:12:15,%2010:03%20AM.png\",\n        \"Screenshot 1:12:15, 10:03 AM.png\",\n        \"577\",\n        \"451\",\n        \"#5ba34d\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nIn your [Dashboard](https://pub.superrewards.com/login) there is a Postback Test Tool (in the settings for each app) that you can use to send a test postback to your script.  The tool will report on when the postback is sent out, and what response we got from your system.\n\nOnce the postback is successfully tested, it will also give you the option to set up a [Chargeback Postback](doc:chargeback-postbacks), an important tool in fighting fraud.","excerpt":"Postbacks are absolutely critical to working with SuperRewards.","slug":"notification-postbacks","type":"basic","title":"Notification Postbacks"}

Notification Postbacks

Postbacks are absolutely critical to working with SuperRewards.

After every successful user transaction, whether it is a payment or an [offer lead](doc:basics-how-offers-work), our system will post a notification to your system, so that you can take the right actions and credit your users. Below we describe what information to expect, and how your script or app should respond. [block:callout] { "type": "danger", "body": "Notification postbacks are one of the most critical parts of integrating with us, so if you run into trouble please contact us at [info@superrewards.com](mailto:info@superrewards.com).", "title": "Key Process" } [/block] [block:callout] { "type": "success", "title": "How about a sample?", "body": "You can see two working examples of PHP postback scripts on our GitHub: [superrewards-postback](https://github.com/Playerize/superrewards-postback)." } [/block] [block:api-header] { "type": "basic", "title": "Setup" } [/block] Your *Postback URL* is set in your [Dashboard](https://pub.superrewards.com/login), in the settings for each app. [block:image] { "images": [ { "image": [ "https://files.readme.io/gg268XqQUyB3RZeBQX7S_Screenshot%201:12:15,%2010:00%20AM.png", "Screenshot 1:12:15, 10:00 AM.png", "734", "218", "#5c88a0", "" ] } ] } [/block] In order to be able to receive these postbacks, you will need the `secret key` displayed in the app settings as well. This key is different for every app, so if you have more than one app, make sure you're using the correct key. For example: [block:image] { "images": [ { "image": [ "https://files.readme.io/tko6C0i8SBiAuNlGzxAN_Screenshot%201:12:15,%2010:02%20AM.png", "Screenshot 1:12:15, 10:02 AM.png", "738", "156", "#5c88bf", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "Security" } [/block] Our postbacks to you are signed using your app's `secret key`, which you can find in your [Dashboard](https://pub.superrewards.com/login). Details of the signing are below. If you test the signing properly, it will be impossible for any fake postbacks to be sent to your system. We *highly* recommend that you only accept postbacks from our server IPs. Currently the only valid IP addresses that should hit your script are: * 54.85.0.76 * 54.84.205.80 * 54.84.27.163 It is recommended that you use a SSL-secured (HTTPS) URL for your Postback URL, to ensure that it cannot be intercepted between our servers and yours. [block:api-header] { "type": "basic", "title": "Fields and Formats" } [/block] Postbacks are sent from our server to yours using a HTTP GET request with these fields in the query string: * `id`: the ID of this transaction, unique to this user event. * `uid`: the ID of the user, that you passed us at the beginning of their session. * `oid`: the numeric ID of the offer or payment method that they used. * `new`: total number of new in-game currency that the user has earned by completing this event. This amount is calculated based on the [VC Ratio](TODO) that you set for this app. * `total`: total number of in-game currency that this user has earned on this app. * `sig`: the security hash that proves that this postback comes from us. Use your app's `secret key` to calculate a matching security hash (MD5) with the method here, and compare it to the value we sent in `sig`. They should match, if they do not match you should ignore this postback. [block:code] { "codes": [ { "code": "sig = md5(id:new:uid:SECRET_KEY)", "language": "text", "name": "Pseudocode" }, { "code": "$sig = md5($_REQUEST['id'].':'.$_REQUEST['new'].':'.$_REQUEST['uid'].':'.$SECRET_KEY);", "language": "php" } ] } [/block] [block:callout] { "type": "info", "title": "PayPage Postbacks", "body": "In many cases, postbacks generated from purchases made through PayPage will not have a `new` value, as there will be no virtual currency in the purchase. In these cases, we send a `product_code` value in the postback, which will be used to generate the postback signature instead of `new`." } [/block] [block:code] { "codes": [ { "code": "sig = md5(id:product_code:uid:SECRET_KEY);", "language": "text", "name": "Pseudocode" }, { "code": "$sig = md5($_REQUEST['id'].':'.$_REQUEST['product_code'].':'.$_REQUEST['uid'].':'.$SECRET_KEY);", "language": "php" } ] } [/block] [block:callout] { "type": "info", "title": "Transaction ID field", "body": "`id` is unique for the user transaction, if we resend a postback it will have the same `id` value." } [/block] [block:callout] { "type": "success", "title": "Custom Fields?", "body": "If there are other fields you would like passed back to you, check out the [Custom Fields section of our Web Integration Options](web-integration-reference#custom)" } [/block] [block:api-header] { "type": "basic", "title": "Response Values" } [/block] Our system will retry postbacks up to 30 times if we don't get a valid response. This happens over the next 24 hours, with longer delays between each attempt. You must tell us you've received our postback by having your script or app output a value of of 1 (Success) or 0 (Try sending again later). No tags, just a 1 byte reply. * 1 - If you were able to update your system successfully. * 0 - If there is a problem. (We'll wait and resend the postback again later) [block:code] { "codes": [ { "code": "if ($success) {\n print(\"1\\n\");\n}\nelse {\n print(\"0\\n\");\n}\nexit;", "language": "php" } ] } [/block] If your web server (eg. Apache) responds with an HTTP result code other than 200, our system will consider it a failed postback and try again later. Be prepared for duplicate postbacks! In case of duplicate postbacks from us (you've already seen and handled one with the same `id` value), please respond with 1 so our system knows that you've processed it, otherwise we will continue re-sending it. **Below are other postback codes you might see under certain circumstances:** [block:code] { "codes": [ { "code": "Pending = 0;\nSuccess = 1;\nBad Url = 3;\nNo AlphaUID = 4; // Could not find alpha uid conversion\nNo Total Points = 5; // No points\nNo App = 6; // App not found\nNo UID = 7;\nNo Points = 8;\nNo Secret Key = 9;\nResend Pending = 10;\nResend Success = 11;\nResend Failure = 13;\nAmount Too High = 15;\nBroken AlphaUid = 16;\nMismatch SID = 17;\nTest Completed Offer Postback = 99;", "language": "text", "name": null } ] } [/block] [block:api-header] { "type": "basic", "title": "Testing" } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/qtqrNUetQeq1PEJcoWNY_Screenshot%201:12:15,%2010:03%20AM.png", "Screenshot 1:12:15, 10:03 AM.png", "577", "451", "#5ba34d", "" ] } ] } [/block] In your [Dashboard](https://pub.superrewards.com/login) there is a Postback Test Tool (in the settings for each app) that you can use to send a test postback to your script. The tool will report on when the postback is sent out, and what response we got from your system. Once the postback is successfully tested, it will also give you the option to set up a [Chargeback Postback](doc:chargeback-postbacks), an important tool in fighting fraud.