{"_id":"57feb975144b7e2d00e36801","parentDoc":null,"project":"571f5e8cd8667f0e00a3c498","user":"5720c075db52d01700f5d1e4","category":{"_id":"571f7d2720695f3400f38797","__v":0,"project":"571f5e8cd8667f0e00a3c498","version":"571f5e8cd8667f0e00a3c49b","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2016-04-26T14:37:27.487Z","from_sync":false,"order":3,"slug":"session-api","title":"Session-API"},"version":{"_id":"571f5e8cd8667f0e00a3c49b","hasDoc":true,"__v":12,"hasReference":true,"project":"571f5e8cd8667f0e00a3c498","createdAt":"2016-04-26T12:26:52.312Z","releaseDate":"2016-04-26T12:26:52.312Z","categories":["571f5e8cd8667f0e00a3c49c","571f73cfcb4baa0e00d13a80","571f7451cb4baa0e00d13a88","571f7d2720695f3400f38797","571f7fb0ac2a080e0014c661","571f884be54f2d0e003ebb0a","572200c9ecb38d0e00d80ebd","572c301e7c8eff0e00aaa174","57df91b2c6348d0e0020c452","57e104db9ff1e21900a721ab","57fd04caeaa77f19008b8202","5899c7113514ce0f0014da84"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"__v":1,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-10-12T22:30:13.717Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":true,"order":2,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Purpose\"\n}\n[/block]\nWith the Session-API you can store collected data into a session and use it to prepopulate your donation form or to process this session with the Payment-API. The sent values are immediately validated, so you can show errors to your user.\n\nThe Session-API is qualified for implementing custom apps with an own payment/donation step (e.g. a charity shop or a mobile donation app).\n\nSee [app/createSession](doc:appcreatesession) and [app/updateSession](doc:appupdatesession) for further informations.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Form-API\",\n  \"body\": \"We also provide a [Javascript-jQuery-Plugin](doc:form-api) for easy implementation on your website.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"1. Form Prepopulation\"\n}\n[/block]\nThe Session-API allows a severside form data prepopulation. You submit form data before the form itself is loaded. In contrast to the simple Form-Prepopulation-API the data is not exposed to the public. For that reason you can also transfer non-public values like primary keys or complete data structure like shop baskets.\nAnother great advantage is that submitted values do not have any GET request size restriction, because you can POST the values to this endpoint.\n\nAppend the session hash of the JSON-result to your form url as GET-parameter.\nAll the values which you transferred to the session are then automatically prepopulated to the form.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"http://www.mynonprofit.com/donation?fbSessionHash=abc12345\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"For prepopulation it's **not** required that the session has the status \\\"complete\\\".\",\n  \"title\": \"Incomplete session are ok\"\n}\n[/block]\n##Errors\nSo the sent values are immediately validated, there can be errors on these. You have to consider and handle the \"current_fields\" error. For example if you submit an invalid email-address this value won't be stored in the session and you should show the error to your user.\n\n##Non editable prepopulation\nEvery value can be fixed, so the user cannot change or delete the value in the iframe payment form. Just add a \"_fix\" to the fieldname. \nFor example: *payment[amount_fix]=12.34*\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"2. Process with Payment-API\"\n}\n[/block]\nYou can build up a session with a multi-step-form and process it with the [Payment-API](doc:payment-api). In this case the session has to be complete.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Authentication\"\n}\n[/block]\nYou just have to provide the hash of your form, there is no secret authentication, because the donation form is a public part of your website. You can find the hash of your form in the settings of your form in your FundraisingBox.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/41433c2-FundraisingBox-FormAPI-FormHash.png\",\n        \"FundraisingBox-FormAPI-FormHash.png\",\n        463,\n        173,\n        \"#eaeff4\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Errors\"\n}\n[/block]\nOn a successful API-request you get a JSON with HTTP status 200. Even if there are e.g. current_fields_errors on your session or the payment_status is \"error\", it was a successful request and it returns a JSON with status \"success\".\n\nOnly if there is an error preventing the API from working you get a JSON with status \"error\" and the corresponding HTTP error code, 400, 404 or 500.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"status\\\": \\\"error\\\",\\n  \\\"error\\\": \\\"error 105: no hash\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n**Possible errors:**\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Error\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"error 101: general error\\nerror 900: general error\",\n    \"0-1\": \"something went wrong, please contact our support\",\n    \"1-0\": \"error 102: not owner\",\n    \"2-0\": \"error 103: inactive\",\n    \"3-0\": \"error 104: not api owner\",\n    \"4-0\": \"error 105: no hash\",\n    \"5-0\": \"error 106: no config\",\n    \"6-0\": \"error 202: session processed\",\n    \"10-0\": \"error 404: server error\\nerror 500: server error\",\n    \"11-0\": \"maintenance: *...translated maintenance message...*\",\n    \"1-1\": \"you are not allowed to use forms\",\n    \"2-1\": \"the selected form is inactive\",\n    \"3-1\": \"you are not allowed to use the form api\",\n    \"4-1\": \"form hash is missing\",\n    \"5-1\": \"no form has been found for the given hash\",\n    \"6-1\": \"processed sessions cannot be read or updated\",\n    \"10-1\": \"something is wrong with the server\",\n    \"11-1\": \"the FundraisingBox is currently in maintenance mode\",\n    \"7-0\": \"error 203: session not found\",\n    \"7-1\": \"wrong or no session hash at updateSession\",\n    \"8-0\": \"error 204: session exists already\",\n    \"8-1\": \"hash of existing session used for createSession\",\n    \"9-0\": \"error 205: new session requires values\",\n    \"9-1\": \"you have to submit some values for createSession\"\n  },\n  \"cols\": 2,\n  \"rows\": 12\n}\n[/block]","excerpt":"Session-API","slug":"session-api-introduction","type":"basic","title":"Introduction"}

Introduction

Session-API

[block:api-header] { "type": "basic", "title": "Purpose" } [/block] With the Session-API you can store collected data into a session and use it to prepopulate your donation form or to process this session with the Payment-API. The sent values are immediately validated, so you can show errors to your user. The Session-API is qualified for implementing custom apps with an own payment/donation step (e.g. a charity shop or a mobile donation app). See [app/createSession](doc:appcreatesession) and [app/updateSession](doc:appupdatesession) for further informations. [block:callout] { "type": "info", "title": "Form-API", "body": "We also provide a [Javascript-jQuery-Plugin](doc:form-api) for easy implementation on your website." } [/block] [block:api-header] { "type": "basic", "title": "1. Form Prepopulation" } [/block] The Session-API allows a severside form data prepopulation. You submit form data before the form itself is loaded. In contrast to the simple Form-Prepopulation-API the data is not exposed to the public. For that reason you can also transfer non-public values like primary keys or complete data structure like shop baskets. Another great advantage is that submitted values do not have any GET request size restriction, because you can POST the values to this endpoint. Append the session hash of the JSON-result to your form url as GET-parameter. All the values which you transferred to the session are then automatically prepopulated to the form. [block:code] { "codes": [ { "code": "http://www.mynonprofit.com/donation?fbSessionHash=abc12345", "language": "text" } ] } [/block] [block:callout] { "type": "info", "body": "For prepopulation it's **not** required that the session has the status \"complete\".", "title": "Incomplete session are ok" } [/block] ##Errors So the sent values are immediately validated, there can be errors on these. You have to consider and handle the "current_fields" error. For example if you submit an invalid email-address this value won't be stored in the session and you should show the error to your user. ##Non editable prepopulation Every value can be fixed, so the user cannot change or delete the value in the iframe payment form. Just add a "_fix" to the fieldname. For example: *payment[amount_fix]=12.34* [block:api-header] { "type": "basic", "title": "2. Process with Payment-API" } [/block] You can build up a session with a multi-step-form and process it with the [Payment-API](doc:payment-api). In this case the session has to be complete. [block:api-header] { "type": "basic", "title": "Authentication" } [/block] You just have to provide the hash of your form, there is no secret authentication, because the donation form is a public part of your website. You can find the hash of your form in the settings of your form in your FundraisingBox. [block:image] { "images": [ { "image": [ "https://files.readme.io/41433c2-FundraisingBox-FormAPI-FormHash.png", "FundraisingBox-FormAPI-FormHash.png", 463, 173, "#eaeff4" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "Errors" } [/block] On a successful API-request you get a JSON with HTTP status 200. Even if there are e.g. current_fields_errors on your session or the payment_status is "error", it was a successful request and it returns a JSON with status "success". Only if there is an error preventing the API from working you get a JSON with status "error" and the corresponding HTTP error code, 400, 404 or 500. [block:code] { "codes": [ { "code": "{\n \"status\": \"error\",\n \"error\": \"error 105: no hash\"\n}", "language": "json" } ] } [/block] **Possible errors:** [block:parameters] { "data": { "h-0": "Error", "h-1": "Description", "0-0": "error 101: general error\nerror 900: general error", "0-1": "something went wrong, please contact our support", "1-0": "error 102: not owner", "2-0": "error 103: inactive", "3-0": "error 104: not api owner", "4-0": "error 105: no hash", "5-0": "error 106: no config", "6-0": "error 202: session processed", "10-0": "error 404: server error\nerror 500: server error", "11-0": "maintenance: *...translated maintenance message...*", "1-1": "you are not allowed to use forms", "2-1": "the selected form is inactive", "3-1": "you are not allowed to use the form api", "4-1": "form hash is missing", "5-1": "no form has been found for the given hash", "6-1": "processed sessions cannot be read or updated", "10-1": "something is wrong with the server", "11-1": "the FundraisingBox is currently in maintenance mode", "7-0": "error 203: session not found", "7-1": "wrong or no session hash at updateSession", "8-0": "error 204: session exists already", "8-1": "hash of existing session used for createSession", "9-0": "error 205: new session requires values", "9-1": "you have to submit some values for createSession" }, "cols": 2, "rows": 12 } [/block]