To complete the PayTR Direct API integration, it is not enough to just send data from the payment form. Notification URL integration is mandatory to ensure that the payment result is received accurately and verified.

Related Guide:

PayTR Direct API Integration: Step 1 - Receiving Direct Payments with Payment Form

1) What is a Notification URL?

When the customer fills out and submits the payment form, PayTR sends the payment result directly to the Notification URL address you specify via POST.
From here, you receive whether the payment was successful or failed.
You must confirm/cancel the order and return an "OK" response to PayTR.

2) Data Received via POST

Field Name	Required	Description
merchant_oid	Yes	Order number
status	Yes	success or failed
total_amount	Yes	Payment amount if successful, 0 if unsuccessful
hash	Yes	Hash control data
failed_reason_code	No	Error code (if there is an error)
failed_reason_msg	No	Error message (if there is an error)
test_mode	Yes	Is it a test?
payment_type	Yes	card or eft
currency	No	TL, USD, etc.
payment_amount	No	Order amount
installment_count	No	Number of installments

As a Response: you should only return echo "OK";.

3) PHP Notification URL Example Code

$post = $_POST;

$merchant_key = 'STORE_KEY';
$merchant_salt = 'STORE_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');

if($post['status'] == 'success') {
    // Confirm Order
} else {
    // Cancel Order
}

echo "OK";
exit;

4) Critical Considerations

Do not put Entry Restrictions on the Notification URL: (No IP / login protection, etc.)
Only return OK: Do not add HTML, whitespace, etc.
Perform Hash Control: Otherwise, there is a risk of fraud.
Multiple notifications may come for one order: If you have already confirmed the order, do not process it again.
Use SSL: Your Notification URL address must be HTTPS.

5) Error Codes and Meanings

Code	Description
0	Detailed error message of the payment
1	Missing authentication
2	Authentication failed
3	Security check failed
6	Customer left the page
8	Card does not support installments
9	No authorization to process with the card
10	3D Secure required
11	Fraud warning
99	Technical integration error

6) Post-Test Payment Checks

Check the Notifications from PayTR Merchant Panel > Transaction Details.
If you see "In Progress" instead of "Successful": Notification URL did not return OK.
Check the PHP error log.
If debug mode is active, record the incoming POST data.

Conclusion: Your Integration is Now Ready!

With a correct Notification URL integration, your payment system will work 100% smoothly. This step is the basis of professional work in payment systems.

Related Resources: