In this article, we will explain step by step how to receive payments directly from the payment form using PayTR Direct API. We will cover server-side verification, token generation, correct submission of form data, and payment success statuses.

Related Guides:

Direct API Integration Working Logic

The customer wants to purchase a product/service.
Enters their information into the payment form.
A token is generated and the information is POSTed directly to PayTR.
PayTR checks the data and redirects the customer to the success/failure page.

1) How to Generate a Token?

Required Fields:

merchant_id
user_ip
merchant_oid
email
payment_amount
payment_type ('card')
installment_count
currency (Default TL)
test_mode
non_3d

PHP Token Calculation Example:

$hash_str = $merchant_id . $user_ip . $merchant_oid . $email . $payment_amount . $payment_type . $installment_count . $currency . $test_mode . $non_3d;
$paytr_token = base64_encode(hash_hmac('sha256', $hash_str.$merchant_salt, $merchant_key, true));

Note: HMAC SHA256 hash encryption with Base64 is mandatory.

2) What Needs to be Sent in the POST Request

Field Name	Description
merchant_id	Merchant ID
paytr_token	The token you generated
user_ip	Customer IP address
merchant_oid	Order number
email	Customer email address
payment_type	'card'
payment_amount	Payment amount
installment_count	Number of installments
cc_owner	Cardholder
card_number	Card number
expiry_month	Month
expiry_year	Year
cvv	CVV
merchant_ok_url	Successful redirect URL
merchant_fail_url	Failed redirect URL
user_name	Customer name
user_address	Address
user_phone	Phone number
user_basket	JSON basket data

3) Preparing the Payment Form (PHP HTML Example)

<form action="https://www.paytr.com/odeme" method="post">
    <input type="text" name="cc_owner" value="TEST KARTI">
    <input type="text" name="card_number" value="9792030394440796">
    <input type="text" name="expiry_month" value="12">
    <input type="text" name="expiry_year" value="99">
    <input type="text" name="cvv" value="000">
    <!-- Other mandatory hidden inputs -->
    <input type="hidden" name="merchant_id" value="..."><!-- etc. -->
    <input type="submit" value="Ödeme Yap">
</form>

4) Sync Mode (If to be Used)

If sync_mode=1 is sent, the payment result is returned instantly in JSON format.
You can get "status": "success" or "failed" or "wait_callback" values.
Offers a faster integrated, modern payment experience.

Sync Mode JSON Response Example:

{
  "status": "success",
  "msg": "Ödeme Başarılı",
  "utoken": "...", // If card storage is done
  "ctoken": "..."
}

5) Notification URL and Payment Results

Even if the customer goes to merchant_ok_url, the order is not confirmed!
The actual verification comes via the Notification URL with server-side POST data.
If status=success in the values received by POST, you can confirm the order.

6) Things to Consider

Card information should only be POSTed to PayTR. Never save it to your own server.
If you have trouble getting the IP address, check the "REMOTE_ADDR" value.
"SSL/TLS" must be active even in the test environment.
Send debug_on=1 to debug.

Frequently Made Mistakes and Solutions

Problem	Reason	Solution
"bad hash" error	Incorrect hash calculation	Check HMAC SHA256 and base64 encoding
Payment form gives an error	Missing field	Make sure you send all required fields
The order is not confirmed while the customer is going to merchant_ok_url	Awaiting confirmation from Notification URL	Code the Notification URL correctly

Conclusion: You are in Control with Direct API!

PayTR Direct API integration allows you to fully control the payment process on your own page. It offers a more flexible integration experience, especially with installment transactions and non-3D Secure transaction options.

Related Articles: