Getting Started with PayTR Direct API Direct API Step 1

Direct API Step 1

TRANSFER OF INFORMATION FROM PAYMENT FORM

1) The customer starts a new order on the merchant webpage.

2) Merchant redirects the customer to the page where the payment options are presented.

3) After the customer inputs and confirms the information for the payment, the merchant should produce a security token. The data to be used in token production is listed below. Please check sample codes for clarification on token production.

Data to be used in token production

Field name / type	Description	Mandatory	Limitations & Notes
merchant_id (string)	Merchant ID: Your Merchant ID (Mağaza no) provided by PayTR	Yes
user_ip (string)	User ip: User IP received during the request (Important: Make sure you send the external IP address when you run tests on your local machine)	Yes	Up to 39 characters (ipv4)
merchant_oid (string)	Merchant order id: The unique order id you set for the transaction.(Note: Order number is posted back within callback notification	Yes	Up to 64 characters, Alpha numeric
email (string)	User email address: The email address which; the user registered with on your system or you received via the order form	Yes	Up to 100 characters
payment_amount(integer)	Payment amount: The total amount of the order.	Yes	Brackets only send as dot (.)
payment_type(string)	Payment type	Yes	('card')
installment_count(int)	Installment count	Yes	0, 2, 3, 4, 5, 6, 7, 8, 9, 10,11,12
currency(string)	Currency	No	TL, EUR, USD, GBP, RUB (TL is assumed if not sent)
test_mode	When the merchant is in live mode, it can be sent as 1 to run a test	No	0 or 1
non_3d	For Non3D transactions send this value as 1	Yes	0 or 1
request_exp_date(int)	If a value other than zero is sent, payment must be completed within that time. (e.g. You can use it for security purposes in case of price updates etc.)	No	Timestamp

4) The Merchant system sends the token, and the data used to produce the token, and the data which is not used for the token production but required for payment proccess, to https://www.paytr.com/odeme with POST method (Important Notice: The form on the merchant page must POST only to PayTR URL because it contains sensitive card information. POST should never be sent to the server of the merchant.)

POST REQUEST FIELDS AND VALUES:

Field name / type	Description	Mandatory	Limitations & Notes
merchant_id (integer)	Merchant ID: Your Merchant ID provided by PayTR	Yes
paytr_token (string)	Paytr_token: It is used to ensure that the request comes from you and the content did not change	Yes	Please check the sample codes for calculation
user_ip (string)	User ip: User IP received during the request (Important: Make sure you send the external IP address when you run tests on your local machine)	Yes	Up to 39 characters (ipv4)
merchant_oid (string)	Merchant order id: The unique order id you set for the transaction.(Note: Order number is posted back within callback notification	Yes	Up to 64 characters, Alpha numeric
email (string)	User email address: The email address which; the user registered with on your system or you received via the order form	Yes	Up to 100 characters
payment_amount (double), decimal (.) and two digits after the point	Payment amount: The total amount of the order.	Yes	For example: 100.99 or 150 or 1500.35
payment_type(string)	Payment type	Yes	('card')
installment_count(int)	Installment count	Yes	0, 2, 3, 4, 5, 6, 7, 8, 9, 10,11,12
card_type(string)	Card type (For installment transactions)	No	advantage, axess, combo, bonus, cardfinans, maximum, paraf, world, saglamkart
currency(string)	Currency	No	TL(or TRY), EUR, USDD (TL is assumed if not sent)
client_lang(string)	Language to be used on payment process	No	tr for Turkish or en for English (tr is assumed if not sent)
test_mode	When the merchant is in live mode, it can be sent as 1 to run a test	No	0 or 1
non_3d	For Non3D transactions send this value as 1	Yes	0 or 1
non3d_test_failed	If you need to test failed Non3D transaction send 1 (non_3d and test_mode values must be both 1)	No	0 or 1
cc_owner(string)	Card holder name	Yes	Up to 50 characters
card_number(string)	Card number	Yes	Up to 16 characters
expiry_month(string)	Card expiry date (Month)	Yes	1, 2, 3, .. , 11, 12
expiry_year(string)	Card expiry date (Year)	Yes	20, 21, 22,…
cvv(string)	Card security code	Yes	Up to 4 characters
merchant_ok_url(string)	The page the user will be redirected to after successful payment (e.g. Order status / my orders page)(Warning: the payment may not have been approved yet when the user reaches this page	Yes	Up to 400 characters
merchant_fail_url(string)	The page that the user will be redirected to if something unexpected occurs	Yes	Up to 400 characters
user_name (string)	User name and surname: First and last name of the user that you have on your system or received via the order form	Yes	Up to 60 characters
user_address (string)	User address: The address of the user that you have on your system or received via the order form	Yes	Up to 400 characters
user_phone (string)	User phone number: The phone number of the user that you have on your system or received via the order form	Yes	Up to 20 characters
user_basket (string)	User basket/order contents	Yes	JSON - Please check the sample codes for structure
debug_on (int)	Display errors: If the value is 1, when wrong or incomplete information is transmitted to the API, error message is displayed on the page.	No	0 or 1(Be sure to send 1 to detect errors during the integration and testing process)
sync_mode (int)	Sync Mode: After sending a payment request, the response in JSON format returns directly to the request result without redirecting to the successful or unsuccessful page according to the result of the transaction. In addition; Details of the transaction are sent to the defined Notification URL address. The values that the status field returned as a result of sync mode can receive are “failed”, “wait_callback” and “success Note: The Non3D authorization must be turned on in your store for this operation.	No	0 or 1 (A request must be sent to us in order for the relevant authorization to be defined to the store. If it is approved by our units, the authorization will be defined to the store.)

SYNC MODE RESPONSE

status	msg (Description)	utoken, ctoken (If the card has been stored))
failed	“You have a process that is still in progress, you can try it again after it is completed”. or a different error message.	No
wait_callback	Checking Payment, Wait for Notification.	Yes
success	Successful Payment.	Yes

5The PAYTR system performs checks and verifications on the sent information and directs the customer to the merchant_ok_url or merchant_fail_url address given by the merchant according to the payment result. In case of redirecting to merchant_ok_url, no data is sent in the POST content.In case of redirecting to merchant_fail_url, the fail_message field in the POST content contains information about why the payment failed. This information is a formatted message that can be displayed directly to the customer.

6)The result of the payment attempt is entered into the Notification URL (Callback URL) on the Merchant website, token, merchant order number and payment status, etc. The member workplace is notified by posting the information.

This step concludes the part of the payment process which the user will interact with. HOWEVER; the integration is not yet complete. STEP 2 must be completed in order to receive the payment result (success / failed) and to confirm / cancel the order.

IMPORTANT NOTICE: PayTR payment infrastructure works asynchronously.Therefore, when the payment is completed, the customer is redirected to merchant_ok_url, while the final result (Successful or Unsuccessful) of the payment is sent to the Notification URL by POST. No data is sent to merchant_ok_url, so you should not take actions such as order confirmation/cancellation on the page you specify as merchant_ok_url.

About Odeabank Cards: Maximum 3 installments are made with Odeabank Axess Bank'O Card cards. Therefore, you can not send more than 3 installments for the relevant cards.

<!doctype html>
<html>
    <head>
        <meta charset="UTF-8">
    </head>

    <?php

        $merchant_id = 'MAGAZA_NO';
        $merchant_key = 'XXXXXXXXXXX';
        $merchant_salt = 'YYYYYYYYYYY';

        $merchant_ok_url="http://site-ismi/basarili";
        $merchant_fail_url="http://site-ismi/basarisiz";

        $user_basket = htmlentities(json_encode(array(
            array("Altis Renkli Deniz Yatağı - Mavi", "18.00", 1),
            array("Pharmasol Güneş Kremi 50+ Yetişkin & Bepanthol Cilt Bakım Kremi", "33,25", 2),
            array("Bestway Çocuklar İçin Plaj Seti Beach Set ÇANTADA DENİZ TOPU-BOT-KOLLUK", "45,42", 1)
        )));

        srand(time(null));
        $merchant_oid = rand();

        $test_mode="0";

        $non_3d="0";

        $client_lang = "tr";

        $non3d_test_failed="0";

        if( isset( $_SERVER["HTTP_CLIENT_IP"] ) ) {
            $ip = $_SERVER["HTTP_CLIENT_IP"];
        } elseif( isset( $_SERVER["HTTP_X_FORWARDED_FOR"] ) ) {
            $ip = $_SERVER["HTTP_X_FORWARDED_FOR"];
        } else {
            $ip = $_SERVER["REMOTE_ADDR"];
        }

        $user_ip = $ip;

        $email = "testnon3d@paytr.com";

        $payment_amount = "100.99";
        $currency="TL";

        $payment_type = "card";

        $post_url = "https://www.paytr.com/odeme";

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

    <body>
        <form action="<?php echo $post_url;?>" method="post">
          Kart Sahibi Adı: <input type="text" name="cc_owner" value="TEST KARTI"><br>
          Kart Numarası: <input type="text" name="card_number" value="9792030394440796"><br>
          Kart Son Kullanma Ay: <input type="text" name="expiry_month" value="12" ><br>
          Kart Son Kullanma Yıl: <input type="text" name="expiry_year" value="99"><br>
          Kart Güvenlik Kodu: <input type="text" name="cvv" value="000"><br>
          <input type="hidden" name="merchant_id" value="<?php echo $merchant_id;?>">
          <input type="hidden" name="user_ip" value="<?php echo $user_ip;?>">
          <input type="hidden" name="merchant_oid" value="<?php echo $merchant_oid;?>">
          <input type="hidden" name="email" value="<?php echo $email;?>">
          <input type="hidden" name="payment_type" value="<?php echo $payment_type;?>">
          <input type="hidden" name="payment_amount" value="<?php echo $payment_amount;?>">
          <input type="hidden" name="currency" value="<?php echo $currency;?>">
          <input type="hidden" name="test_mode" value="<?php echo $test_mode;?>">
          <input type="hidden" name="non_3d" value="<?php echo $non_3d;?>">
          <input type="hidden" name="merchant_ok_url" value="<?php echo $merchant_ok_url;?>">
          <input type="hidden" name="merchant_fail_url" value="<?php echo $merchant_fail_url;?>">
          <input type="hidden" name="user_name" value="Paytr Test">
          <input type="hidden" name="user_address" value="test test test">
          <input type="hidden" name="user_phone" value="05555555555">
          <input type="hidden" name="user_basket" value="<?php echo $user_basket; ?>">
          <input type="hidden" name="debug_on" value="1">
          <input type="hidden" name="client_lang" value="<?php echo $client_lang; ?>">
          <input type="hidden" name="paytr_token" value="<?php echo $token; ?>">
          <input type="hidden" name="non3d_test_failed" value="<?php echo $non3d_test_failed; ?>">
          <input type="hidden" name="installment_count" value="<?php echo $installment_count; ?>">
          <input type="hidden" name="card_type" value="<?php echo $card_type; ?>">
          <input type="submit" value="Submit">
        </form>
    </body>
</html>

# Python 3.6+

import base64
import hashlib
import hmac
import html
import json
import random

from django.shortcuts import render, HttpResponse
from django.views.decorators.csrf import csrf_exempt

def home(request):
    merchant_id = 'MAGAZA_NO'
    merchant_key = b'XXXXXXXXXXX'
    merchant_salt = b'YYYYYYYYYYY'

    merchant_ok_url = 'http://site-ismi/basarili'
    merchant_fail_url = 'http://site-ismi/basarisiz'

    user_basket = html.unescape(json.dumps([['Altis Renkli Deniz Yatağı - Mavi', '18.00', 1],
                                            ['Pharmaso Güneş Kremi 50+ Yetişkin & Bepanthol Cilt Bakım Kremi', '33,25',
                                             2],
                                            ['Bestway Çocuklar İçin Plaj Seti Beach Set ÇANTADA DENİZ TOPU-BOT-KOLLUK',
                                             '45,42', 1]]))

    merchant_oid = 'OS' + random.randint(1, 9999999).__str__()
    test_mode = '0'
    debug_on = '1'

    non_3d = '0'

    client_lang = 'tr'

    non3d_test_failed = '0'
    user_ip = ''
    email = 'testnon3d@paytr.com'

    payment_amount = "100.99"
    currency = 'TL'
    payment_type = 'card'

    user_name = 'Paytr Test'
    user_address = 'test test test'
    user_phone = '05555555555'

    card_type = 'bonus'
    installment_count = '5'

    hash_str = merchant_id + user_ip + merchant_oid + email + payment_amount + payment_type + installment_count + currency + test_mode + non_3d
    paytr_token = base64.b64encode(hmac.new(merchant_key, hash_str.encode() + merchant_salt, hashlib.sha256).digest())

    context = {
        'merchant_id': merchant_id,
        'user_ip': user_ip,
        'merchant_oid': merchant_oid,
        'email': email,
        'payment_type': payment_type,
        'payment_amount': payment_amount,
        'currency': currency,
        'test_mode': test_mode,
        'non_3d': non_3d,
        'merchant_ok_url': merchant_ok_url,
        'merchant_fail_url': merchant_fail_url,
        'user_name': user_name,
        'user_address': user_address,
        'user_phone': user_phone,
        'user_basket': user_basket,
        'debug_on': debug_on,
        'client_lang': client_lang,
        'paytr_token': paytr_token.decode(),
        'non3d_test_failed': non3d_test_failed,
        'installment_count': installment_count,
        'card_type': card_type
    }

    return render(request, 'home.html', context)

using Newtonsoft.Json.Linq;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Mvc;
using System.Collections.Specialized;
using System.Net;
using System.Security.Cryptography;
using System.Text;
using System.Web.Script.Serialization;
using System.Web.UI;
using System.Web.UI.WebControls;

namespace WebApplication1.Controllers
{
    public class HomeController : Controller
    {
        public ActionResult Test()
        {
            ViewBag.Message = "Your test page.";

            string merchant_id = "XXXXXX";
            string merchant_key = "XXXXXX";
            string merchant_salt = "XXXXXX";

            string emailstr = "info@siteniz.com";

            int payment_amountstr = 100.99;

            string merchant_oid = "";

            string user_namestr = "";

            string user_addressstr = "";

            string user_phonestr = "";

            string merchant_ok_url = "http://siteniz.com/Success";

            string merchant_fail_url = "http://siteniz.com/Failed";

            string user_ip = Request.ServerVariables["HTTP_X_FORWARDED_FOR"];
            if (user_ip == "" || user_ip == null){
                user_ip = Request.ServerVariables["REMOTE_ADDR"];
            }

            object[][] user_basket = {
            new object[] {"Örnek ürün 1", "18.00", 1}, 
            new object[] {"Örnek ürün 2", "33.25", 2}, 
            new object[] {"Örnek ürün 3", "45.42", 1},
            };

            string card_type = "bonus";

            string debug_on = "1";

            string test_mode = "0";

            string non_3d = "0";

            string non3d_test_failed = "0";

            string installment_count = "0";

            string payment_type = "card";

            string post_url = "https://www.paytr.com/odeme";

            string currency = "TL";

            JavaScriptSerializer ser = new JavaScriptSerializer();
            string user_basket_json = ser.Serialize(user_basket);

            string Birlestir = string.Concat(merchant_id, user_ip, merchant_oid, emailstr, payment_amountstr.ToString(), payment_type, installment_count, currency, test_mode, non_3d, merchant_salt);
            HMACSHA256 hmac = new HMACSHA256(Encoding.UTF8.GetBytes(merchant_key));
            byte[] b = hmac.ComputeHash(Encoding.UTF8.GetBytes(Birlestir));

            ViewBag.MerchantId = merchant_id;
            ViewBag.UserIp = user_ip;
            ViewBag.MerchantOid = merchant_oid;
            ViewBag.Email = emailstr;
            ViewBag.PaymentType = payment_type;
            ViewBag.PaymentAmount = payment_amountstr.ToString();
            ViewBag.InstallmentCount = installment_count;
            ViewBag.Currency = currency;
            ViewBag.TestMode = test_mode;
            ViewBag.Non3d = non_3d;
            ViewBag.MerchantOkUrl = merchant_ok_url;
            ViewBag.MerchantFailUrl = merchant_fail_url;
            ViewBag.UserName = user_namestr;
            ViewBag.UserAddress = user_addressstr;
            ViewBag.UserPhone = user_phonestr;
            ViewBag.UserBasket = user_basket_json;
            ViewBag.Non3dTestFailed = non3d_test_failed;
            ViewBag.DebugOn = debug_on;
            ViewBag.CardType = card_type;
            ViewBag.PostUrl = post_url;
            ViewBag.PaytrToken = Convert.ToBase64String(b);

            return View();
        }
    }
}

var express = require('express');
var ejsLayouts = require('express-ejs-layouts');
var microtime = require('microtime');
var crypto = require('crypto');
var nodeBase64 = require('nodejs-base64-converter');
var app = express();
var path = require('path');

app.set('views', path.join(__dirname, '/app_server/views'));
app.set('view engine', 'ejs');
app.use(ejsLayouts);
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

var merchant_id = 'MAGAZA_NO';
var merchant_key = 'XXXXXXXXXXX';
var merchant_salt = 'YYYYYYYYYYY';
var basket = JSON.stringify([
    ['Örnek Ürün 1', '50.00', 1], 
    ['Örnek Ürün 2', '33.25', 2], 
    ['Örnek Ürün 3', '45.42', 1] 
]);
var user_basket = basket;
var merchant_oid = "IN" + microtime.now(); 
var user_ip = '';
var email = 'testnon3d@paytr.com'; 
var payment_amount = '100.99'; 
var currency = 'TL';
var test_mode = '0';
var user_name = 'PayTR Test';
var user_address = 'test test test'; 
var user_phone = '05555555555';

var merchant_ok_url = 'http://www.siteniz.com/odeme_basarili.php';

var merchant_fail_url = 'http://www.siteniz.com/odeme_hata.php';
var debug_on = 1;
var client_lang = 'tr'; 
var payment_type = 'card'; 
var non_3d = '0'; 
var card_type = '';  
var installment_count = '0'; 

var non3d_test_failed = '0';

app.get("/", function (req, res) {

    var hashSTR = `${merchant_id}${user_ip}${merchant_oid}${email}${payment_amount}${payment_type}${installment_count}${currency}${test_mode}${non_3d}`;
    console.log('HASH STR' + hashSTR);
    var paytr_token = hashSTR + merchant_salt;
    console.log('PAYTR TOKEN' + paytr_token);
    var token = crypto.createHmac('sha256', merchant_key).update(paytr_token).digest('base64');

    console.log('TOKEN' + token);
    context = {
        merchant_id,
        user_ip,
        merchant_oid,
        email,
        payment_type,
        payment_amount,
        currency,
        test_mode,
        non_3d,
        merchant_ok_url,
        merchant_fail_url,
        user_name,
        user_address,
        user_phone,
        user_basket,
        debug_on,
        client_lang,
        token,
        non3d_test_failed,
        installment_count,
        card_type,
    };

    res.render('index');

});

app.post("/callback", function (req, res) {

    var callback = req.body;

    paytr_token = callback.merchant_oid + merchant_salt + callback.status + callback.total_amount;
    var token = crypto.createHmac('sha256', merchant_key).update(paytr_token).digest('base64');

    if (token != callback.hash) {
        throw new Error("PAYTR notification failed: bad hash");
    }

    if (callback.status == 'success') {

    } else {

    }

    res.send('OK'); 

});

var port = 3200;
app.listen(port, function () {
    console.log("Server is running. Port:" + port);
});

Direct API Step 1 sample codes click to download