{"_id":"56b36ff3ce8e5a1700f7c3e0","parentDoc":null,"project":"542998547a6b69080076806e","version":{"_id":"542998547a6b690800768071","__v":9,"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"},"category":{"_id":"54d309955616470d0013cc55","pages":["54d309f42ce0e00d00751632","56b36ff3ce8e5a1700f7c3e0"],"__v":2,"project":"542998547a6b69080076806e","version":"542998547a6b690800768071","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-02-05T06:11:33.180Z","from_sync":false,"order":9999,"slug":"api-access","title":"API Access"},"user":"542998207a6b690800768069","__v":30,"updates":["56e1f930c97d070e009f4967","570534668c69510e00b1e187","57069fecb3521b0e0029416e","5706dbd2b2943d0e00085b6f","57740cb76262f90e003145c2","5786ce1c021efa0e00ebb744","5797d50d946a240e00ad0073"],"next":{"pages":[],"description":""},"createdAt":"2016-02-04T15:36:19.147Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"The SuperRewards PayPage is the most flexible product we've ever designed, giving you a simple payment UX for any virtual good or virtual currency bundle in your app.  \n\nThe simple API lets you define the product at run-time, instead of defining the product price and attributes in advance, so you can rapidly add and change the currency bundles, items, and power-ups that you're promoting to users, without ever logging into our system to do it.\n\nUsers will see a clean payment page that includes your product description and image, and allows them to pay using our long list of global methods, creating the highest conversion rates and capturing the most value for you.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Example Flow\"\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ZDN40yZNS5ygdTRZGY8w_PayPage%20Example.png\",\n        \"PayPage Example.png\",\n        \"1301\",\n        \"825\",\n        \"#235789\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Use Cases\"\n}\n[/block]\nThere are three main ways to link to the PayPage, based on your use case:\n* **Virtual Good**: You provide a name, description, image, product code, and price for the item, we allow the user to complete the purchase, and notify you using the product code so you can grant it to the user.\n* **Virtual Currency: All Price Points**: _UNSUPPORTED IN v1_ Our other payment widgets show the user a list of virtual currency price points that you define in our system, based on your exchange rate and discount schedule.  In this use case, we allow the user to select the currency bundle, complete the purchase, and notify you how many coins or diamonds to credit them. \n* **Virtual Currency: Known Price Point**: If you want to link directly to a virtual currency purchase bundle, like a promotion for a $5.00 price point, you can do so by passing the currency name, quantity, price, image, and description, and we'll notify you of the purchased currency, quantity and earnings so you can credit them.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Linking to PayPage\"\n}\n[/block]\nFields are passed to PayPage in a JSON object, encoded and signed using JWT.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"What is JWT?\",\n  \"body\": \"We use JWT as a simple, standards-based way to sign the requests.  Signing is important, as it ensures any users who may try to get more than they pay for are unable to modify the details of the product or the price during the session.\\n\\nThe [jwt.io project site](http://jwt.io) has a live encoder and debugger, and libraries for every language.  Check it out, and hit us up with any questions!\\n\\n**We recommend building the JWT payload on the server-side, so that your key is never exposed in your client-side code.**\"\n}\n[/block]\nFor example, to have PayPage show a $10 sword:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"h\\\": \\\"mdgprxkqigh.022997899048\\\",\\n  \\\"uid\\\": \\\"123456789\\\",\\n  \\\"action\\\": \\\"paypage\\\",\\n  \\\"timestamp\\\": 1459958191,\\n  \\\"product\\\": {\\n    \\\"title\\\": \\\"Sword of Smiting\\\",\\n    \\\"description\\\": \\\"The shining-est sword in the realm\\\",\\n    \\\"image\\\": \\\"https://cdn.mygame.com/assets/virtual_goods/sword100.png\\\",\\n    \\\"product_code\\\": \\\"sword_smite\\\",\\n    \\\"price\\\": [\\n      {\\\"amount\\\": 10.00, \\\"currency\\\": \\\"USD\\\"}\\n    ]\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nPassed through the JWT encoder, using your app's `secret key` from our system as the JWT secret, you get:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJoIjoibWRncHJ4a3FpZ2guMDIyOTk3ODk5MDQ4IiwidWlkIjoiMTIzNDU2Nzg5IiwiYWN0aW9uIjoicGF5cGFnZSIsInRpbWVzdGFtcCI6MTQ1OTk1ODE5MSwicHJvZHVjdCI6eyJ0aXRsZSI6IlN3b3JkIG9mIFNtaXRpbmciLCJkZXNjcmlwdGlvbiI6IlRoZSBzaGluaW5nLWVzdCBzd29yZCBpbiB0aGUgcmVhbG0iLCJpbWFnZSI6Imh0dHBzOi8vY2RuLm15Z2FtZS5jb20vYXNzZXRzL3ZpcnR1YWxfZ29vZHMvc3dvcmQxMDAucG5nIiwicHJvZHVjdF9jb2RlIjoic3dvcmRfc21pdGUiLCJwcmljZSI6W3siYW1vdW50IjoxMCwiY3VycmVuY3kiOiJVU0QifV19fQ.qQGEsLMqr3RyPU1-xxurXiMw9HoFzGv8PleW1UbmcYI\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nThat encoded value should be passed to our PayPage endpoint, passing the `action` and `app hash` again so we can identify the web hits well:\nhttps://wall.superrewards.com/payments?action=paypage&h=mdgprxkqigh.022997899048&uid=123456&data=<encoded string>\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Required Fields (All Use Cases)\"\n}\n[/block]\nThe first two fields in the example above are the `app hash` and `uid`.  Your `app hash` is unique to your app, and is available once your app is created in our [Publisher Dashboard](https://pub.superrewards.com).  \n\nThe use of the `app hash` and `uid` are the same across all of our products, and you can read more here: [Foundation: Hashes and Keys](doc:foundation-app-hashes-keys-and-signing)  and [Notes on UIDs](doc:notes-on-uids) \n\nThe `timestamp` field is required. JWTs are valid by default for one hour after their creation, in order to prevent abuse and re-use. This period can be changed with an optional `expirySeconds` field if needed.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"h\\\": \\\"mdgprxkqigh.022997899048\\\",\\n  \\\"uid\\\": \\\"123456789\\\",\\n  \\\"action\\\": \\\"paypage\\\",\\n  \\\"timestamp\\\": 1459958191,\\n  \\\"expirySeconds\\\": 7200,\\n  \\\"product\\\": {\\n    \\\"title\\\": \\\"Sword of Smiting\\\",\\n    \\\"description\\\": \\\"The shining-est sword in the realm\\\",\\n    \\\"image\\\": \\\"https://cdn.mygame.com/assets/virtual_goods/sword100.png\\\",\\n    \\\"product_code\\\": \\\"sword_smite\\\",\\n    \\\"price\\\": [\\n      {\\\"amount\\\": 10.00, \\\"currency\\\": \\\"USD\\\"}\\n    ]\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThe `action: paypage` field is mandatory, and identifies this full page layout of the payment page.  In the future we will support other layouts and uses, as we do with some of our other products.\n\nEvery use case below requires a `product` entity in the JSON, with fields for:\n* `product_code`: a unique identifier for this virtual item or virtual currency\n* `title`: a title to display\n* `description`: a brief description for the user\n* `image`: URL of an image to display _please use HTTPS!_\n* `price`: an array of currency/amount values as described below\n**The only required fields here are `product_code` and `price`**, although the user experience is much better with a `title`, `description` and `image`. We will default to the app's name if a title is not provided (eg. \"Mafia Game: $5.99\")\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"About `product_code`\",\n  \"body\": \"**For virtual goods**, `product_code` must be set to a unique identifier for the item, as that is what we will use to notify you that it has been purchased.  For example, if you pass in `gold_sword`, you will get back a Notification Postback alerting you that user 12345 purchased a `gold_sword`.  If you use the same `product_code` for multiple items, you will not know what they purchased.\\n\\n**For virtual currency**, `product_code` should be unique to the currency, NOT the quantity.  For example, if your currency is GameBux, and you set `product_code` to `game_bux`, we will send Notification Postbacks like so:\\n`/postback?uid=12345&new=100&product_code=game_bux`\\n`/postback?uid=12345&new=5000&product_code=game_bux`\\nIncluding both the common currency identifier and the quantity that they purchased.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Image URLs and HTTPS\",\n  \"body\": \"PayPage is displayed as a full browser page to the user, so it's important that they see the green security indicators in their window.  For that reason, we ensure that all of the images and assets on the page are served over HTTPS, and if the product image you include in your JWT data block is not secure, we will show a placeholder instead.  \\n\\nIf you don't see your image, check that the URL begins with https://\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Pricing (All Use Cases)\"\n}\n[/block]\nThere are three approaches to pricing your virtual goods or currency, depending on how much detailed control you'd like to have.\n\n**Dynamic Currency Prices**\nThe simple approach is shown in the example above, you list a single price for the item.  In this case, SuperRewards will translate the price to the appropriate currency for the user's location (for example, a Canadian user seeing that USD$10.00 sword would instead see it priced at CAD$13.80).\n\n**Fixed Currency Prices**\nThe second approach is very similar, and you only pass in one price for the item.\nHowever, some apps prefer to show all prices in one common currency, so the Canadian user would also see the sword priced at USD$10.00.  You can do this by setting the `disableCurrencyConversion` option:\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Minimum Purchase Amount\",\n  \"body\": \"PayPage currently supports purchases only for amounts of $0.99 USD or greater.\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"h\\\": \\\"mdgprxkqigh.022997899048\\\",\\n  \\\"uid\\\": \\\"123456789\\\",\\n  \\\"action\\\": \\\"paypage\\\",\\n  \\\"options\\\": {\\n    \\\"disableCurrencyConversion\\\": true\\n  },\\n  \\\"timestamp\\\": 1459958191,\\n  \\\"product\\\": {\\n    \\\"title\\\": \\\"Sword of Smiting\\\",\\n    \\\"description\\\": \\\"The shining-est sword in the realm\\\",\\n    \\\"image\\\": \\\"https://cdn.mygame.com/assets/virtual_goods/sword100.png\\\",\\n    \\\"product_code\\\": \\\"sword_smite\\\",\\n    \\\"price\\\": [\\n      {\\\"amount\\\": 10.00, \\\"currency\\\": \\\"USD\\\"}\\n    ]\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"disableCurrencyConversion example\"\n    }\n  ]\n}\n[/block]\n**Custom Currency Prices**\nOne issue with Dynamic Currency Prices (where we convert automatically) is that it can result in odd prices, like the $13.80 sword.  To show location-appropriate prices, but still set nice looking amounts, you can specify extra currency prices in the JSON.  Any locations that don't match will still be priced dynamically by us, based on the first one in the list.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"h\\\": \\\"mdgprxkqigh.022997899048\\\",\\n  \\\"uid\\\": \\\"123456789\\\",\\n  \\\"action\\\": \\\"paypage\\\",\\n  \\\"timestamp\\\": 1459958191,\\n  \\\"product\\\": {\\n    \\\"title\\\": \\\"Sword of Smiting\\\",\\n    \\\"description\\\": \\\"The shining-est sword in the realm\\\",\\n    \\\"image\\\": \\\"https://cdn.mygame.com/assets/virtual_goods/sword100.png\\\",\\n    \\\"product_code\\\": \\\"sword_smite\\\",\\n    \\\"price\\\": [\\n      {\\\"amount\\\": 9.99, \\\"currency\\\": \\\"USD\\\"},\\n      {\\\"amount\\\": 12.99, \\\"currency\\\": \\\"CAD\\\"},\\n      {\\\"amount\\\": 6.99, \\\"currency\\\": \\\"GBP\\\"}\\n    ]\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Custom Currency Pricing Example\"\n    }\n  ]\n}\n[/block]\nIn this example, an American user will see the sword at US$9.99, a Canadian user at C$12.99, and a British user at £6.99.\nUsers from other locations will be shown an automatic currency conversion based on the first price (USD).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Selling a Virtual Good\"\n}\n[/block]\nThis is as shown in the examples, and there are no extra required fields.  Quantities are not permitted (see the section below on Virtual Currency selling to see why), but you can describe and name the product as a package.  \n\nFor example you can name the product \"300 Diamonds\" and give it a product code \"diamonds-300\" but you will get a single postback for the purchase of that product.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Selling Virtual Currency\"\n}\n[/block]\nIn order to avoid conflict with apps who also use our other payment and offer products, PayPage makes it optional to know about the quantity of currency.\n\nIf the currency you're selling is also the main currency you configured when you set up your app with us, you can pass a `quantity` field, and the Notification Postback will include that for compatibility.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Including the quantity field\",\n  \"body\": \"ANY TIME you include the quantity field, regardless of the product code, our system will assume you are selling your primary virtual currency, and will send the postback with `new` and `total` set appropriately.\\n\\nIf you do not include this field, PayPage transactions will be reported with `0` virtual currency sold in your publisher dashboard. If you are selling virtual currency packages using PayPage, it is important to include the quantity field!\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"h\\\": \\\"mdgprxkqigh.022997899048\\\",\\n  \\\"uid\\\": \\\"123456789\\\",\\n  \\\"action\\\": \\\"paypage\\\",\\n  \\\"timestamp\\\": 1459958191,\\n  \\\"product\\\": {\\n    \\\"title\\\": \\\"20 GameBux\\\",\\n    \\\"description\\\": \\\"20 GameBux, a 10% discount!\\\",\\n    \\\"image\\\": \\\"https://cdn.mygame.com/assets/currency/gamebux_icon.png\\\",\\n    \\\"product_code\\\": \\\"gamebux-20\\\",\\n    \\\"quantity\\\": 20,\\n    \\\"price\\\": [\\n      {\\\"amount\\\": 1.99, \\\"currency\\\": \\\"USD\\\"}\\n    ]\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Sell 20 GameBux\"\n    }\n  ]\n}\n[/block]\nThis way you can define custom currency bundles, at the discount levels you choose, and at attractive total prices.\nWhen you receive a postback with the code `gamebux-20` you will know to credit the user with 20 units of currency.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Optional Parameters\"\n}\n[/block]\nYou may specify optional parameters in the `options` field, in order to change some behaviours and default settings.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"h\\\": \\\"mdgprxkqigh.022997899048\\\",\\n  \\\"uid\\\": \\\"123456789\\\",\\n  \\\"action\\\": \\\"paypage\\\",\\n  \\\"options\\\": {\\n    \\\"disableCurrencyConversion\\\": true,\\n    \\\"redirectUrl\\\" : \\\"https://www.mygame.com\\\"\\n  },\\n  \\\"timestamp\\\": 1459958191,\\n  \\\"product\\\": {\\n    \\\"title\\\": \\\"20 GameBux\\\",\\n    \\\"description\\\": \\\"20 GameBux, a 10% discount!\\\",\\n    \\\"image\\\": \\\"https://cdn.mygame.com/assets/currency/gamebux_icon.png\\\",\\n    \\\"product_code\\\": \\\"gamebux-20\\\",\\n    \\\"price\\\": [\\n      {\\\"amount\\\": 1.99, \\\"currency\\\": \\\"USD\\\"}\\n    ]\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Option\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Default Value\",\n    \"0-0\": \"disableCurrencyConversion\",\n    \"0-1\": \"boolean\",\n    \"0-2\": \"false\",\n    \"h-3\": \"Example\",\n    \"0-3\": \"true\",\n    \"h-4\": \"Description\",\n    \"0-4\": \"if set to true, disables conversion to local currency when not specified in the `price` array\",\n    \"1-0\": \"redirectUrl\",\n    \"1-1\": \"string\",\n    \"1-2\": \"null\",\n    \"1-3\": \"https://www.mygame.com\",\n    \"1-4\": \"If set, the user will be redirected to this URL five seconds after our system detects a payment completion.\"\n  },\n  \"cols\": 5,\n  \"rows\": 2\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Receiving Notifications\"\n}\n[/block]\nFirst, read the documentation on our standard postback system in [Notification Postbacks](doc:notification-postbacks), and check out [Sample Postback Code](doc:sample-postback-code).\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Do I need a new postback script or URL?\",\n  \"body\": \"The PayPage system does not break our normal postback format, but adds some fields that you will need to handle if you are using PayPage.\\n\\nOnly one postback URL can be set for your app, so if you intend to use both our standard offer and payment wall products, and PayPage, please update your postback script to handle the extra fields and logic described below.\"\n}\n[/block]\nRegardless of the options you used to open PayPage above, you will receive a Notification Postback that includes our standard fields from [Notification Postbacks](doc:notification-postbacks), and these:\n* `product_code`\n* `payout`\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Because PayPage allows purchases of items besides currency, the `new` field may be 0. When using PayPage, we will build the `sig` field based on `product_code` rather than `new`. Please ensure that your postback script verifies the `sig` field using `product_code` rather than `new`. See our [Notification Postbacks](doc:notification-postbacks) documentation for more details.\",\n  \"title\": \"Empty `new` field?\"\n}\n[/block]\nFor example, a $1.99 USD purchase of 20 GameBux will result in:\n`https://myapp.com/superrewards?id=165274242&total=200&new=0&uid=1234567&oid=112233&payout=1.99&product_code=gamebux-20&sig=70a5998fcc292366e97ca10a1b6fc4a2`\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://myapp.com/superrewards\\t\\t\\t\\t// Postback URL defined in Dashboard\\n?id=165274242\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t// Transaction ID\\n&total=200\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t// Currency to date for user (legacy)\\n&new=0\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t// Currency this txn for user (legacy)\\n&uid=1234567\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t// User ID you sent us\\n&oid=112233\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t// Our payment method ID\\n&payout=1.99\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t// Your earnings in USD\\n&product_code=gamebux-20\\t\\t\\t\\t\\t\\t\\t// Product code purchased\\n&sig=70a5998fcc292366e97ca10a1b6fc4a2\\t// Security signature (see doc page)\",\n      \"language\": \"text\",\n      \"name\": \"Postback field breakdown\"\n    }\n  ]\n}\n[/block]","excerpt":"A payment landing page for any virtual good or virtual currency.","slug":"paypage","type":"basic","title":"PayPage"}

PayPage

A payment landing page for any virtual good or virtual currency.

The SuperRewards PayPage is the most flexible product we've ever designed, giving you a simple payment UX for any virtual good or virtual currency bundle in your app. The simple API lets you define the product at run-time, instead of defining the product price and attributes in advance, so you can rapidly add and change the currency bundles, items, and power-ups that you're promoting to users, without ever logging into our system to do it. Users will see a clean payment page that includes your product description and image, and allows them to pay using our long list of global methods, creating the highest conversion rates and capturing the most value for you. [block:api-header] { "type": "basic", "title": "Example Flow" } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/ZDN40yZNS5ygdTRZGY8w_PayPage%20Example.png", "PayPage Example.png", "1301", "825", "#235789", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "Use Cases" } [/block] There are three main ways to link to the PayPage, based on your use case: * **Virtual Good**: You provide a name, description, image, product code, and price for the item, we allow the user to complete the purchase, and notify you using the product code so you can grant it to the user. * **Virtual Currency: All Price Points**: _UNSUPPORTED IN v1_ Our other payment widgets show the user a list of virtual currency price points that you define in our system, based on your exchange rate and discount schedule. In this use case, we allow the user to select the currency bundle, complete the purchase, and notify you how many coins or diamonds to credit them. * **Virtual Currency: Known Price Point**: If you want to link directly to a virtual currency purchase bundle, like a promotion for a $5.00 price point, you can do so by passing the currency name, quantity, price, image, and description, and we'll notify you of the purchased currency, quantity and earnings so you can credit them. [block:api-header] { "type": "basic", "title": "Linking to PayPage" } [/block] Fields are passed to PayPage in a JSON object, encoded and signed using JWT. [block:callout] { "type": "success", "title": "What is JWT?", "body": "We use JWT as a simple, standards-based way to sign the requests. Signing is important, as it ensures any users who may try to get more than they pay for are unable to modify the details of the product or the price during the session.\n\nThe [jwt.io project site](http://jwt.io) has a live encoder and debugger, and libraries for every language. Check it out, and hit us up with any questions!\n\n**We recommend building the JWT payload on the server-side, so that your key is never exposed in your client-side code.**" } [/block] For example, to have PayPage show a $10 sword: [block:code] { "codes": [ { "code": "{\n \"h\": \"mdgprxkqigh.022997899048\",\n \"uid\": \"123456789\",\n \"action\": \"paypage\",\n \"timestamp\": 1459958191,\n \"product\": {\n \"title\": \"Sword of Smiting\",\n \"description\": \"The shining-est sword in the realm\",\n \"image\": \"https://cdn.mygame.com/assets/virtual_goods/sword100.png\",\n \"product_code\": \"sword_smite\",\n \"price\": [\n {\"amount\": 10.00, \"currency\": \"USD\"}\n ]\n }\n}", "language": "json" } ] } [/block] Passed through the JWT encoder, using your app's `secret key` from our system as the JWT secret, you get: [block:code] { "codes": [ { "code": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJoIjoibWRncHJ4a3FpZ2guMDIyOTk3ODk5MDQ4IiwidWlkIjoiMTIzNDU2Nzg5IiwiYWN0aW9uIjoicGF5cGFnZSIsInRpbWVzdGFtcCI6MTQ1OTk1ODE5MSwicHJvZHVjdCI6eyJ0aXRsZSI6IlN3b3JkIG9mIFNtaXRpbmciLCJkZXNjcmlwdGlvbiI6IlRoZSBzaGluaW5nLWVzdCBzd29yZCBpbiB0aGUgcmVhbG0iLCJpbWFnZSI6Imh0dHBzOi8vY2RuLm15Z2FtZS5jb20vYXNzZXRzL3ZpcnR1YWxfZ29vZHMvc3dvcmQxMDAucG5nIiwicHJvZHVjdF9jb2RlIjoic3dvcmRfc21pdGUiLCJwcmljZSI6W3siYW1vdW50IjoxMCwiY3VycmVuY3kiOiJVU0QifV19fQ.qQGEsLMqr3RyPU1-xxurXiMw9HoFzGv8PleW1UbmcYI", "language": "text" } ] } [/block] That encoded value should be passed to our PayPage endpoint, passing the `action` and `app hash` again so we can identify the web hits well: https://wall.superrewards.com/payments?action=paypage&h=mdgprxkqigh.022997899048&uid=123456&data=<encoded string> [block:api-header] { "type": "basic", "title": "Required Fields (All Use Cases)" } [/block] The first two fields in the example above are the `app hash` and `uid`. Your `app hash` is unique to your app, and is available once your app is created in our [Publisher Dashboard](https://pub.superrewards.com). The use of the `app hash` and `uid` are the same across all of our products, and you can read more here: [Foundation: Hashes and Keys](doc:foundation-app-hashes-keys-and-signing) and [Notes on UIDs](doc:notes-on-uids) The `timestamp` field is required. JWTs are valid by default for one hour after their creation, in order to prevent abuse and re-use. This period can be changed with an optional `expirySeconds` field if needed. [block:code] { "codes": [ { "code": "{\n \"h\": \"mdgprxkqigh.022997899048\",\n \"uid\": \"123456789\",\n \"action\": \"paypage\",\n \"timestamp\": 1459958191,\n \"expirySeconds\": 7200,\n \"product\": {\n \"title\": \"Sword of Smiting\",\n \"description\": \"The shining-est sword in the realm\",\n \"image\": \"https://cdn.mygame.com/assets/virtual_goods/sword100.png\",\n \"product_code\": \"sword_smite\",\n \"price\": [\n {\"amount\": 10.00, \"currency\": \"USD\"}\n ]\n }\n}", "language": "json" } ] } [/block] The `action: paypage` field is mandatory, and identifies this full page layout of the payment page. In the future we will support other layouts and uses, as we do with some of our other products. Every use case below requires a `product` entity in the JSON, with fields for: * `product_code`: a unique identifier for this virtual item or virtual currency * `title`: a title to display * `description`: a brief description for the user * `image`: URL of an image to display _please use HTTPS!_ * `price`: an array of currency/amount values as described below **The only required fields here are `product_code` and `price`**, although the user experience is much better with a `title`, `description` and `image`. We will default to the app's name if a title is not provided (eg. "Mafia Game: $5.99") [block:callout] { "type": "info", "title": "About `product_code`", "body": "**For virtual goods**, `product_code` must be set to a unique identifier for the item, as that is what we will use to notify you that it has been purchased. For example, if you pass in `gold_sword`, you will get back a Notification Postback alerting you that user 12345 purchased a `gold_sword`. If you use the same `product_code` for multiple items, you will not know what they purchased.\n\n**For virtual currency**, `product_code` should be unique to the currency, NOT the quantity. For example, if your currency is GameBux, and you set `product_code` to `game_bux`, we will send Notification Postbacks like so:\n`/postback?uid=12345&new=100&product_code=game_bux`\n`/postback?uid=12345&new=5000&product_code=game_bux`\nIncluding both the common currency identifier and the quantity that they purchased." } [/block] [block:callout] { "type": "warning", "title": "Image URLs and HTTPS", "body": "PayPage is displayed as a full browser page to the user, so it's important that they see the green security indicators in their window. For that reason, we ensure that all of the images and assets on the page are served over HTTPS, and if the product image you include in your JWT data block is not secure, we will show a placeholder instead. \n\nIf you don't see your image, check that the URL begins with https://" } [/block] [block:api-header] { "type": "basic", "title": "Pricing (All Use Cases)" } [/block] There are three approaches to pricing your virtual goods or currency, depending on how much detailed control you'd like to have. **Dynamic Currency Prices** The simple approach is shown in the example above, you list a single price for the item. In this case, SuperRewards will translate the price to the appropriate currency for the user's location (for example, a Canadian user seeing that USD$10.00 sword would instead see it priced at CAD$13.80). **Fixed Currency Prices** The second approach is very similar, and you only pass in one price for the item. However, some apps prefer to show all prices in one common currency, so the Canadian user would also see the sword priced at USD$10.00. You can do this by setting the `disableCurrencyConversion` option: [block:callout] { "type": "info", "title": "Minimum Purchase Amount", "body": "PayPage currently supports purchases only for amounts of $0.99 USD or greater." } [/block] [block:code] { "codes": [ { "code": "{\n \"h\": \"mdgprxkqigh.022997899048\",\n \"uid\": \"123456789\",\n \"action\": \"paypage\",\n \"options\": {\n \"disableCurrencyConversion\": true\n },\n \"timestamp\": 1459958191,\n \"product\": {\n \"title\": \"Sword of Smiting\",\n \"description\": \"The shining-est sword in the realm\",\n \"image\": \"https://cdn.mygame.com/assets/virtual_goods/sword100.png\",\n \"product_code\": \"sword_smite\",\n \"price\": [\n {\"amount\": 10.00, \"currency\": \"USD\"}\n ]\n }\n}", "language": "json", "name": "disableCurrencyConversion example" } ] } [/block] **Custom Currency Prices** One issue with Dynamic Currency Prices (where we convert automatically) is that it can result in odd prices, like the $13.80 sword. To show location-appropriate prices, but still set nice looking amounts, you can specify extra currency prices in the JSON. Any locations that don't match will still be priced dynamically by us, based on the first one in the list. [block:code] { "codes": [ { "code": "{\n \"h\": \"mdgprxkqigh.022997899048\",\n \"uid\": \"123456789\",\n \"action\": \"paypage\",\n \"timestamp\": 1459958191,\n \"product\": {\n \"title\": \"Sword of Smiting\",\n \"description\": \"The shining-est sword in the realm\",\n \"image\": \"https://cdn.mygame.com/assets/virtual_goods/sword100.png\",\n \"product_code\": \"sword_smite\",\n \"price\": [\n {\"amount\": 9.99, \"currency\": \"USD\"},\n {\"amount\": 12.99, \"currency\": \"CAD\"},\n {\"amount\": 6.99, \"currency\": \"GBP\"}\n ]\n }\n}", "language": "json", "name": "Custom Currency Pricing Example" } ] } [/block] In this example, an American user will see the sword at US$9.99, a Canadian user at C$12.99, and a British user at £6.99. Users from other locations will be shown an automatic currency conversion based on the first price (USD). [block:api-header] { "type": "basic", "title": "Selling a Virtual Good" } [/block] This is as shown in the examples, and there are no extra required fields. Quantities are not permitted (see the section below on Virtual Currency selling to see why), but you can describe and name the product as a package. For example you can name the product "300 Diamonds" and give it a product code "diamonds-300" but you will get a single postback for the purchase of that product. [block:api-header] { "type": "basic", "title": "Selling Virtual Currency" } [/block] In order to avoid conflict with apps who also use our other payment and offer products, PayPage makes it optional to know about the quantity of currency. If the currency you're selling is also the main currency you configured when you set up your app with us, you can pass a `quantity` field, and the Notification Postback will include that for compatibility. [block:callout] { "type": "warning", "title": "Including the quantity field", "body": "ANY TIME you include the quantity field, regardless of the product code, our system will assume you are selling your primary virtual currency, and will send the postback with `new` and `total` set appropriately.\n\nIf you do not include this field, PayPage transactions will be reported with `0` virtual currency sold in your publisher dashboard. If you are selling virtual currency packages using PayPage, it is important to include the quantity field!" } [/block] [block:code] { "codes": [ { "code": "{\n \"h\": \"mdgprxkqigh.022997899048\",\n \"uid\": \"123456789\",\n \"action\": \"paypage\",\n \"timestamp\": 1459958191,\n \"product\": {\n \"title\": \"20 GameBux\",\n \"description\": \"20 GameBux, a 10% discount!\",\n \"image\": \"https://cdn.mygame.com/assets/currency/gamebux_icon.png\",\n \"product_code\": \"gamebux-20\",\n \"quantity\": 20,\n \"price\": [\n {\"amount\": 1.99, \"currency\": \"USD\"}\n ]\n }\n}", "language": "json", "name": "Sell 20 GameBux" } ] } [/block] This way you can define custom currency bundles, at the discount levels you choose, and at attractive total prices. When you receive a postback with the code `gamebux-20` you will know to credit the user with 20 units of currency. [block:api-header] { "type": "basic", "title": "Optional Parameters" } [/block] You may specify optional parameters in the `options` field, in order to change some behaviours and default settings. [block:code] { "codes": [ { "code": "{\n \"h\": \"mdgprxkqigh.022997899048\",\n \"uid\": \"123456789\",\n \"action\": \"paypage\",\n \"options\": {\n \"disableCurrencyConversion\": true,\n \"redirectUrl\" : \"https://www.mygame.com\"\n },\n \"timestamp\": 1459958191,\n \"product\": {\n \"title\": \"20 GameBux\",\n \"description\": \"20 GameBux, a 10% discount!\",\n \"image\": \"https://cdn.mygame.com/assets/currency/gamebux_icon.png\",\n \"product_code\": \"gamebux-20\",\n \"price\": [\n {\"amount\": 1.99, \"currency\": \"USD\"}\n ]\n }\n}", "language": "json" } ] } [/block] [block:parameters] { "data": { "h-0": "Option", "h-1": "Type", "h-2": "Default Value", "0-0": "disableCurrencyConversion", "0-1": "boolean", "0-2": "false", "h-3": "Example", "0-3": "true", "h-4": "Description", "0-4": "if set to true, disables conversion to local currency when not specified in the `price` array", "1-0": "redirectUrl", "1-1": "string", "1-2": "null", "1-3": "https://www.mygame.com", "1-4": "If set, the user will be redirected to this URL five seconds after our system detects a payment completion." }, "cols": 5, "rows": 2 } [/block] [block:api-header] { "type": "basic", "title": "Receiving Notifications" } [/block] First, read the documentation on our standard postback system in [Notification Postbacks](doc:notification-postbacks), and check out [Sample Postback Code](doc:sample-postback-code). [block:callout] { "type": "success", "title": "Do I need a new postback script or URL?", "body": "The PayPage system does not break our normal postback format, but adds some fields that you will need to handle if you are using PayPage.\n\nOnly one postback URL can be set for your app, so if you intend to use both our standard offer and payment wall products, and PayPage, please update your postback script to handle the extra fields and logic described below." } [/block] Regardless of the options you used to open PayPage above, you will receive a Notification Postback that includes our standard fields from [Notification Postbacks](doc:notification-postbacks), and these: * `product_code` * `payout` [block:callout] { "type": "info", "body": "Because PayPage allows purchases of items besides currency, the `new` field may be 0. When using PayPage, we will build the `sig` field based on `product_code` rather than `new`. Please ensure that your postback script verifies the `sig` field using `product_code` rather than `new`. See our [Notification Postbacks](doc:notification-postbacks) documentation for more details.", "title": "Empty `new` field?" } [/block] For example, a $1.99 USD purchase of 20 GameBux will result in: `https://myapp.com/superrewards?id=165274242&total=200&new=0&uid=1234567&oid=112233&payout=1.99&product_code=gamebux-20&sig=70a5998fcc292366e97ca10a1b6fc4a2` [block:code] { "codes": [ { "code": "https://myapp.com/superrewards\t\t\t\t// Postback URL defined in Dashboard\n?id=165274242\t\t\t\t\t\t\t\t\t\t\t\t\t// Transaction ID\n&total=200\t\t\t\t\t\t\t\t\t\t\t\t\t\t// Currency to date for user (legacy)\n&new=0\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t// Currency this txn for user (legacy)\n&uid=1234567\t\t\t\t\t\t\t\t\t\t\t\t\t// User ID you sent us\n&oid=112233\t\t\t\t\t\t\t\t\t\t\t\t\t\t// Our payment method ID\n&payout=1.99\t\t\t\t\t\t\t\t\t\t\t\t\t// Your earnings in USD\n&product_code=gamebux-20\t\t\t\t\t\t\t// Product code purchased\n&sig=70a5998fcc292366e97ca10a1b6fc4a2\t// Security signature (see doc page)", "language": "text", "name": "Postback field breakdown" } ] } [/block]