{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"255ff211-3d7b-424f-852d-48e19328ebdb","name":"Finclude B2B API","description":"## Important notices\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> _**From April 2022, /confirmation calls are compulsory for all vending transactions, especially so for bill payments. See the \"/confirmation\" section and \"Basic Transaction Flows\" for more information**_ \n  \n> _**NOTE It is the obligation of a the calling party to make use of the /reprint endpoint in a scenario where the response of a vending transaction done via the Finclude B2B API, is not received by the calling party, before a new vending transaction is initiated for the same meter number/msisdn/product.**_ \n  \n\n## Additional information and documentation\n\n<p>To see a list of available products and their respective api_tx_object_ids, more info regarding specific bill payments and example till slips as mandated by the utility companies, see<a href=\"https://docs.google.com/spreadsheets/d/1F_TH6IK-cqfh3WhrTL52ZiFZTy79McoGCjTQu2KMe5c/edit?usp=sharing\">Additional B2B API information</a></p>\n\n<p>To enable consumers of the Finclude B2B API to code their interface to the Finclude B2B API in such a way that it is not needed to make additional code changes every time Finclude deploys additional products, Finclude has incorporated specific information and structures into the B2B API that allow consumers to:</p>\n\n- dynamically add products to a structured menu, including displaying relevant thumbnails\n    \n- dynamically build the inputs for capturing the input data\n    \n- dynamically verify the captured data\n    \n- dynamically call the correct endpoint using the correct JSON request body format (including the data that was captured)\n    \n- dynamically display any information on screen that allows the cashier/operator/client to decide whether to abort or continue\n    \n- dynamically print the correct information on the till/customer slip\n    \n\n<p>We have prepared an additional document to address specifically<a href=\"https://docs.google.com/document/d/1M0cWgh-KogMkSsESyNLcqm-Ypl-xCzZxb9gLrCbGJlk/edit?usp=sharing\">Using the Finclude B2B API to build dynamic menus and make dynamic calls</a></p>\n\n<p>You can download the<a href=\"https://drive.google.com/file/d/1Y1QnQyNBygJrhP4ceNn8y_miHAjfz3U3/view?usp=sharing\">Finclude B2B API specification.yaml</a></p>\n\n## Version History\n\n| DATE | API VERSION | EDITOR | REMARKS |\n| --- | --- | --- | --- |\n| 2021-03-17 | 0.0.67 | Gerhard v Rensburg | \\- Converted from API Blueprint schema to OpenApi 3 schema. This was needed to allow the sharing of the API schema information which is not contained in the Postman documentation.  <br>\\- Added additional examples in the API Collection.  <br>\\- Switched to using environment variables instead of collection variables since this allows for easier switching between the mock server and other environments. |\n| 2021-03-18 | 0.0.78 | Gerhard v Rensburg | \\- In the API spec all references to application/x-www-form-urlencoded were replaced with application/json and the Collection, mock server and corresponding documentation were updated to reflect this.  <br>\\- Updated auth/token error schema mandatory keys.  <br>\\- Updated Collection to display the correct error codes on the example error responses and the mock server.  <br>\\- Correct required keys in the /transaction_status body schema.  <br>\\- transaction_status request body tx_log_id type on the schema was corrected from array to integer.  <br>\\- Change /requestCancellation property from cancelDetail to cancel_detail  <br>\\- Change /requestCancellation property, cancel_reason_code from minLength 10 and maxLength 10 to only maxLength 100  <br>\\- Added requester_data to /requestCancellation request body schema  <br>\\- Since OpenAPI 3 is case sensitive for parameters (object keys), all parameters have been standardised to all lower case.  <br>\\- Added error code section |\n| 2021-03-30 | 0.0.84 | Gerhard v Rensburg | \\- Changed the base url for getting and refreshing a token (/token). Note that the base path differs from the rest of the API  <br>\\- Added the various base paths for the various API environments to this document  <br>\\- Changed /token to be url-encoded (application/x-www-form-urlencoded) instead of raw JSON (application/json). Note that this only applies when requesting or refreshing a token. The rest of the API still accepts the body as JSON  <br>\\- Updated the API spec for /token: Instead of passing in \"read write\" as the scope, \"read write openid\" must be passed in  <br>\\- Changed /objectlist from a GET to a POST since a GET should not contain a JSON body  <br>\\- Changed /prepaid_utility_lookup from a GET to a POST since a GET should not contain a JSON body  <br>\\- Changed /transaction_status from a GET to a POST since a GET should not contain a JSON body  <br>\\- Changed /reprint from a GET to a POST since a GET should not contain a JSON body  <br>\\- Updated all the body references to id_token to use a variable that contains the id_token instead a \"hard coded\" id_token. This will allow for easier testing against the live environments since the id_token received from the authentication server is now automatically updated into the id_token-variable |\n| 2021-04-07 | 0.0.86 | Gerhard v Rensburg | \\- meter_number for /prepaid_utility_lookup request schema changed from integer to string to allow for meter numbers that start with a 0  <br>\\- meter_number for /prepaid_utility_sale request schema changed from integer to string to allow for meter numbers that start with a 0  <br>\\- meter_number for /prepaid_utility_sale response schema changed from integer to string to allow for meter numbers that start with a 0  <br>\\- Updated the list of required properties for both the request body and the response schemas for pin_airtime_data  <br>\\- Clarified the schema for /confirmation property \"payment_method\" to be more in-line with how objects within arrays are supposed to be used  <br>\\- Added a couple of \"generic\" test calls to the Postman collection in the folder \"Generic tests\" |\n| 2021-04-16 | 0.0.90 | Gerhard v Rensburg | \\- Since the req_transaction_id has to be unique every call, I added a new environment variable ({{your_unique_transaction_id}}) to the Postman collection. This is now used in the request bodies to supply a unique req_transaction_id so that the req_transaction_id does not have to be continuously changed by hand.  <br>\\- Update all the endpoint calls in the Postman collection to show the date format with the time zone information added as it would be used for South African time. Example: \"2021-01-10T07:36:39.001+02:00\"  <br>\\- Forced the addition of the Authorization key to the header information. Because oAuth 2 authentication is used, Postman should be adding this to the headers automatically but it seems that it does not always do so and this creates confusion. Forcing it into the headers in the collection means that it now clearly shows in the documentation that this should be included in the header  <br>\\- Added a description to the x-mock-match-request-body header key in the Postman collection so that it is clear that this header key is only used for the Postman mock server configuration and is not needed when calling the Finclude API  <br>\\- Added a link to an article that gives a good but simple explanation for the RFC 3339 date time format  <br>\\- Updatedthe API spec request and response schemas for /confirmation and /requestCancellation. Corrected their properties req_transaction_id & ord_req_transaction_id to string instead of integer  <br>\\- Updated the API spec to indicate that for the request body, /prepaid_utility_lookup - parameters - meter_number is required  <br>\\- Updated the API spec and removed from the \"required\" list for the request bodies of /objectlist & /prepaid_utility_sale & /transaction_status &/confirmation & /reprint & /requestCancellation, a number of properties that are not required and added in those that are  <br>\\- Updated API spec for the request body schemas of /confirmation & /requestCancellation to also include \"req_platform\"  <br>\\- Updated API spec and corrected /requestCancellation property tx_log_id from string to integer. |\n| 2021-04-21 | 0.0.91 | Gerhard v Rensburg | \\- Updated the API spec to add sales_api_tx_object_id to /utility_lookup since it was not specified in the response schema though it should have been included previously  <br>\\- Removed requester_data from the response schema for /transaction_status. Since requester_date is not sent as part as the request body, it makes no sense to have requester_data in the response |\n| 2021-05-14 | 0.0.91 | Gerhard v Rensburg | \\- Updated the documentation for auth/token to give more clarity regarding the use of expired tokens |\n| 2021-06-11 | 2.0.0 | Gerhard v Rensburg | \\- Version 2 was released fixing the issue with the id_token. In V1 the access_token was passed in as the id_token. In V2, the id_token has to be passed in. Note that the base URL for V2 has changed. |\n| 2021-08-20 | 2.0.0 | Gerhard v Rensburg | \\- Switched the OpenAPI specification from JSON format to YAML. This was done because YAML allows for easier multi-line descriptions in the specification doc  <br>\\- Added /mobile_pay  <br>\\- A couple of additional error codes were added into the error code list  <br>\\- Some of the examples wree removed because they over complicated things and led to confusion. Because of this the Postman collection structure is now much more simplified.  <br>\\- The API specification document now contains all the information needed to be able to successfully create a Postman collection directly off the API specification document |\n| 2021-08-25 | 2.0.1 | Gerhard v Rensburg | \\- Added a number of additional error codes to the API Error code list  <br>\\- Added the specification for the /mobile_pay endpoint |\n| 2022-02-28 | 2.0.1 | Gerhard v Rensburg | \\- Update the /token information to give better clarification of the use of the three token types returned in the response  <br>\\- Made a correction to the code examples that showed the value of the id_token key as \"null\" or as an empty string. It now correctly shows \" the id_token value you received in the response from the /token call\" |\n| 2022-03-30 | 2.0.1 | Gerhard v Rensburg | \\- Added /bill_lookup and /bill_payment endpoint information  <br>\\- Added a link to a Google sheet with a list of api_tx_object_id as well as information regarding the request JSON and response JSON data that applies to the Zambia bill payment providers |\n| 2022-04-19 | 2.0.1 | Gerhard v Rensburg | \\- Calling either /confirmation or /requestCancellation after a vending call (examples: /pint_airtime_data, /prepaid_utility_sale, /bill_payment) is now compulsory for all new implementations after April 2022. Without calling /confirmation, /bill_payments will never be completed and the transactions will automatically be rolled back after a period of time.  <br>\\- Added the following new error codes: 200030, 200031, 200032, 200033 |\n| 2022-05-16 | 2.0.1 | Gerhard v Rensburg | \\- Added the following new error codes: 200034 |\n| 2022-08-19 | 2.0.2 | Gerhard v Rensburg | \\- Added the specification for mobile_cashin and mobile_cashout |\n| 2022-09-22 | 2.0.2 | Gerhard v Rensburg | \\- Updated the description of /reprint to give more clarity. Also updated the example request body and response body for a successful call |\n| 2022-12-15 | 2.0.3 | Gerhard v Rensburg | \\- Added new endpoints: mobile_lookup, mobile_cashin & mobile_cashout |\n| 2023-01-09 | 3.0.0 | Gerhard v Rensburg | \\- Major version change to version 3.0.0  <br>\\- API URLs were updated to show the test server for B2B v3. The URLS for B2B v2 servers were removed  <br>\\- /objectlist endpoint was updated. Note that the response returned has changed significantly.  <br>\\- /retrieve_image, /mobile_lookup, /mobile_cashin and /mobile_cashout endpoints were added |\n| 2023-03-03 | 3.0.0 | Gerhard v Rensburg | \\- Updated the description for /prepaid_utility_sale to list the possible values for the token type |\n| 2023-03-22 | 3.0.0 | Gerhard v Rensburg | \\- Expanded the API so that an optional entity_id can be passed in on the request for the majority of requests<  <br>\\- Added the filter opject to the /objectlist endpoint request to allow for the filtering of available products  <br>\\- Update the API spec to make it clear that the use of id_token when making a request has been deprecated from B2B v3 and is now optional only for the sake of backwards compatibility |\n| 2023-06-13 | 3.0.0 | Gerhard v Rensburg | \\- Added the \"Additional information and documentation\" section to the beginning of the documentation so that it will be more difficult to miss.e  <br>\\- Created additional documentation to specifically cover \"Using the Finclude B2B API to build dynamic menus and make dynamic calls\" |\n| 2023-07-24 | 3.1.0 | Gerhard v Rensburg | \\- Formalised the used of a store id. Up to now API consumenrs would have had to make use of the requester_data field to send a store id. We've now added a req_store_id field to all API calls that currently accept a req_device_id field. Going forward, if it is expected that the store id be included in reports. markof files or any other form our output from Finclude, the store id will have to be sent in the req_store_id field. The only exception is where the store id is already sent in the requester_data field  <br>\\- Updated the >/retrieve_image endpoint to allow specifyin a list of images to retrieve. Note that this required a change to the type of the image_id input on the request, as well as the structure of the response |\n| 2023-08-01 | 3.1.0 | Gerhard v Rensburg | \\- Added child_menu_group_id_list and child_product_api_tx_object_id_list to the response of the /objectList endpoint. These keys are include in the menu item objects in the menu_group |\n| 2024-01-04 | 3.1.5 | Gerhard v Rensburg | \\- Removed all references to id_token use in API requests  <br>\\- Added paygate/getURL and paygate/payUI  <br>\\- Added GET for retrieve_image |\n| 2024-03-18 | 3.1.5 | Gerhard v Rensburg | \\- Added /pinless_airtime_data endpoint  <br>\\- Added \"param_input_hint\" to the \"menu_parameters\" in the reponse of the /objectlist |\n| 2024-08-13 | 3.3.3 | Gerhard v Rensburg | \\- Added /voucher_sale and /voucher_redeem endpoints  <br>\\- Updated the descriptions for error code 200041 to 200046  <br>\\- Error responses now include the \"requester_data\" if it was included in the request payload. |\n| 2024-11-04 | 3.3.3 | Gerhard v Rensburg | \\- Added /card_lookup and /card_pay endpoints |\n| 2025-04-09 | 3.3.8 | Gerhard v Rensburg | \\- Changed endpoints: mobile_lookup to account_verification, mobile_cashin to make_payment & mobile_cashout to receive_payment  <br>\\- Updated the default description for a number of error codes (200048 to 200051)  <br>\\- Added new error codes: 400016 and 400017 |\n\n## Background\n\nThe Findesk Business to Business (B2B) API are specifically written to allow businesses to integrate to the Findesk system. The aim is to allow for one integration per transaction object/method type that can be used accross country and for different providers.\n\nThe Findesk B2B API are http-based RESTful API that used 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## Getting Started\n\nThe below diagram shows the basic api flow and indicates the use of each on a high level.\n\n<img src=\"https://content.pstmn.io/f35d9a88-cd61-4284-9c35-65e1fad08867/YXBpZmxvdy5wbmc=\">\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. Note that in some countries or for some products the denomination might be different so check the transaction object list.\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    \n- 2020-12-31T06:20:50.52+00:00 (UTC+0)\n    \n- 2020-12-31T14:20:50.52+07:00 (UTC+7)\n    \n- 2020-12-31T03:20:50.52-04:00 (UTC-4)\n    \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\nRecharged **instructions** are send back using an array of strings having a maximum of 40 characters in the string.\n\n## api_tx_object_id\n\nMany calls has the api_tx_object_id as a required field. The api_tx_object_id is used to identify the specific product for a specific country. For a list of api_tx_object_ids, see the link below.\n\n[Additional B2B API information](https://docs.google.com/spreadsheets/d/1F_TH6IK-cqfh3WhrTL52ZiFZTy79McoGCjTQu2KMe5c/edit?usp=sharing)\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    \n- Base URL: [https://extlb.finclude.co.za/api/b2b/v3/](https://extlb.finclude.co.za/api/b2b/v3/)\n    \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://content.pstmn.io/701b4ea2-13b6-4e22-bb96-cd9b97becc6d/a2V5Y2xvYWsucG5n\">\n\n## Credentials\n\nThe Finclude Team will provide a username, password and clientid for the different environments. It is very important to ensure that the password are updated immediately and that these values are treated confidentialy.\n\n## Common HTTP status codes\n\n| Status Code | Description | Explenation |\n| --- | --- | --- |\n| 100's | Informational response | The server is busy with the request. |\n| 200's | Successful response | Request were sucessfully 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 were successfully completed. |\n| 200001 | provider_unkown_error | Unknown provider error, no error description was received |\n| 200002 | provider_error | Meter can not trade, please visit provider |\n| 200003 | provider_error | Meter not found |\n| 200004 | provider_error | Amount requested less then the required minimum amount |\n| 200005 | provider_error | System unable to generate token |\n| 200006 | provider_error | System unable to complete transaction |\n| 200007 | provider_error | Customer has incomplete transaction |\n| 200008 | provider_error | FBE not available |\n| 200009 | provider_error | Meter not active |\n| 200010 | provider_error | Product is currently inactive |\n| 200011 | provider_error | No stock is available |\n| 200012 | provider_error | Recharge failed |\n| 200013 | provider_error | Purchase failed |\n| 200014 | provider_error | Payment failed |\n| 200015 | provider_error | Card not supported |\n| 200016 | provider_error | Customer has insufficient funds available |\n| 200017 | provider_error | Invalid PIN entered |\n| 200018 | provider_error | Invalid account type selected |\n| 200019 | provider_error | Expired card |\n| 200020 | provider_error | No connection to bank system |\n| 200021 | provider_error | System currently unavailable |\n| 200022 | provider_error | Request timeout to provider |\n| 200023 | provider_error | The operation has timed out |\n| 200024 | provider_error | Supplier account error |\n| 200025 | auth_error | Invalid Credentials |\n| 200026 | findesk_error | Insufficient funds in the Finclude pre-funded account |\n| 200027 | provider_error | Payment approval rejected |\n| 200028 | provider_error | Provider callback timed out |\n| 200029 | provider_error | Product not found |\n| 200030 | provider_error | Tendered amount below the allowed limit |\n| 200031 | provider_error | Tendered amount above the allowed limit |\n| 200032 | provider_error | The customer account has reached a transaction limit with the authorizer |\n| 200033 | provider_error | The account number is malformed, or does not exist |\n| 200034 | provider_error | Exact amount required, partial payments not accepted |\n| 200035 | provider_error | MSISDN invalid |\n| 200036 | provider_error | Approval not granted by wallet holder |\n| 200037 | provider_error | The transaction cannot be reversed/cancelled |\n| 200038 | provider_error | Tendered amount not within the allowed limits |\n| 200039 | provider_error | Account topup is not allowed for the specified MSISDN |\n| 200040 | provider_error | Unable to process. Please contact Finclude [support@finclude.net](https://mailto:support@finclude.net) |\n| 200041 | provider_error | Customer blocked because of KYC Failure |\n| 200042 | provider_error | Supplier system refused connection |\n| 200043 | provider_error | Token cannot be found |\n| 200044 | provider_error | The token and pin combination can not be found |\n| 200045 | provider_error | Voucher was previously redeemed |\n| 200046 | provider_error | Voucher has expired |\n| 200047 | provider_error | Voucher has been cancelled |\n| 200048 | provider_error | Deposit not allowed |\n| 200049 | provider_error | Withdrawel not allowed |\n| 200050 | provider_error | Payment was previously completed |\n| 200051 | provider_error | Invalid bank ID |\n| 200052 | provider_error | Insufficient funds in the supplier account |\n| 200053 | provider_error | For future use |\n| 200054 | provider_error | For future use |\n| 400001 | invalid_grant | Account is not fully set up |\n| 400002 | invalid_client | Invalid client credentials |\n| 400003 | invalid_request | Missing form parameter: grant_type |\n| 400004 | unsupported_grant_type | Unsupported grant_type |\n| 400005 | invalid_scope | Invalid scopes: {{scope}} |\n| 400006 | invalid_grant | Token is not active |\n| 400007 | invalid_grant | Invalid refresh token |\n| 400008 | invalid_request | Missing parameter value |\n| 400009 | invalid_user | User not authorised to perform transaction |\n| 400010 | api_error | Transaction not found |\n| 400011 | api_error | Requester transaction detail does not match tx_log_id |\n| 400012 | api_error | Invalid tx_log_id |\n| 400013 | api_error | Error retrieving receipt |\n| 400014 | api_error | Reprint is not available |\n| 400015 | api_error | Image is not available |\n| 400016 | api_error | User cancelled the transaction |\n| 400017 | api_error | Transaction could not be cancelled |\n| 401001 | invalid_request | Missing parameter: username |\n| 401002 | invalid_request | Missing parameter: password |\n| 401003 | unauthorized_client | Client secret not provided in request |\n| 401004 | unauthorized_client | Invalid client secret |\n| 401005 | unauthorized_client | Invalid authorization token |\n| 401006 | unauthorized_client | Invalid id token |\n| 401007 | invalid_request | Incorrect Parameters |\n| 401008 | invalid_api_tx_object_id | Incorrect API Tx Object |\n| 401009 | Invalid_Transaction | Transaction Id doesn't exists |\n| 401010 | invalid_status_type | Invalid Status Type |\n| 401011 | invalid_org_id | Invalid Original Transaction Id |\n| 401012 | invalid_msidsn_code | Invalid Msisdn code or not supported |\n| 500000 | internal_server | The server has experience an error. |\n| 500001 | Duplicate_Transaction | Transaction Id already exists |\n| 500002 | No_Active_Catalogue | No active catalogue for scope and api_tx_object_id |\n| 500003 | multiple_entities | More than one entity found. Please specify the entity_id in the request |\n\n> **Note:** Remember error code for unexpected errors should be the same and then we send back the error from the supplier. \n  \n\n## GLOSSARY\n\n| Term | Description |\n| --- | --- |\n| API | Application Programming Interface (API), refers to the method through which two applications talk to each other. |\n| Authentication | Determines who the user is. |\n| Authorisation | Determines which parts of the system can be accessed. |\n| B2B | Business to Business |\n| GST | General Sales Tax |\n| RESTfull API | RESTfull API is an architectural style for an api, which access data using HTTP request. It uses the methods GET, PUT, POST and DELETE to read, update, create and delete. |\n| TI | Tarrif Index |\n| tx_object | Transaction Object defines any predefined product or action that can be performed through the system. |\n| VAT | Value Added Tax |\n\n## BASIC TRANSACTION\n\nAll transaction methods follows a pattern even though the information requested or responded with may differ.\n\n## Request\n\nThe basic transaction request have the following parameters. These parameters will be unique to the requester.\n\n- **req_session_id**: Global unique identifier for the session used.\n    \n- **req_device_id**: The unique identifier for the device used in the transaction.\n    \n- **req_store_id**: The id of the store where the transaction was done.\n    \n- **req_transaction_id**: The unique transaction of the requester.\n    \n- **req_date_time**: The date time stamp of the request.\n    \n- **req_platform**: The technolgy platform used were the request originated from.\n    \n\nThe fields req_session_id and req_date_time are required.\n\nThe req_platform are used to identify the technology platform from where the transaction has originated. The following values are allowed:\n\n- **POS**: Point of Sale Devices\n    \n- **WEB**: Website\n    \n- **Mobile**: Mobile device\n    \n- **USSD**: USSD used\n    \n- **Other**: Not specific platform used\n    \n\nSome methods allow the requester to send a requester_data array with the request. The data array are limited to a maximum of ten elements consisting of field name and value.\n\n## Response\n\nThe basic transaction response consist of the following sections\n\n- **meta**: The meta section returns the requester detail with a response message.\n    \n    - response_code\n        \n    - response_message\n        \n    - req_session_id\n        \n    - req_device_id\n        \n    - req_store_id\n        \n    - req_transaction_id\n        \n    - req_date_time\n        \n    - req_platform\n        \n- **transaction_detail**: The transaction detail provide the details as per the Findesk system.\n    \n    - date_time: the date time stamp of the transaction.\n        \n    - tx_log_id: the unique transaction id within the Findesk system.\n        \n    - tx_status: the status of the transacion.\n        \n- **voucher_detail**: The voucher detail includes the information of the transaction, which is typically printed on a till slip or displayed at the end of the transacion.\n    \n\n> Note: _Not all tags are always returned._ Only tags for which information from the supplier are received, are returned. Therefore, if for example the \"outstanding\" tag in the meter lookup is not returned, you have to assume that it is information the the supplier does not supply. You have to handle this appropriately on your side, either defaulting to 0 or empty string, or handle it in some other way that makes sense in your environment. \n  \n\n- **transaction_value**: The financial value breakdown of the transaction.\n    \n\n> An error section is returned when the transaction fails. \n  \n\n- **error**\n    \n    - error_code: The numeric error code for the error.\n        \n    - error: The error group.\n        \n    - error_description: The error description.\n        \n\n> **Note:** The above serves as a guideline, use the detailed responses provided for each transaction method. \n  \n\n## Basic transaction flows\n\nUsing the methods in the api there are different possible transaction flows that can be used.\n\n**The most simple version**\n\nThe requester perform a POST requested using the method that will provide the transaction object that the user selected. The Findesk system will generate a response. The requester would then display the response to there user.\n\n<img src=\"https://content.pstmn.io/dbf297ee-8e8f-4d0e-8918-f015eacc0b55/YmFzaWNGbG93LnBuZw==\">\n\n**Include confirmation**\n\nUsing the confirmation flow, the requester must indicate that status of the transaction. The transaction status method are used to determine the transaction status should a timeout or similiar type of errors occur. The transaction status method would return a favourable result should the transaction be completed at the Findesk side. The requester can now retreive the transaction detail using the reprint method and confirm the transaction.\n\nCalls to the _/confirmation_ and _/requestCancellation_ endpoints are treated as advice messages. The network must store-and-forward these messages every 20 minutes until a response is received from Finclude, or until midnight. Finclude will always approve an advice request as long as the request is well-formed and authentication/authorization succeeds.\n\nIMPORTANT NOTE: A payment instruction to the Finclude API is not deemed complete until either a /confirmation or /requestCancellation instruction is received for the vending transaction.\n\n<img src=\"https://content.pstmn.io/6b1ce615-6d7b-462e-bcd1-cf9886a4bdba/Y29uZmlybWF0aW9uRmxvdy5wbmc=\">\n\n**Requesting cancellation**\n\nRequesting cancellation is not part of the normal flow as this action is limited to certain contractual situations. The cancel request is recorder in the Findesk system and it is important that the requester mark their transaction as such.The reversal of the transaction is a seperate step.\n\n> **Note:** It is important to note that the request for cancellation and actual cancellation are not the same. \n  \n\n<img src=\"https://content.pstmn.io/840db26b-736d-49db-830e-c2c184dc5dbe/Y2FuY2VsRmxvdy5wbmc=\">","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"14500887","team":1370094,"collectionId":"255ff211-3d7b-424f-852d-48e19328ebdb","publishedId":"2sB2cX924d","public":true,"publicUrl":"https://apidocs.finclude.net","privateUrl":"https://go.postman.co/documentation/14500887-255ff211-3d7b-424f-852d-48e19328ebdb","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.11.6","publishDate":"2026-04-10T10:06:49.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[],"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"}],"canonicalUrl":"https://apidocs.finclude.net/view/metadata/2sB2cX924d"}