How to Integrate Virtual POS? Our Guide from Test to Live Transitions
Virtual POS integration establishes a secure connection between your e-commerce site or application and our payment infrastructure. When a customer reaches the checkout step, the transaction amount and order reference are transmitted to us at Paynkolay; after the card verification and authorization process is completed, we send the result back to your system.
Proper integration isn't just about rendering the payment form. It requires separating test and live environments, generating a unique reference for each order, verifying request and response hashes, testing 3D Secure flows, and correctly managing failed transactions. This guide explains this process step-by-step for our Virtual POS from the perspective of both your business and your technical team.
Short answer: We offer different integration paths such as the Common Payment Page, Payment via Link, and direct API. Your technical team should first select the method that fits your needs, set up the flow with test credentials, verify successful and failed scenarios, and then transition to the live endpoint with live credentials once we complete your authorization.
What is Virtual POS Integration?
Virtual POS integration is the process of connecting the data flow between your cart, order, payment, and transaction result to our payment infrastructure. The authorization logic of a physical POS device works in an online environment. However, since the payment is received over the internet, communication security, the points where card data passes through, and the verification of the payment result are particularly important.
The scope of integration varies depending on the chosen model. If card fields are displayed on our hosted payment page, your business's contact with card data is minimized. If you collect card information on your own payment page, your security and PCI DSS responsibilities expand. Therefore, choosing a method is not just a design decision; it also determines your risk, compliance, and development workload.
Our Virtual POS Integration Methods
1. Common Payment Page (Redirection via Form)
In this method, the required order fields are sent to us via HTTP POST, and the customer is redirected to the payment form we host. Card information is transmitted directly to our servers. When the transaction is complete, we send the result to your defined successUrl or failUrl address.
This is generally a simpler starting point for businesses that do not want to develop a payment page from scratch and want to reduce the passage of card data through their own systems. Our documentation also describes an iframe option; however, our current iframe page states that this usage is not recommended. Therefore, the redirection flow should be your default choice in a new project, and iframes should only be selected after carefully reviewing technical requirements and risks.
2. Payment via Link
With Payment via Link, your business creates a payment link; the customer opens the link via SMS, email, WhatsApp, or another digital channel and completes the transaction on our payment page. It is suitable for businesses that do not have a website or collect remote payments outside of a standard cart flow. If you require a real-time payment experience connected to a cart and order system, the Common Payment Page or API might be more appropriate.
3. Direct API Integration
API integration gives you maximum control over the payment experience. Our public integration page defines our RESTful API structure, JSON or form-data usage, and test/live environments. However, if you collect card information on your own page, the PCI DSS scope and security responsibilities belong to your business. This model should be considered for projects with development and operation teams that are highly competent in payment security.
4. Ready E-commerce Modules
We publish ready integration modules for open-source platforms. As of August 3, 2026, our supported list includes Magento 1.9 and 2.0; OpenCart 2.0, 2.3, 3.0, and 4.0; PrestaShop 1.6, 1.7, and 8.1.0; as well as WooCommerce, GiveWP, and WHMCS. Ready modules can reduce your development time; nevertheless, version compatibility, update status, and potential conflicts with other payment plugins must be checked before going live.
Which Integration Method is Right for You?
| Method | Best Suited For | Technical Load | Critical Note |
| Common Payment Page | You have an e-commerce site; fast and controlled redirection is desired. | Medium | The card form is hosted by us; you must verify the return result separately. |
| Payment via Link | You have no website or you collect payments manually/remotely. | Low | Cart automation capabilities may be limited. |
| Direct API | You need a custom payment experience and full in-app control. | High | If you collect card data, your PCI DSS responsibilities expand. |
| Ready Module | You use a supported e-commerce infrastructure. | Low–Medium | The platform and module version must be thoroughly tested. |
Decision tip: The lowest development load is not always the best option. Order automation, brand experience, security team competence, PCI DSS scope, and maintenance capacity must all be evaluated together.
Prerequisites Before Starting the Integration
Your Paynkolay Virtual POS application and necessary transaction authorizations must be completed by us.
Your domain and the pages used in the payment flow must operate over HTTPS; TLS 1.2 or higher must be supported according to our integration page.
Your successUrl and failUrl addresses must be externally accessible, belong to the correct domain, and be secure.
You must set up a structure to generate a unique clientRefCode for each order; our documentation specifies that Turkish characters should not be used in this field.
Test and live credentials must be kept in separate configurations; live keys must never be added to code repositories, browsers, or screenshots.
You must manage order statuses with a clear state model (e.g., "awaiting payment," "successful," "failed," "canceled/refunded").
You must prepare a test plan for successful and failed payments, 3D Secure, duplicate requests, timeouts, and refund scenarios.
Virtual POS Integration with Us: 8 Steps
1. Choose the integration model
If you want us to host the card form, choose the Common Payment Page. If you are going to send payment links, use Payment via Link. If you want a completely custom flow and full technical control, evaluate the API model. If you use a supported e-commerce platform, check the latest version of our ready module first.
2. Obtain your test credentials securely
Integration credentials will be displayed in your Paynkolay panel based on your authorization. Your Merchant Secret Key must only be stored server-side in a secure secret management structure accessible by authorized personnel. The SX token must be used exactly as defined in our documentation for your chosen flow; it must not be published in a blog post, support message, screenshot, or unnecessary log record. In the Common Payment form, SX is a mandatory field in the standard HTML POST body; therefore, you should not expose the SX and the Merchant Secret Key under the same security rule.
3. Create the request fields
Our Common Payment Page flow requires mandatory fields such as the amount, the cardholder's IP address, a unique customer/order reference, successful and failed return URLs, the rnd transaction time value, and the request hash. Options like installments, currency, language, 3D Secure, and card storage can be utilized according to your contract and merchant authorizations.
4. Generate the request hash according to the validation rule
We require the relevant hash to be generated for every request. In our current public examples, the SHA-512 result is transmitted in Base64 format for both Common Payment and API requests. The exact order of fields, how empty fields are handled, and the integration version you use must match our technical document perfectly. Do not generate the hash in the browser, and never send your Merchant Secret Key to the client side.
5. Send to our test environment
For the Common Payment Page, our public documentation provides the test address as [https://paynkolaytest.nkolayislem.com.tr/Vpos](https://paynkolaytest.nkolayislem.com.tr/Vpos) and the live address as [https://paynkolay.nkolayislem.com.tr/Vpos](https://paynkolay.nkolayislem.com.tr/Vpos). During your testing phase, only use your test authorizations and our current test scenarios.
6. Test 3D Secure and error scenarios
Testing only successful payments is insufficient. You must separately test scenarios where 3D verification is completed and where it is interrupted, bank rejections, insufficient funds, incorrect hashes, missing fields, duplicate references, timeouts, and users closing the page. Non-3D transactions require a separate authorization from us, and our FAQ page clearly states that the risk for these transactions belongs entirely to your business.
7. Verify the payment result on your server side
Just because a user arrives at your successUrl does not mean the payment was successful. According to our payment result documentation, you must check the returning response hash; the RESPONSE_CODE value must be 2, and the AUTH_CODE must not be empty, 0, or 00. If the returning hash does not match the expected value, do not accept the transaction as coming from us, and do not change the order status to "paid." In the 3D AutoComplete return, you must also compare the AUTHORIZATION_AMOUNT with the amount value sent to the payment page; according to our rules, this value must be equal to or greater than the sent amount.
Most critical check: Treat the browser redirection merely as a notification that needs to be verified, not as the source of truth. Update the order only when the response hash, RESPONSE_CODE, and AUTH_CODE checks are fully successful; and in the 3D AutoComplete flow, only when the AUTHORIZATION_AMOUNT check is also complete.
8. Transition to live in a controlled manner
After completing your test scenarios and once we define your live transaction authorizations, activate the live endpoint and live integration credentials from a separate configuration. Before fully transitioning, test a controlled low-amount transaction, verify the results, check the panel records, execute a cancellation/refund, and perform an accounting reconciliation. After going live, strictly monitor your error rates and failed transactions.
Key Fields on the Common Payment Page
| Field | Purpose | Implementation Note |
| amount | Transaction amount | The decimal separator and amount format must comply with our documentation. |
| cardHolderIP | Cardholder's IP | Must be generated server-side with the correct client IP. |
| clientRefCode | Your order/reference code | Must be unique; do not use Turkish characters. |
| successUrl | Return address for successful flows | A return here is not proof of success on its own. |
| failUrl | Return address for failed flows | Must display a safe, clear message to the user. |
| rnd | Request transaction date/variable | Must be identical in the request and your request hash calculation; the return rnd value will be regenerated by us. |
| hashDataV2 | Request integrity/validation | The field order and algorithm must match our current documentation. |
| sx | Merchant/service login token | Use according to the documentation for your chosen flow; it is a POST field in the Common Payment form—do not log or share it publicly. |
| use3D | 3D Secure preference | Must be compatible with your merchant authorization and flow. |
| instalments | Installment selection | Depends on card, sector, and your contract authorizations. |
| currencyCode | Currency | Verify default and authorized currencies with us before going live. |
Note: This table summarizes the application logic. For live code, always check field names, data types, ordering, and mandatory statuses against the latest version of our integration page.
The Difference Between 3D Secure and Non-3D
3D Secure allows the cardholder's bank to apply an additional verification step. We fully support 3D Secure. Non-3D payments, however, are authorized separately; according to our FAQ, any risks that may arise in a Non-3D model belong to your business. Therefore, Non-3D should only be used after carefully evaluating your business needs, fraud controls, and risk policies.
Using 3D Secure does not replace standard integration checks. You must still verify the return hash and necessary fields in the transaction result; an order must never be considered paid if a 3D flow fails.
Test Checklist
Successful 3D Secure payment: Order, panel, and result fields match perfectly.
3D verification rejection or cancellation: Order is not marked as paid.
Bank rejection/insufficient funds: A safe, non-technical message is displayed to the user.
Incorrect or missing hash: The request is rejected and secret values are never logged.
Retrying with the same clientRefCode: Duplicate collections do not occur.
Manual access to successUrl or a fake POST request: The order is not marked as paid.
Altered amount or order info in the response: Validation fails immediately.
Timeout/connection loss: An ambiguous transaction does not trigger an automatic secondary charge.
Installment and currency options: Only displayed as authorized in your configuration.
Cancellations and refunds: Same-day cancellations and next-day refunds work according to our panel/service rules.
Live transition: Verified that absolutely no test SX tokens, keys, or endpoints remain active.
Logging: Transaction records are properly masked regarding personal and card data.
Common Integration Errors
Mixing Test and Live Credentials
Using our test endpoint with a live SX token, or our live endpoint with test credentials, will result in validation and authorization errors. Keep your environment variables strictly separated and verify in your go-live checklist that endpoints and credentials match the correct environment.
Changing Hash Field Order or Character Encoding
If your field order, empty value handling, URL formatting, or character encoding in the hash calculation differs from our documentation, it will not match the value we generate. Keep your concatenation code in a single function and test it rigorously against our official examples.
Failing to Use a Unique Order Reference
Reusing the same reference causes duplicate transactions or severe matching issues. Every payment attempt must clearly relate to an order; implement an idempotent business rule for retry attempts.
Treating the successUrl Return as Direct Success
This is a critical flaw that can cause orders to appear "paid" when no money was received. Do not change the order status without verifying the returning response hash, ensuring RESPONSE_CODE is 2, checking the AUTH_CODE, and—in the 3D AutoComplete flow—comparing the AUTHORIZATION_AMOUNT against the sent amount.
Writing Secret Keys to the Client Side or Logs
Never expose your Merchant Secret Key or similar values in JavaScript code, mobile apps, error screens, analytics events, or plaintext logs. If a secret value is exposed, deleting it is not enough; you must cut access immediately and request a key renewal from us.
Defaulting to Iframes
Our current iframe documentation explicitly states that we do not recommend this usage. Browser settings like SameSite, Content-Security-Policy, and X-Frame-Options can break the flow. For new setups, always prioritize redirection or our other official methods first.
Secure Integration Checklist
Enforce HTTPS and our supported TLS versions across your entire payment flow.
Store the Merchant Secret Key and other real secrets in secure server-side management; use the SX token strictly as defined in our documentation, and keep it out of logs.
Ensure hidden values are never in source code, screenshots, support tickets, or logs.
Verify the returning hash on the server side; never trust the browser URL alone.
Do not send card numbers or CVVs to application logs, analytics systems, or error trackers.
Restrict admin panel and live key access based on the principle of least privilege.
Keep your dependencies up to date and monitor for security patches affecting the payment flow.
Monitor your systems for duplicate requests, abnormal error spikes, and unexpected transaction amounts.
Have an incident response procedure ready for key leaks, cancellations, and renewals.
PCI DSS Note: Our PCI DSS Level 1 compliance does not automatically absolve your business of its own responsibilities. Your scope is determined by who hosts the payment page, whether card data touches your servers, and your chosen integration architecture.
Should Cancellation and Refund Processes be Included in the Integration?
Yes. Building a correct order cancellation and refund flow is just as important as accepting payments. In our public documentation, a reversal made on the same day (before the bank's end-of-day) is defined as a cancellation; a transaction made the next day (or after the end-of-day) is a refund. Please note that the SX value used in our cancellation/refund service differs from the SX value used for sales and must be verified in your panel.
You must match the refund amount, transaction date, Paynkolay reference, and return result with your order and accounting records. Our FAQ page details how you can process full or partial refunds via the panel. If you plan to execute partial refunds or industry-specific operations via our service, confirm your authorizations and business rules with our team before going live.
How Long Does Virtual POS Integration Take?
It is impossible to provide a single, fixed timeframe. A business using one of our ready modules on an established site will launch much faster than a business developing a custom API, card storage, recurring payments, or complex order flows. Application reviews, authorization, site readiness, software capacity, testing scenarios, and security audits all dictate the total duration.
The safest approach is to allocate distinct timeframes for method selection, test setup, error/3D scenario testing, user acceptance, and a controlled live transition. Avoid making commitments like "It will definitely be live today" or "It absolutely takes 24 hours" without confirming your contract status and current campaigns with us.
Benefits of Our Virtual POS Integration for Your Business
You can establish a payment structure accommodating various card programs through a single integration.
Based on your product and merchant authorizations, you can offer options like installments for domestic credit cards and single payments for international cards.
You can manage payments, track transactions, run reports, and handle cancellations/refunds entirely from our panel.
Depending on your business model, you can leverage additional features like card storage, recurring payments, and fraud prevention.
Our Common Payment Page, Payment via Link, API, and ready module options allow you to adapt the integration to your exact technical requirements.
The availability of these features is subject to your merchant agreement, sector regulations, technical authorizations, and current product terms. Please request a custom offer from us regarding commission rates, value dates, installment limits, or foreign currency authorizations.
Frequently Asked Questions
Is a developer required for your Virtual POS integration?
Technical development is necessary for custom API or form integrations. If you utilize a current ready module for a supported platform, the workload decreases significantly; however, we still highly recommend having a technical professional handle the configuration, testing, and go-live checks.
Do you provide a test environment?
Yes. Our public integration documentation defines our test and live environments separately. Do not use real credit cards or live keys until all your test scenarios are complete.
Does a user reaching the successUrl mean the payment was successful?
No. According to our documentation, you must verify the returning response hash, ensure the RESPONSE_CODE is 2, and confirm the AUTH_CODE contains a valid value (not empty, 0, or 00). For 3D AutoComplete returns, you must also compare the AUTHORIZATION_AMOUNT against the sent amount. Never mark an order as paid until you have completed these server-side checks.
Can we accept Non-3D payments?
According to our FAQ page, Non-3D payments require a separate authorization, and the financial risks for these transactions fall on your business. You must confirm your eligibility and risk policy directly with us.
Do you have ready integrations for WooCommerce and OpenCart?
As of August 3, 2026, our integration page lists modules for WooCommerce and OpenCart 2.0, 2.3, 3.0, and 4.0. Before installing, cross-check platform, PHP, and plugin version compatibility in our current documentation.
Can I store card information on my own server?
Storing card data introduces extremely high security and PCI DSS requirements. You must never store card information as plain text in your application. If you require card storage, you should evaluate our authorized card storage solution and technical guidelines.
Which metrics should we monitor after the integration is complete?
We recommend tracking your successful transaction rate, bank rejections, 3D abandonment rate, technical errors, duplicate requests, average response times, cancellations/refunds, and the volume of ambiguous transactions. Always convert error codes into secure, user-friendly messages rather than displaying raw technical output to your customers.
Paynkolay Sanal POS’u inceleyin • Entegrasyon dokümanlarına gidin • Başvuru yapın