{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"864a6196-ea6e-4bd1-8342-22fc7890dfd5","name":"API 3 - Partner Documentation","description":"This reference section provides you with a complete and in-depth description of the Better Payment API for partners and is currently `work in progress`.\n\nThe Partner API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.\n\nYou can use the Partner API in test mode, which does not affect your live data or interact with the banking networks. The base URL you use for the request determines whether the request is live or test mode:\n\n```\nTest mode: https://testapi.better-fs.de/v3\n\n```\n\nLive mode base URL will be provided on request.\n\nThe Partner API differs as we release new versions and tailor functionality.\n\n**Please Note:**\n\n*   Query parameters in the URL are only possible for filter and sort options\n*   All POST data need to go into the request body in the JSON format from the examples\n    \n\n# Security / Authentication\n\nThe Partner API uses API credentials (API key and API secret) to authenticate requests.  \nYour API credentials carry many privileges, so be sure to keep them secure and do not share them in publicly accessible areas such as GitHub, client-side code, and so forth.\n\nAll API requests must be made over HTTPS (port 443) using TLS 1.2. Calls made over plain HTTP (port 80 or any other port) will fail.\n\nAPI requests always need to be authenticated with Basic Authentication. Basic authentication is a simple authentication scheme built into the HTTP protocol.\n\nYou will have to attach `Basic` followed by base64 encoded string of your `api_key:api_secret` combination.\n\nFor example, to authorize as `9eca1a5cacbed63fd932:7423655f519517490af0` you would attach the following to the header of your request:\n\n``` json\nAuthorization: Basic OWVjYTFhNWNhY2JlZDYzZmQ5MzI6NzQyMzY1NWY1MTk1MTc0OTBhZjA=\n\n```\n\nAll other parameters are sent in the body of your request.\n\n# Encoding\n\nThe system expects data to be sent as json encoded in UTF-8.\n\nUsing this in the header can help:\n\n```\nContent-Type: application/json\n\n```\n\n# Time\n\nThe server for the API are running in UTC (Coordinated Universal Time).\n\n# HTTP Status Codes\n\nHTTP Status Codes  \nFor each request you send to our API the HTTP status code of the response will already tell you the basic result.\n\n*   200 - successful request\n*   201 - successful request creating a new resource\n*   400 - bad request because invalid parameters or values sent\n*   401 - invalid authorization header provided\n*   403 - invalid access token provided or no permission\n*   404 - requested resource or endpoint/url is not found or doesn't exist\n*   422 - Entity can't be processed because of invalid input parameter\n    \n\nFor payments you'll want more fine grained information to find out why a payment failed. You're getting this information in the response body with result `NOK` and corresponding error code and message.\n\n# Metadata\n\nMetadata is additional data that is available in the response for certain GET requests and supports the data set. This includes:\n\n*   Pagination\n*   Search Filter\n*   Sort Option\n    \n\n# Changelog\n\n### **v3.18**\n\n*   PayPal is now a supported payment method.\n    \n\n### v3.11\n\n*08.06.2021*\n\n*   [API Users Create](https://partnerdocs.better-fs.de/#32e05f18-f43d-445e-ae61-a924a513ad4d) can set a reporter role that is similar to the partner role but only allows GET requests.\n*   [API Users Index](https://partnerdocs.better-fs.de/#787520b7-6f32-4b78-8ea7-fa3a5434ad05) can filter role by reporter.\n*   [API Users Update](https://partnerdocs.better-fs.de/#4a8e3e62-3586-4df1-8a76-4be702ef5e31) can update role to reporter.\n    \n\n### v3.2\n\n*04.08.2020*\n\n*   [Transactions Payment](https://partnerdocs.better-fs.de/#b02cf8f5-a015-4a10-9b4d-f284b63dd325) has a `fee` block with `settled` parameter now.\n    \n\n### v3.1.2\n\n*21.07.2020*\n\n*   [API Users Update](https://partnerdocs.better-fs.de/#4a8e3e62-3586-4df1-8a76-4be702ef5e31) allows to set merchant_id correctly now.\n*   [Transactions Payment](https://partnerdocs.better-fs.de/#b02cf8f5-a015-4a10-9b4d-f284b63dd325) is providing the correct redirect_url for the payment pages now.\n    \n\n### v3.1.1\n\n*08.07.2020*\n\n*   In [Transactions Payment](https://partnerdocs.better-fs.de/#b02cf8f5-a015-4a10-9b4d-f284b63dd325) is a new parameter cancel in the urls block. The cancel button from the payment page is redirecting to this URL instead of the error_url if this parameter is set.\n    \n\n### v3.1\n\n*07.07.2020*\n\n*   In [Transactions Index](https://partnerdocs.better-fs.de/#5873a723-0c05-4940-a9a5-ee8c125c72e3) a new searchable_by parameter for merchant_reference has been added\n*   internal improvements and updates\n    \n\n### v3.0\n\n*15.06.2020*\n\n*   a new API request [Transactions Refund](https://partnerdocs.better-fs.de/#2fae7dca-a037-4014-a5a7-3efc78a6fcff) has been added.\n*   The field send_customer_id has been removed as configuration parameter for credit card payment processor *payon* in [Merchants Payment Method Updates](https://partnerdocs.better-fs.de/#569e847d-3f60-40f9-8280-5257969119c0)\n*   Added filter option for end_to_end_id for direct debit transactions in [Transactions Index](https://partnerdocs.better-fs.de/#5873a723-0c05-4940-a9a5-ee8c125c72e3).\n    \n\n### v3.0-pre4\n\n*18.05.2020*\n\n*   Pagination has been renamed to metadata in responses of index API calls.\n*   Metadata includes an array sortable_by which is a list of valid values for the sort URL parameter.\n*   Metadata includes an array searchable_by which is a list of valid URL parameters to filter search results\n*   All above applies to:\n    *   [API Users Index](https://partnerdocs.better-fs.de/#787520b7-6f32-4b78-8ea7-fa3a5434ad05)\n    *   [Merchants Index](https://partnerdocs.better-fs.de/#d437a830-c817-4376-af91-7b1226933f1d)\n    *   [Transactions Index](https://partnerdocs.better-fs.de/#5873a723-0c05-4940-a9a5-ee8c125c72e3)\n    *   [Transactions Log](https://partnerdocs.better-fs.de/#a7dfc074-776a-4a85-8019-7aab59d34fe9)\n*   The return data is now called data_set instead of data to be consistent with other API calls that return arrays.\n    *   [Merchants Payment Methods Index](https://partnerdocs.better-fs.de/#188d545a-13cc-48d2-827f-3fe27263b622)\n*   The payment processor payon has a change in the configuration fields. user_name and password is not longer needed and have been replaced with the bearer_token.\n    *   [Payment Methods Index](https://partnerdocs.better-fs.de/#42a64054-9aa1-438b-a247-831b0d94986a)\n    *   [Payment Methods Show](https://partnerdocs.better-fs.de/#32954f7e-9cec-4e36-ab4c-07991511bb8d)\n    *   [Merchants Payment Methods Index](https://partnerdocs.better-fs.de/#188d545a-13cc-48d2-827f-3fe27263b622)\n    *   [Merchants Payment Methods Show](https://partnerdocs.better-fs.de/#a684f920-980b-4a8e-a810-d04fb3a60b01)\n    *   [Merchants Payment Methods Update](https://partnerdocs.better-fs.de/#569e847d-3f60-40f9-8280-5257969119c0)\n\n### v3.0-pre3\n\n*13.05.2020*\n\nThe frame_origin is not set in every payment call anymore but can be configured once for payment pages in the form settings of the merchant.\n\n*   [Transactions Payment](https://partnerdocs.better-fs.de/#b02cf8f5-a015-4a10-9b4d-f284b63dd325): frame_origin parameter removed\n*   [Merchants Form Settings Show](https://partnerdocs.better-fs.de/#f22ee111-0a9d-4058-9afe-731d48608ecb): frame_origin parameter added\n*   [Merchants Form Settings Update](https://partnerdocs.better-fs.de/#eac5f48c-729b-4e77-b067-46534266b0b9): frame_origin parameter added\n    \n\nMerchant address details have been moved into a separate block. Also state and country has been added.\n\n*   [Merchant Create](https://partnerdocs.better-fs.de/#04c043ab-9864-4bb0-9a56-3d2d2b6ad053): address block in request\n*   [Merchant Index](https://partnerdocs.better-fs.de/#d437a830-c817-4376-af91-7b1226933f1d): address block in response\n*   [Merchant Show](https://partnerdocs.better-fs.de/#be0a6aa0-6731-489c-a4ab-8f37969f26f5): address block in response\n*   [Merchant Update](https://partnerdocs.better-fs.de/#2cd8813e-038f-41db-b3cd-4eab1ed542a1): address block in request\n    \n\nauto_bearer_token removed from solarisbank payment processor because not required here.\n\n*   [Merchants Payment Methods Index](https://partnerdocs.better-fs.de/#188d545a-13cc-48d2-827f-3fe27263b622): auto_bearer_token removed\n*   [Merchants Payment Methods Show](https://partnerdocs.better-fs.de/#a684f920-980b-4a8e-a810-d04fb3a60b01): auto_bearer_token removed\n*   [Merchants Payment Methods Update](https://partnerdocs.better-fs.de/#569e847d-3f60-40f9-8280-5257969119c0): auto_bearer_token removed\n    \n\nAdded end_to_end_id wherever necessary in case of directdebit transactions.\n\n*   [Transactions Payment](https://partnerdocs.better-fs.de/#b02cf8f5-a015-4a10-9b4d-f284b63dd325): end_to_end_id in response\n*   [Transactions Index](https://partnerdocs.better-fs.de/#5873a723-0c05-4940-a9a5-ee8c125c72e3): end_to_end_id in response\n*   [Transactions Show](https://partnerdocs.better-fs.de/#0cd4c94c-3e10-4161-a796-2340f4d67a09): end_to_end_id in response\n    \n\n# REFERENCE","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"8188056","team":441718,"collectionId":"864a6196-ea6e-4bd1-8342-22fc7890dfd5","publishedId":"T1DiGLU4","public":true,"publicUrl":"https://partnerdocs.better-fs.de","privateUrl":"https://go.postman.co/documentation/8188056-864a6196-ea6e-4bd1-8342-22fc7890dfd5","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":"API3 Partner Documentation"}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.10.1","publishDate":"2024-12-16T13:50:50.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"API3 Partner Documentation","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[{"name":"API 3 - Partner Documentation","id":"b2356c82-5cf7-49a3-96e7-060000d0e9c4","owner":"8188056","values":[{"key":"base_url","value":"https://testapi.better-fs.de/v3","enabled":true},{"key":"api_key","value":"[api_key]","enabled":true},{"key":"api_secret","value":"[api_secret]","enabled":true}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/24e453665616bfc315155efa99daadb88678e2539c23164cf3f7431d9ae69ae3","favicon":"https://better-fs.de/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"API 3 - Partner Documentation","value":"8188056-b2356c82-5cf7-49a3-96e7-060000d0e9c4"}],"canonicalUrl":"https://partnerdocs.better-fs.de/view/metadata/T1DiGLU4"}