Payments integration
PayTR
What it does
- Collects card payments with 3D Secure through PayTR's iframe or direct model.
- Returns installment options at checkout and records the chosen installment count on each payment.
- Verifies every PayTR notification signature before an order changes state, and issues refunds through the API.
Provider based in Turkey
PayTR is the second of Kambloo's two primary card gateways. It is a common choice for Turkish stores that want a single contract and a quick start. The adapter supports 3D Secure, installments, stored cards, and API refunds. It is an Internal Module with no fee from Kambloo.
How it works with Kambloo
PayTR can run in two 3D Secure modes, and the adapter handles both. In iframe mode PayTR returns HTML content that Kambloo embeds in the checkout page. In direct mode the customer is redirected to PayTR. In both cases the customer types the card number on PayTR's side. Kambloo's servers never see it, so the store's PCI scope stays at SAQ-A.
The order is created in pending state and stock is reserved before the payment starts. PayTR sends a server-to-server notification to your store's webhook endpoint when the bank answers. Kambloo verifies the signature first. Only then does it update the payment row, mark the order paid, and release the customer to the confirmation page. A failed 3D Secure attempt releases the stock reservation at once and returns the customer to the cart. Each retry becomes a new payment row, so you keep a full history.
Notifications may arrive more than once: a browser return and a server callback, or a retry. Kambloo defends against this in three layers. A cache lock on the conversation ID serialises concurrent duplicates. A unique index on the transaction ID stops a second insert. The payment state machine refuses to move a captured payment again, so the order-paid event fires only once. If nothing arrives in 10 minutes, a query job asks PayTR for the status.
Installment options come from PayTR at checkout, based on the card BIN and cart total. You control which counts are enabled and whether the surcharge is shown per installment. The chosen count is written to the payment record.
Requirements
- A PayTR merchant account and API credentials.
- PayTR test mode for the first end-to-end order.
- A live store domain so PayTR can reach your notification URL.
Setup steps
The short version. The screens in your store admin follow the same order.
- Install the PayTR module from the Market. It is free.
- Enter your PayTR API credentials under Settings > Payments > PayTR. They are stored encrypted and shown masked.
- Pick iframe or direct 3D Secure mode.
- Run a test order with PayTR's test mode enabled.
- Enable the gateway. It appears at checkout once configuration is complete.
Questions about PayTR
Should I use iframe or direct mode?
Iframe mode keeps the customer on your checkout page while the 3D Secure step renders inside a frame. Direct mode redirects to PayTR. Card data stays with PayTR in both modes.
Can a repeated PayTR notification create a second payment record?
No. Each notification is locked on gateway plus conversation ID, and the transaction ID is unique in the payments table. Duplicates are acknowledged and ignored.
Can I refund only part of an order?
Yes. Refund any amount up to the refundable balance from the order screen. The request goes to PayTR's refund API and the result is recorded against the payment.