{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"d3d37be4-a59d-43b6-af92-1daef54fbc9f","name":"Finclude bankchannel API","description":"## Important notice\n\n_The information and data captured in this document are strictly confidential and supplied on the basis that this information and data is confidential and will be held in confidence and not disclosed to any third party without the written consent of Financial Inclusion Technology (Proprietary) Limited. All intellectual property contained within this document is proprietary to Financial Inclusion Technology (Proprietary) Limited, all rights reserved._\n\n## Version History\n\n| DATE | API VERSION | EDITOR | REMARKS |\n| --- | --- | --- | --- |\n| 2023-06-29 | 1.0.0 | Gerhard v Rensburg | <br><br><li><p>Creation of the Postman collection and documentation for use by clients</p></li><br><br> |\n\n## Background\n\nThe Findesk Bankchannel API are specifically written to allow businesses to integrate to various banking institutions for sending payment instructions and receiving transaction notifications for actions on a bank account. The aim is to standardise payment instructions and notifications accross banking institutions.\n\nThe Findesk Bankchannel API are http-based RESTful API that uses OAuth 2.0 for authentication with open id connect for authorisation. The request and response bodies are formatted in JSON.\n\n## Ignore unknown fields\n\nClient implementations are advised to ignore unknown fields in all messages/objects, as new fields may be introduced (where such a field does not break functional backward-compatibility).\n\n## **Some general guidelines to follow**\n\nThe **denomination for most monetary transactions** are smallest Subunit which means that if the amount of a transaction is for example R12,59 the value in the api call would be send through as 1259.\n\n**Date time** should be send using RFC 3339, this means that the time zone should be included using the Z synax to indicate Zulu timezone or the UTC+0. For clarity below examples:\n\n\\* 2020-12-31T06:20:50.52Z (UTC+0)  \n\\* 2020-12-31T06:20:50.52+00:00 (UTC+0)  \n\\* 2020-12-31T14:20:50.52+07:00 (UTC+7)  \n\\* 2020-12-31T03:20:50.52-04:00 (UTC-4)\n\nRFC 3339 follows ISO 8601 date time format with the difference that is allows for the T to be replaced by a space.\n\nSee this link for a very good but simple explanation of the RFC 3339 date time format: [https://medium.com/easyread/understanding-about-rfc-3339-for-datetime-formatting-in-software-engineering-940aa5d5f68a](https://medium.com/easyread/understanding-about-rfc-3339-for-datetime-formatting-in-software-engineering-940aa5d5f68a)\n\n## Environments\n\nExternal Staging area:\n\n\\* Token request URL: [https://extauth.finclude.co.za/auth/realms/finclude/protocol/openid-connect](https://extauth.finclude.co.za/auth/realms/finclude/protocol/openid-connect)  \n\\* Base URL: [https://extlb.finclude.co.za/api/bankchannel/v1](https://extlb.finclude.co.za/api/bankchannel/v1)\n\n## Authentication\n\nAuthentication will always be the first step when building the integration. Authentication is needed before any other api call can be made.\n\nThe basic flow are shown in the diagram below.\n\n<img src=\"https://drive.google.com/uc?export=view&amp;id=1rfaQl-oJGEw1TJ3jF34MR-vlZQifWXrp\" width=\"auto\">\n\n## Credentials\n\nThe Finclude Team will provide a username, password, client)id and client_secret for the different environments. It is very important to ensure that the passwords are updated immediately and that these values are treated confidentially.\n\n## Common HTTP status codes\n\n| Status Code | Description | Explanation |\n| --- | --- | --- |\n| 100's | Informational response | The server is busy with the request. |\n| 200's | Successful response | Request were successfully completed. |\n| 300's | Redirection | Request was received, but there is a redirect of some sort. |\n| 400's | Client errors | The request was made, but the request is not valid. |\n| 500's | Server errors | Server failed to complete the request. |\n\n## API error codes\n\n| error code | error | error description |\n| --- | --- | --- |\n| 200000 | successful_response | Request was successfully completed |\n| 200001 | provider_unknown_error | Unknown Provider Exception - will return the provider error where possible |\n| 200002 | provider_error | No connection to bank system |\n| 200003 | provider_error | System currently unavailable |\n| 200004 | provider_error | Request timeout to provider |\n| 200005 | provider_error | The operation has timed out |\n| 200006 | provider_error | Provider callback timed out |\n| 200007 | provider_error | For future use |\n| 200008 | provider_error | For future use |\n| 200009 | provider_error | For future use |\n| 200010 | provider_error | For future use |\n| 200011 | provider_error | For future use |\n| 200012 | provider_error | For future use |\n| 200013 | provider_error | For future use |\n| 200014 | provider_error | For future use |\n| 200015 | provider_error | For future use |\n| 200016 | provider_error | For future use |\n| 200017 | provider_error | For future use |\n| 200018 | provider_error | For future use |\n| 200019 | provider_error | For future use |\n| 200020 | provider_error | For future use |\n| 200021 | provider_error | For future use |\n| 200022 | provider_error | For future use |\n| 200023 | provider_error | For future use |\n| 200024 | provider_error | For future use |\n| 200025 | provider_error | For future use |\n| 200026 | provider_error | For future use |\n| 200027 | provider_error | For future use |\n| 200028 | provider_error | For future use |\n| 200029 | provider_error | For future use |\n| 200030 | provider_error | For future use |\n| 300001 | api_error | Missing/incorrect parameter value |\n| 300002 | api_error | User not authorised to perform transaction |\n| 300003 | api_error | Transaction not found |\n| 300004 | api_error | TransactionId already exists |\n| 300005 | api_error | JSON schema validation error failed |\n| 300006 | api_error | Endpoint cannot be used in production |\n| 300007 | api_error | For future use |\n| 300008 | api_error | For future use |\n| 300009 | api_error | For future use |\n| 300010 | api_error | For future use |\n| 300011 | api_error | For future use |\n| 300012 | api_error | For future use |\n| 300013 | api_error | For future use |\n| 300014 | api_error | For future use |\n| 300015 | api_error | For future use |\n| 300016 | api_error | For future use |\n| 300017 | api_error | For future use |\n| 300018 | api_error | For future use |\n| 300019 | api_error | For future use |\n| 300020 | api_error | For future use |\n| 300021 | api_error | For future use |\n| 300022 | api_error | For future use |\n| 300023 | api_error | For future use |\n| 300024 | api_error | For future use |\n| 300025 | api_error | For future use |\n| 300026 | api_error | For future use |\n| 300027 | api_error | For future use |\n| 300028 | api_error | For future use |\n| 300029 | api_error | For future use |\n| 300030 | api_error | For future use |\n| 400001 | authentication_error | Invalid client_id used |\n| 400002 | authentication_error | Invalid api credentials |\n| 400003 | authentication_error | Missing form parameter: grant_type |\n| 400004 | authentication_error | Unsupported grant_type |\n| 400005 | authentication_error | Invalid scope |\n| 400006 | authentication_error | Token is not active |\n| 400007 | authentication_error | Invalid refresh token |\n| 400008 | authentication_error | Client secret not provided in request |\n| 400009 | authentication_error | Invalid client secret |\n| 400010 | authentication_error | Invalid authorization token |\n| 500000 | internal_server | The server has experienced an error |","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"14500887","team":1370094,"collectionId":"d3d37be4-a59d-43b6-af92-1daef54fbc9f","publishedId":"2s93z3eQE4","public":true,"publicUrl":"https://bankchannelapidocs.finclude.net","privateUrl":"https://go.postman.co/documentation/14500887-d3d37be4-a59d-43b6-af92-1daef54fbc9f","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"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":"2023-06-20T10:24:22.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[{"name":"bankchannel docs","id":"40956cc7-4aca-4a8f-94b5-873d54595e10","owner":"14500887","values":[{"key":"baseUrl","value":"https://extlb.finclude.co.za/api/bankchannel/v1","enabled":true},{"key":"authurl","value":"https://extauth.finclude.co.za/auth/realms/finclude/protocol/openid-connect","enabled":true},{"key":"client_id","value":"bankchannel_API","enabled":true},{"key":"client_secret","value":"a561f8dd-3a62-4c2b-8ed1-a02184386345","enabled":true},{"key":"username","value":"<enter your username>","enabled":true},{"key":"password","value":"<enter your password>","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/73a007861ac6304a754d8085f148ffaf960cca33c585f14fd654195f3b9f2a9b","favicon":"https://finclude.net/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":"bankchannel docs","value":"14500887-40956cc7-4aca-4a8f-94b5-873d54595e10"}],"canonicalUrl":"https://bankchannelapidocs.finclude.net/view/metadata/2s93z3eQE4"}