Payment Architecture and Payment Gateway Integration

What is payment architecture, and when does it need separate attention?

Payment architecture is the software structure that decides how a payment is initiated, how the cardholder is authenticated, how the result is written into your system and with what assurance, and how refunds and accounting entries are tracked. Behind a single pay button, order, stock, invoicing, notification and reporting systems all work together.

The standard payment plugin of an off-the-shelf e-commerce platform is enough for most simple shops. Designing the payment flow separately becomes necessary when:

• You run a recurring billing model such as subscriptions, memberships or usage-based billing.
• You operate a marketplace or service platform that sells products from more than one seller.
• Payments are taken on the website, in the mobile app and through the call centre against the same customer account.
• You work with more than one bank or payment institution and want to route transactions by cost and approval rate.
• Reconciliation is done by hand, refunds are tracked over email and accounting records do not match collections.

What does UNIT İstanbul do in payment infrastructure, and what does it not do?

Providing payment services, processing card data and holding customer funds are licensed, regulated activities in Türkiye and in the other markets we work in. UNIT İstanbul is not a payment institution, an electronic money institution or a bank. We design and build the software that connects to the infrastructure offered by institutions that hold these licences.

We do not give legal opinions on how the relevant payment regulations apply to your business; we recommend clarifying those questions with your legal adviser and the licensed institution you will work with. On the software side, we turn those decisions into technical requirements.

Bank virtual POS integration or a payment institution?

A virtual POS is the service a bank gives a merchant so it can accept cards online. Payment institutions put a single interface in front of many banks and payment methods; onboarding and integration are faster, but the balance between fees and control is different. Which one suits you depends on your transaction volume, your instalment needs and your team's operational capacity.

Whichever option you start with, we build a payment layer that separates provider-specific code from your own business logic. Adding or replacing a provider later then does not mean rewriting your order and accounting code.

How should the cardholder authentication (Three-Domain Secure) flow be built?

Cardholder authentication is the step in which the bank asks the cardholder for a one-time code or a banking app approval before approving the payment, widely known as Three-Domain Secure. The user briefly moves to the bank's screen; if the flow is not built carefully, an order can stay unconfirmed even though the money has been taken.

1. 1.Before payment, the order is saved with a unique identifier and a pending status.
2. 2.The payment request is initiated from the server; the amount and currency come from the order record, not from data sent by the browser.
3. 3.The user is redirected to the authentication screen or it opens inside the page; on mobile it is designed to complete without leaving the app.
4. 4.On return from the bank, the result is processed based on a server-side verification call to the provider or a signed notification, not on the user's browser.
5. 5.The order is confirmed, stock is reduced and notifications are sent; this step completes on the server even if the user closes the return page.

How do you store cards and reduce PCI DSS scope?

PCI DSS is the card industry security standard that every organisation processing, transmitting or storing card data must follow. The most effective way to reduce the compliance burden is to make sure card numbers never reach your servers at all.

• Hosted payment fields: Card details are entered into secure fields the provider embeds in your page, or on its payment page; your system receives only a token.
• Tokenisation: Repeat payments with a saved card and subscriptions use the token issued by the provider instead of the card number.
• No security codes stored: The code on the back of the card is never written to a database, log or error record.
• Log masking: Card, identity and contact data are masked automatically in request and response logs.
• Access separation: The payment service's keys are kept in a separate secrets store, permissions are granted per person and keys are rotated regularly.

This approach also affects which PCI DSS self-assessment questionnaire applies to you; we recommend making the final assessment with your provider and, where needed, a qualified assessor. Processing of personal data and retention periods are set up in line with your KVKK (Turkish data protection law) privacy notice.

How are subscriptions, marketplaces and split payments designed?

Subscriptions and recurring payments

With subscriptions, the real work starts after the first charge. The renewal schedule, when and how often a failed charge is retried, how the customer is told that their card has expired, and how the remaining period is calculated on upgrades and downgrades all need written rules. When these rules are designed independently of the code and can be changed from the admin panel, the product team can test pricing without waiting for a developer.

Marketplace and sub-merchant payments

In a marketplace the customer pays once, and the amount is split into items such as seller shares, the platform commission and shipping. The split and the payouts to sellers are run by the licensed payment institution's sub-merchant infrastructure; on the software side we build seller onboarding, commission rules, the payout schedule, recalculation of the split after partial refunds and seller reports. Set-ups that may require a licence, such as paying sellers from the platform's own account, should be clarified with your legal adviser at the outset.

How are refunds, cancellations and reconciliation managed?

A cancellation (void) reverses a transaction in full before the end-of-day settlement; a refund pays back all or part of a settled transaction to the card. A chargeback starts with the cardholder's dispute at their bank and requires gathering evidence. These three cases should be modelled as separate states in the software.

Reconciliation is the comparison of payment records in your system with the provider's reports and the amounts that reach your bank account. A reconciliation service that pulls provider reports automatically, flags unmatched records and posts entries to your accounting or ERP system greatly reduces the manual checks your finance team does. We plan broader accounting and ERP integrations together with our enterprise software work.

How are in-app payments and financial flows integrated?

If you sell digital content and subscriptions in a mobile app, the app stores' rules on using their own purchase systems come into play; for physical goods and services you can use card payments or digital wallets. Making this distinction at the start of product design reduces the risk of rejection in store review. We describe our approach to apps as a whole on the mobile app development page.

Adding banking features to your app, such as account information, payment initiation, international money transfers or bill payments, is possible through the open banking and payment interfaces offered by licensed institutions. In these integrations, user consent, session duration, how exchange rates are shown and a clear statement of which institution carries out the transaction are part of the screen design.

How are payment errors, timeouts and fraud handled?

The most dangerous situation in payments is a transaction with an unknown outcome: the request was sent, and the response timed out. Blindly retrying the payment can lead to a double charge. A robust payment infrastructure is built on these principles:

• Every payment request is sent with an idempotency key, so even if the same request arrives twice, only one transaction is created.
• Payment states are managed with an explicit state machine; beyond pending, approved, declined, cancelled and refunded, no intermediate state is left undefined.
• Transactions with an uncertain outcome are queried with the provider in the background and moved to the correct state automatically.
• Provider notifications are accepted only after their signature is verified, and out-of-order or duplicate notifications are processed safely.
• Fraud controls combine the provider's risk engine with your own business rules, such as limits on repeated attempts, account age and delivery address mismatches.
• Approval rate, decline codes, response times and notification delays are monitored, and the team is alerted as soon as a threshold is crossed.

How is payment conversion measured and improved?

The payment screen is the last step of a funnel and deserves its own measurement. When reaching the payment page, entering card details, moving to the authentication screen, returning from authentication and approval are tracked as separate events, you can see where the drop-off happens. Translating bank decline codes into messages the user understands and offering an alternative payment method can win back part of that loss.

Our roots as a marketing agency help here: we set up payment events in the same language as ad and analytics measurement and plan from the start how revenue data flows correctly back to campaigns. We run improvements across the whole funnel together with our CRO and analytics team; for the e-commerce site as a whole, see our web and e-commerce service.

What determines the cost of a payment infrastructure project?

Cost is driven mainly by the number of providers to connect, the payment model (one-off, subscription, marketplace), the number of channels (web, mobile, call centre), the depth of accounting and ERP integrations and the state of the existing system. Access to the provider's test environment, the merchant approval process and the provider's pre-launch tests also shape the timeline. After discovery, we set out the scope, deliverables and maintenance terms in a written proposal. You can find our other software services and references on the Unit Software page, or get in touch to talk about your project.