Skip to main content

FAQ (Frequently Asked Questions)

Authentication & Security​

  • Why does the AccessToken become invalid after 24 hours? For security reasons, it is generated with a limited lifetime. It becomes invalid after 24 hours; a new token must be obtained using the same ApiKey and SecretKey.

  • I am getting a “401 Unauthorized” error on a request. What should I do? Usually, the AccessToken is missing, incorrect, or expired. Check that AccessToken: <JWT> is sent in the header and that the token is valid.

  • Why does an empty list return in multiple queries (Query)? There is no record matching the filter criteria, or the parameter name/value is incorrect (e.g., using erpcode instead of erpCode). Make sure to use parameter names exactly as defined.

  • Why is the payment set not visible? A payment set may not be assigned to the relevant member, or the endpoint permission may be disabled. Check the license and permissions.

  • What does the “Previously Transferred” message mean? SetPaymentERPCode works idempotently; the same ErpTransactionCode is not processed a second time, and an informational message is returned.

  • Is there a difference between Sandbox and Prod environments? Sandbox is for testing purposes and does not perform real transactions. Prod is live, and transactions are recorded in the ERP. Start integrations in the Sandbox environment.

  • How can I tell if the transfer to ERP was successful? SetPaymentERPCode returns a success message; additionally, in the results of GetPayments / GetReversals, the vposTransactionDetails.erpTransactionCode field will be populated.

  • What is the recommended flow for automatically refreshing the token? Before each request, check the expiration of the locally stored token. If it has expired, obtain a new token using the same ApiKey/SecretKey and resend the request.

  • Which header(s) are mandatory? AccessToken is mandatory for all authorized endpoints. If the content is JSON, send Content-Type: application/json.

  • What should the date/time format and time zone be? Use UTC ISO8601 for all date/time fields (e.g., 2025-09-11T14:37:39). UTC should be assumed on the server side.

Listing, Pagination, and Filtering​

  • How can I find out the total number of records? Use the currentPage, rowCount, and pageCount fields in list responses. rowCount gives the total result count, and pageCount gives the total number of pages.

  • What is the maximum pageSize? The default is 10; a maximum of 100 is recommended. Larger values may negatively affect performance or be restricted.

  • Can I use multiple filters at the same time? Yes. You can send supported parameters together (e.g., name + date range).

  • Is sorting (sort) supported? Unless explicitly stated in this document, the default sorting is used. If custom sorting is required, sort the results on the client side.

  • Is case sensitivity applied? Since exact matching is expected for parameter names, be case-sensitive; sensitivity for values may vary by endpoint. The safest approach is to normalize what you send.

Agent (Dealer/Customer) and Data Accuracy​

  • How do I specify the Agent type? In listing, type=dealer is for Dealer/Sub-dealer, and type=customer is for Customer/Sub-customer.

  • How does codeOrErpCode work in single queries? If the member code or ERP code matches exactly, the record is returned. Incorrect or missing values may result in a 404.

  • Are address fields mandatory? The document explicitly states that address information must be complete. Fill in cityName, districtName, and address; otherwise, you will receive an error.

  • What is taxNumber for individual members? If the Dealer/Sub-dealer/Customer/Sub-customer is an individual, the taxNumber field contains the TCKN.

Payments, Refunds, and ERP Integration​

  • Has a transaction been transferred to ERP? If vposTransactionDetails.erpTransactionCode is populated for the relevant transaction, it has been processed in the ERP.

  • What does reversalType mean in refunds? reversalType = 50 → Cancellation, reversalType = 60 → Refund.

  • Is partial refund supported? Partial refund behavior is not explicitly specified in this document. Check your refund records via GetReversals and apply your business rules accordingly.

Data Format and Best Practices​

  • How should numeric/decimal formats be in JSON? Use a dot (.) as the decimal separator in JSON. Do not send local formats (comma ,).

  • What is the character set? All content is UTF-8. Use Content-Type: application/json; charset=utf-8 in requests.

  • How should empty/null fields be interpreted? They indicate the absence of data according to the field definition. Perform null-safe checks on the client side and assign defaults according to business rules.

  • What are the performance recommendations when retrieving large volumes of data? Use pagination, narrow the date range, process only the required fields, and consume results in a streaming manner on the client side.

  • Is there a webhook? Webhook notifications are not specified in this document. For synchronous data needs, run REST queries periodically; if applicable, follow internal guidelines.