PayTR Error Codes: Detailed Guide

In PayTR integrations, you may sometimes encounter error codes during the process. In this article, you can find all the error codes and their meanings that PayTR may send in payment, refund, status query, and transfer requests in detail.

Error Codes Returned Before Going to the Bank After the Payment Process

failed_reason_code	failed_reason_msg	Description
0	Variable (Detailed error message)	Example: Insufficient card limit/balance
1	Authentication failed	Mobile phone number not entered
2	Authentication failed	Incorrect verification code entered
3	Security check failed	Fraud detection or control error
6	Customer abandoned payment	Page closed or timeout
8	Installment not supported	Installment incompatibility with card type
9	No authorization to process with the card	Store not authorized
10	3D Secure required	Payment with 3D Secure required
11	Security warning	Suspicious transaction detected
99	Technical integration error	Integration problems

Error Codes Returned from Refund API Service

err_no	err_msg	Description
000	Refund cannot be made	System congestion or lockup
001	Invalid request or store inactive	merchant_id missing or inactive
002	Invalid merchant_oid	Order number not transmitted
003	Invalid return_amount	Refund amount not sent
004	Incorrect paytr_token	Token missing or invalid
005	Successful payment not found	Related order does not exist
007	Notification not completed	Order process not yet finished
008	Payment type does not support refund	Specific payment method not refundable
009	Refund amount too high	Refund exceeds remaining amount
010	Insufficient net balance	Insufficient balance in the account
011	Refund not possible for transactions older than one year	Annual timeout

Error Codes Returned from Status Query Service

err_no	err_msg	Description
001	Invalid request or store inactive	merchant_id missing
002	Invalid merchant_oid	Order number missing
003	Incorrect paytr_token	Token missing or incorrect
004	Transaction not found	Order does not exist or failed

Platform Transfer Request Errors

err_no	err_msg	Description
001	Invalid request or store inactive	merchant_id missing
002	You are not authorized	Store is not a marketplace
003	Invalid trans_id	transfer ID missing
004	paytr_token invalid	Token missing or incorrect
005	Invalid merchant_oid	Order number missing
006	No successful payment	Order not found
007	Notification not completed	Order notification missing
008	Value date not passed	Value date must be awaited
009	trans_id reused	Unique ID required
010	Transfer amount too high	Transfer exceeds remaining amount
091	IBAN verification failed	IBAN incorrect
092	Incorrect IBAN format	Must start with TR, 26 characters
095	Sub-vendor amount less than 0	Incorrect transaction
096	Incorrect trans_id format	Only alphanumeric characters
097	IBAN missing	transfer_iban field empty
098	transfer_name missing	transfer_name field empty
099	total_amount incorrect	Numeric value expected
100	Name-Surname format error	Incorrect name/surname without space
101	Name or surname missing	Each must be min 2 characters
201-306	JSON errors, unique trans_id checks	JSON validation and special rules

Conclusion:

Verifying these error codes transparently and taking the correct actions in your system for each error situation is critical for the healthy operation of your PayTR payment infrastructure integration.

For more detailed PayTR integration guides and solutions, you can visit Eka Sunucu Knowledge Center or PayTR Error Codes.