Payment Gateway Integration in Turkey: Steps, 3D Secure and ERP

Virtual POS integration, the term used in Turkey for connecting an online store to card payments, means linking your e-commerce site's payment step to the card infrastructure of a bank or a licensed payment institution. In practice it has three stages: a merchant agreement with the payment provider, connecting the site to the provider through an API or a ready-made module, and testing every scenario, including 3D Secure, in a test environment before going live. On a ready-made e-commerce platform this is mostly a matter of module settings; with custom software it requires development, testing and an accounting connection.

Bank virtual POS or payment institution?

The first decision is who will collect the payment. There are two routes:

• A bank's virtual POS: You sign a merchant agreement directly with a bank, and the money goes to your account at that bank. If you want to work with more than one bank, each means a separate agreement and a separate integration.
• A payment institution: With a single agreement and a single integration, you accept cards and installment options from many banks. Applications are usually approved faster; the commission structure and the time it takes for money to reach your account depend on the contract.

Whichever route you choose, check that the institution you work with is authorized. In Turkey, payment institutions and electronic money institutions operate under Law No. 6493, and the Central Bank of the Republic of Turkey (CBRT) publishes the list of licensed institutions on its website. For example, iyzico and PayTR appear on the CBRT's list of electronic money institutions.

For a newly opened store, a payment institution is often the more practical start. Businesses with established revenue that can negotiate commission with a bank consider a direct bank POS, or both together.

How do you integrate a virtual POS, step by step?

1. Application and contract. The provider asks for your company documents, your site's address and the product category you sell. When reviewing the application, providers usually also look at the distance sales contract, return terms and contact details on the site; publishing these pages in advance speeds things up.
2. Test environment credentials. After approval, you receive a merchant ID, API keys and test cards. These are not written into the code; they are stored on the server side as secret environment variables.
3. Choosing the integration method. On a ready-made platform, the provider's module is installed. With custom software, payment initiation, the 3D Secure redirect and the result notification are built according to the provider's API documentation.
4. Verifying the result notification. What moves an order to "paid" should not be the page the browser returns to, but the notification the provider sends to your server, with its signature (hash) verified. If this check is skipped, fake "payment successful" responses can turn into orders.
5. Scenario tests. Successful payment, insufficient funds, abandoning on the 3D Secure screen, timeout, the same order being paid twice, partial refund and full refund are each tested separately.
6. Going live and monitoring. After entering the live keys, the chain is checked with a small real payment and its refund. In the first weeks, the declined transaction rate and error codes are tracked.

Hosted payment page or direct API?

The most important technical decision in the integration is where the card details are entered.

When you use the provider's payment page or an embedded payment form, the card number never touches your server. Setup is fast and the security burden is low; design flexibility is limited to what the provider allows.

Collecting cards through your own form via a direct API gives you full design control but also increases your responsibility. Every organization that stores, processes or transmits card data falls within the scope of PCI DSS (Payment Card Industry Data Security Standard). If card data passes through your server, you need to ensure and document compliance with this standard.

For most small and mid-sized businesses, the right choice is to style the provider's payment form to match your design and never take card data onto your server. If subscriptions or one-click payments are needed, card storage is also left to the provider's card storage (tokenization) service.

How does 3D Secure affect the payment flow?

3D Secure is the protocol in which the cardholder is authenticated by the card-issuing bank during payment. Its current version, EMV 3-D Secure, assesses risk by sharing transaction and device information with the bank: low-risk transactions can pass without an extra step, while those seen as risky require a one-time password or biometric verification.

The real difficulty with 3D Secure in an integration is the user experience. The problems we see most often are:

• The session dropping and the cart emptying when the user returns to the site from the bank's verification screen on mobile.
• Money being charged but no order being created because the return URL is set incorrectly.
• Redirects getting stuck in the in-app browsers of social media apps.

If you sell through social media ads in particular, test these three scenarios separately.

How do you set up installments, BIN lookup and commission?

Installment options vary by which bank and which card program a card belongs to. The payment form recognizes the bank from the first digits of the card (the BIN) and shows the installments available for that card. On credit cards, the number of installments is not unrestricted in every product group; some categories have a cap or an installment ban. Confirm the limit that applies to your category with your provider.

Who bears the cost of installments is a pricing decision. You can pass the installment charge on to the customer, offer certain installments without a charge and absorb the cost in your margin, or combine the two. What matters is that the total shown on the payment screen matches the amount the customer will see on their card statement.

Looking at a single rate when comparing commission is misleading. When comparing offers, evaluate these items together:

• Commission on single-payment and installment transactions
• The time for funds to reach your account (settlement period) and its effect on the rate
• Fixed fees per transaction, refund and cancellation fees
• Acceptance of foreign cards and currency conversion terms

Why should virtual POS and ERP integration be planned separately?

Collecting the payment does not mean the work is done; the collection needs to land correctly in your accounts. If you do not connect the virtual POS to your ERP or accounting software, your team downloads reports from the provider's panel every day and matches them to orders by hand. Errors show up most in refunds, partial refunds and commission deductions.

In a well-built setup, when the payment notification arrives, the order, the collection record and the invoice flow are triggered, and the provider's account statement is automatically reconciled with the ERP records every day. We cover this side on our CRM and ERP solutions page.

Common mistakes

• Confirming the order based only on the browser return, without verifying the server notification.
• Writing live API keys into the code or into a publicly accessible file.
• Testing only successful payments in the test environment.
• Processing a refund manually in the provider's panel and forgetting to update the order status on the site.
• Adding unnecessary third-party code (a chat widget, extra tracking code) to the payment page.

Checklist before going live

• Is the provider on the CBRT list, and are commission, settlement period and refund fees written in the contract?
• Does card data touch your server? If so, are the PCI DSS obligations planned?
• Has the 3D Secure flow been tested on mobile and in in-app browsers?
• Is the server notification verified with a signature check?
• Have refund, partial refund and duplicate payment scenarios been tested?
• Do collections and refunds flow automatically into your ERP or accounting system?

If you want to build your store's payment infrastructure from scratch or make your existing setup talk to your accounting, take a look at our e-commerce service, or contact us to discuss your situation.