PayTR is a Turkey-based payment infrastructure provider, and thanks to iFrame API integration, you can easily add a payment form to your website. In this article, we will teach you step by step how to make PayTR iFrame API integration in the most accurate and secure way. We will also explain the critical points you may encounter in PayTR integration with examples.

We also recommend that you pay attention to issues such as REST API security improvements and middleware usage during your development process:

How to Make PayTR iFrame API Integration?

Step 1: Creating a Token Request

To use the iFrame payment form, you must first request a token. This request must be made by the server (backend) using the POST method.

POST URL:

https://www.paytr.com/odeme/api/get-token

Required POST Parameters:

merchant_id: PayTR Merchant ID
user_ip: User's IP address
merchant_oid: Order number
email: User email address
payment_amount: Payment amount (in cents)
currency: Currency (TL, USD, EUR, etc.)
user_basket: Basket content (in JSON format, base64 encoded)
no_installment: 0 or 1
max_installment: Maximum number of installments
paytr_token: Special signed token value
merchant_ok_url, merchant_fail_url: Payment result redirect addresses
user_name, user_address, user_phone

How to Calculate paytr_token?

$hash_str = $merchant_id.$user_ip.$merchant_oid.$email.$payment_amount.$user_basket.$no_installment.$max_installment.$currency.$test_mode;
$paytr_token = base64_encode(hash_hmac('sha256', $hash_str.$merchant_salt, $merchant_key, true));

Step 2: Displaying the Payment Form with iFrame

After the token is received, an iframe is presented to the user as follows:

<script src="https://www.paytr.com/js/iframeResizer.min.js"></script>
<iframe src="https://www.paytr.com/odeme/guvenli/<?php echo $token;?>" id="paytriframe" frameborder="0" scrolling="no" style="width: 100%;"></iframe>
<script>iFrameResize({},'#paytriframe');</script>

Step 3: Get the Final Payment Result with Notification URL

Even if the customer makes a payment and is redirected to merchant_ok_url, the actual order confirmation or cancellation is done with the "Notification URL" (asynchronous POST request received by the server).

Important Note:

Never confirm/cancel orders on merchant_ok_url or merchant_fail_url pages!

Only perform order operations with the incoming asynchronous notification POST request.

Sample iFrame API Connection Flow

The user clicks the "Pay" button.
The server collects the necessary data and retrieves the iframe_token from the PayTR API.
An iframe is created with this token.
The user enters their card information and makes the payment via the iframe.
As a result of the payment, PayTR notifies your system of the result via the Notification URL.
You then confirm or cancel the order according to this notification data.

Development and Testing Recommendations

When developing on localhost, be sure to use your external IP address.
In test mode, send debug_on=1 to see error messages clearly.
Send the payment_amount value multiplied by 100.
Make the merchant_oid value unique for each payment.

Conclusion: Easy and Secure Payment Integration with PayTR iFrame API

When implemented correctly, PayTR iFrame API offers both a user-friendly and PCI-DSS compliant secure payment experience. By following this guide, you can perform a smooth and professional PayTR integration.

Be sure to check out these articles for more API security information and development practices: