To complete the PayTR iFrame API integration, simply displaying the payment form is not enough. The actual order confirmation or cancellation takes place via the Notification URL. In this article, we will explain step by step how to integrate the PayTR Notification URL and support it with sample codes.

We also recommend that you take a look at the following article for the first step, iframe integration:

PayTR iFrame API Integration: Step-by-Step Informative Guide

What is a Notification URL?

After the customer completes the payment, PayTR makes a POST request to the Notification URL defined in your system. Thanks to this notification, you finalize the status of your order (approval/cancellation).

Important Note:

The Notification URL is not a "user redirection" page.
It works server-side.
You must give an "OK" response to the PayTR system as soon as you receive the notification.

Parameters PayTR Will Send to the Notification URL

Parameter	Required	Description
merchant_oid	Yes	Order number
status	Yes	"success" or "failed"
total_amount	Yes	Total amount paid (in cents)
hash	Yes	Hash value for signature control
failed_reason_code	No	Error code
failed_reason_msg	No	Error message
test_mode	No	Is it a test transaction?
payment_type	Yes	'card' or 'eft'
currency	No	TL, USD, EUR, etc.
payment_amount	No	Initially sent amount

How to Integrate the Notification URL?

1. Get Incoming POST Data

$post = $_POST;

2. Verify the Signature (hash) of the Incoming Data

$merchant_key = 'Your_Merchant_Key';
$merchant_salt = 'Your_Merchant_Salt';

$hash = base64_encode( hash_hmac('sha256', $post['merchant_oid'].$merchant_salt.$post['status'].$post['total_amount'], $merchant_key, true) );

if( $hash != $post['hash'] )
    die('PAYTR notification failed: bad hash');

3. Identify the Order and Update Its Status

if( $post['status'] == 'success' ) {
    // APPROVE the order
} else {
    // CANCEL the order
}

4. Be Sure to Return an "OK" Response

echo "OK";
exit;

Security Recommendations

Always verify incoming POST data with hash control.
Since you may receive the notification more than once, do not process again by querying the order status.
Do not print any additional output to your Notification URL. Just write OK.
Do not use session variables. Find orders only with merchant_oid.

Incorrect Situations and Reasons

failed_reason_code	Description
0	Detailed error message
1	Missing authentication
2	Wrong password
3	Security check failed
6	Customer did not pay
8	Installment not supported
9	Card not authorized for transaction
10	3D Secure required
11	Fraud warning
99	Technical integration error

Common Mistakes Made in the Notification URL

Not returning an OK response → The order appears as "In Progress".
Not performing hash control of the notification → Security vulnerability occurs.
Using session → Unusable, crashes.
Applying more than one approval/cancellation to the same order → Duplicate transactions occur.

Conclusion: Integration is Not Complete Without PayTR Notification URL!

PayTR Notification URL integration is the most critical part of the payment process. If you do not implement this step correctly, your payments will not be completed and your orders may be processed incompletely. By following this guide step by step, you can make your PayTR integration professional and secure.

Related Content: