{"_id":"57e0fdff8929550e00f1d9c3","__v":0,"project":"571f5e8cd8667f0e00a3c498","user":"5720c075db52d01700f5d1e4","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"},"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"},"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-09-20T09:14:39.469Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":true,"order":3,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"payment namespace\"\n}\n[/block]\nAll data, you want to store in the session, has to be set in the \"payment\"-parameter.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl https://secure.fundraisingbox.com/app/updateSession?hash={your_form_hash}&payment[amount]=12&payment[interval]=1&payment[first_name]=Beate&payment[last_name]=Beispiel&...\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Field dependancies\"\n}\n[/block]\nIf you design a multi-step-form, you have to care about some field dependancies: some fields should passed together to updateSession for a correct validation result:\n- *salutation, title, first_name, last_name*\n- *address, post_code, city, country*\n- *bank_fields, bank_account_owner, bank_account_number, bank_number, bank_iban, bank_bic, bank_confirmation*\n- *credit_card_owner, credit_card_token, credit_card_expire_date_month, credit_card_expire_date_year, credit_card_number_hidden, credit_card_secure_id_hidden*\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Special dependancies\"\n}\n[/block]\nThere can be some special dependancies between fields, which are not immediately obvious:\n- **wants_receipt**: a receipt requires the address of the donor, so there will be an error if no address is provided. We recommend to set the address as required fields in your form-settings or you should place this field together with the address-fields.\n- **wants_newsletter**: to send a newsletter the email address of the donor is required, so there will be an error if no email address is provided. We recommend to set the email address as required field or you should place this field together with the email-address-field.\n- **amount and fb_item_id**: if items have a minimum amount, you should query the item before or together with the amount.\n- **amount and payment_method**: consider the minimum and maximum amounts of your payment methods set in your extensions settings in your FundraisingBox. We recommend to set the same min/max-amounts for all payment methods.\n- **interval and payment_method**: not all payment methods are suitable for recurring payments. Please consider your [form configuration](/docs/form-configuration-json) to show or hide the available payment methods.\n- **payment_method and country**: you can restrict the payment methods to selected countries in your extension-settings. Please consider your [form configuration](/docs/form-configuration-json) to show or hide the available payment methods. We recommend to query the address (with the country) before the payment method.\n- **payment_method and bank-data**: you have to query the bank-data after or with the payment_method for correct validation.\n\n**Adresslabor-validation**\nIf you are using the Adresslabor-extension, you should place the name- and address-fields in one step.\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"IP of donation\",\n  \"body\": \"If you are **not** using Javascript (e.g. our jQuery-Plugin) to send the data, you have to provide the IP of the user (not of your server!). This is required to block spamming users/bots, **otherwise your server will be blocked!**\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Credit card fields\"\n}\n[/block]\nDue to security requirements credit card fields are handled via iframes. We strongly recommend to use our Form-API to handle these fields. See [Credit card data processing](doc:form-api-jquery-plugin-credit-card-data-processing) for further information.\n\nIf you don't use our Form-API you have to implement the Javascript of your credit card provider by yourself and send all required fields to our API.","excerpt":"","slug":"session-api-requirements-conventions","type":"basic","title":"Requirements and conventions"}

Requirements and conventions


[block:api-header] { "type": "basic", "title": "payment namespace" } [/block] All data, you want to store in the session, has to be set in the "payment"-parameter. [block:code] { "codes": [ { "code": "curl https://secure.fundraisingbox.com/app/updateSession?hash={your_form_hash}&payment[amount]=12&payment[interval]=1&payment[first_name]=Beate&payment[last_name]=Beispiel&...", "language": "curl" } ] } [/block] [block:api-header] { "type": "basic", "title": "Field dependancies" } [/block] If you design a multi-step-form, you have to care about some field dependancies: some fields should passed together to updateSession for a correct validation result: - *salutation, title, first_name, last_name* - *address, post_code, city, country* - *bank_fields, bank_account_owner, bank_account_number, bank_number, bank_iban, bank_bic, bank_confirmation* - *credit_card_owner, credit_card_token, credit_card_expire_date_month, credit_card_expire_date_year, credit_card_number_hidden, credit_card_secure_id_hidden* [block:api-header] { "type": "basic", "title": "Special dependancies" } [/block] There can be some special dependancies between fields, which are not immediately obvious: - **wants_receipt**: a receipt requires the address of the donor, so there will be an error if no address is provided. We recommend to set the address as required fields in your form-settings or you should place this field together with the address-fields. - **wants_newsletter**: to send a newsletter the email address of the donor is required, so there will be an error if no email address is provided. We recommend to set the email address as required field or you should place this field together with the email-address-field. - **amount and fb_item_id**: if items have a minimum amount, you should query the item before or together with the amount. - **amount and payment_method**: consider the minimum and maximum amounts of your payment methods set in your extensions settings in your FundraisingBox. We recommend to set the same min/max-amounts for all payment methods. - **interval and payment_method**: not all payment methods are suitable for recurring payments. Please consider your [form configuration](/docs/form-configuration-json) to show or hide the available payment methods. - **payment_method and country**: you can restrict the payment methods to selected countries in your extension-settings. Please consider your [form configuration](/docs/form-configuration-json) to show or hide the available payment methods. We recommend to query the address (with the country) before the payment method. - **payment_method and bank-data**: you have to query the bank-data after or with the payment_method for correct validation. **Adresslabor-validation** If you are using the Adresslabor-extension, you should place the name- and address-fields in one step. [block:callout] { "type": "danger", "title": "IP of donation", "body": "If you are **not** using Javascript (e.g. our jQuery-Plugin) to send the data, you have to provide the IP of the user (not of your server!). This is required to block spamming users/bots, **otherwise your server will be blocked!**" } [/block] [block:api-header] { "type": "basic", "title": "Credit card fields" } [/block] Due to security requirements credit card fields are handled via iframes. We strongly recommend to use our Form-API to handle these fields. See [Credit card data processing](doc:form-api-jquery-plugin-credit-card-data-processing) for further information. If you don't use our Form-API you have to implement the Javascript of your credit card provider by yourself and send all required fields to our API.