tr
tr

API Nasıl Çalışır?

Son kullanıcının web sitesi üzerinde satın alma işlemiyle birlikte ThirdParty, PayByMe tarafında bulunan RequestPage’e HTTP POST methodu kullanarak gerekli parametlerle istekte bulunur. İstek sonucunda PayByMe response olarak "Status=1&ErrorCode=1000&ErrorDesc=HashDegeri " döner.

Response olarak PayByMe’den Status 1 alınmış ise ThirdParty, ErrorDesc’de alınan hash değerini GET methodu ile PaymentPage’e yönlendirerek ödeme sayfasının açılmasını sağlar.

Response olumsuz ise (Status=0) ThirdParty kullanıcıyı ErrorPage’e yönlendirir (PaymentPage’e yönlendirme yapılmaz) ve ödeme işlemi başlamaz

Ödeme işlemi tamamlandıktan sonra PayByMe sistemi kullanıcıyı ThirdParty tarafındaki bilgi ekranı olan RedirectPage yönlendirir.

PaybyMe kullanıcının ücretlenip ücretlenmediğinin sonucunu ThirdParty tarafındaki NotifyPage’e POST eder. ThirdParty NotifyPage’e gönderilen verilerin kendisine ulaştığını belirtmek için, PayByMe’ye "OK" değerini response etmelidir. PayByMe’ye "OK" response’u ulaşmadığı takdirde PayByMe aynı işlem için sonucu belirli aralıklarla göndermeye devam eder.

API Rehberi

RequestPage, PaymentPage, RedirectPage ve ErrorPage birlikte çalışarak ödeme işlemini tamamlayan bir ödeme sistemi oluştururlar.

NotifyPage ise ödeme işlem sonuçlarını ThirdParty’ye aktaran ayrı bir bilgilendirme sistemidir. PaybyMe sistemi, işlem sonuçlarını sadece 80 ya da 443 portu üzerinde çalışan NotifyPage Urllerine gönderebilir.

Bu iki sistem birbirinden bağımsız olarak çalışırlar

Request Page

ThirdParty, ödeme başlatılacak işlem için PayByMe RequestPage’e HTTP POST ile aşağıdaki parametleri gönderip, paybyme tarafına işlem başlatma isteğinde bulunur.

PayByMe gelen istek karşılığında olumlu veya olumsuz bir Response text değeri döner. Bu değerler bu işlem için ödemenin başlatılıp başlatılamayacağını belirtir.

Status=1 alınmış ve işlem ödemeye hazır ise ThirdParty, ErrorDesc’de alınan hash değerini PayByMe PaymentPage’e yönlendirerek ödeme sayfasının açılmasını sağlar. PaymentPage sadece hash değeri ile açılabilir, aksi durumda yönlendirilme yapılmaması gerekir.

Response olumsuz ise (Status=0) ThirdParty kullanıcıyı ErrorPage’e yönlendirir ve ödeme işlemi başlamaz.

class Program
{
    static void Main(string[] args)
    {
    string RequestPageUrl = "Url verilecektir";
    string payUrl = "Url verilecektir.";
    var client = new RestClient(requestUrl);
    var request = new RestRequest("", RestSharp.Method.POST);
    Dictionary<string, string> data = new Dictionary<string, string>();
    data.Add("username","MyApiUsername");
    data.Add("password","MyApiPassword");
    data.Add("syncId",123456789);
    data.Add("subCompany","My Company");
    data.Add("assetName","My Content");
    data.Add("assetPrice","100"); // 100 = 1 TL
    data.Add("clientIp","127.0.0.1");
    data.Add("notifyPage","www.domain.com/notify");
    data.Add("redirectPage","www.domain.com/success");
    data.Add("errorPage","www.domain.com/error");
    foreach (var pair in data)
    {
    request.AddParameter(pair.Key, pair.Value);
    }
    request.AddParameter("application/x-www-form-urlencoded", data);
    var response = client.Execute(request);

Değişkenlerin tanımlamaları yapılır. Daha sonra PaybyMe tarafında bulunan RequestPage Url'ine bu değerler HTTP POST ile gönderilir ve de response değeri alınır.

Request Page

ThirdParty, ödeme başlatılacak işlem için PayByMe RequestPage’e HTTP POST ile aşağıdaki parametleri gönderip, PaybyMe tarafına işlem başlatma isteğinde bulunur.

PayByMe gelen istek karşılığında olumlu veya olumsuz bir Response text değeri döner. Bu değerler bu işlem için ödemenin başlatılıp başlatılamayacağını belirtir.

Status=1 alınmış ve işlem ödemeye hazır ise ThirdParty, ErrorDesc’de alınan hash değerini PayByMe PaymentPage’e yönlendirerek ödeme sayfasının açılmasını sağlar. PaymentPage sadece hash değeri ile açılabilir, aksi durumda yönlendirilme yapılmaması gerekir.

Response olumsuz ise (Status=0) ThirdParty kullanıcıyı ErrorPage’e yönlendirir ve ödeme işlemi başlamaz.

$request_url	= 'URL verilecektir.';
$payment_url	= 'URL verilecektir.';
$username       = 'MyUsername';
$password	= 'MyPasword';
$syncId		= 123456;
$subCompany	= 'My Company';
$assetName	= 'My Content';
$assetPrice	= 100; // 100 = 1 TL
$clientIp	= $_SERVER['REMOTE_ADDR'];
$countryCode	= 'TR';
$languageCode	= 'tr';
$notifyPage	= 'www.yourdomain.com/notify';
$redirectPage	= 'www.yourdomain.com/success';
$errorPage	= 'www.yourdomain.com/error';

Değişkenlerin tanımlamaları yapılır. Daha sonra PaybyMe tarafında bulunan RequestPage Url'ine bu değerler HTTP POST ile gönderilir ve de response değeri alınır.

// Usage
echo make_request($username, $password, $syncId, $shortcode, $subCompany, $assetName, $assetPrice, $clientIp, $countryCode, $languageCode);
function make_request(
$username,
$password,
$syncId,
$shortcode,
$subCompany,
$assetName,
$assetPrice,
$clientIp,
$countryCode,
$languageCode) {
$postFields = '';
$postFields .= 'username=' . $username;
$postFields .= '&password=' . $password;
$postFields .= '&syncId=' . $syncId;
$postFields .= '&shortcode=' . $shortcode;
$postFields .= '&subCompany=' . $subCompany;
$postFields .= '&assetName=' . $assetName;
$postFields .= '&assetPrice=' . $assetPrice;
$postFields .= '¬ifyPage=' . $notifyPage;
$postFields .= '&errorPage=' . $errorPage;
$postFields .= '&redirectPage=' . $redirectPage;
$postFields .= '&clientIp=' . is_null($clientIp) ? $_SERVER['REMOTE_ADDR'] : $clientIp;
$postFields .= '&countryCode=' . is_null($countryCode) ? 'TR' : $countryCode;
$postFields .= '&languageCode=' . is_null($languageCode) ? 'tr' : $languageCode;
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $request_url);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $postFields);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($curl) or die('Connection Error!');
curl_close ($curl);
return $result;
}

Payment Page

ThirdParty’nin ödeme işlemini gerçekleştirebilmesi için son kullanıcıyı yönlendirdiği PayByMe tarafından sunulan ödeme sayfasıdır. (Sadece RequestPage response’undan alınan hash değeri ile açılabilir.) PaybyMe tarafından verilecek olan ödeme sayfasına, responseda bulunan ErrorDesc parametresindaki Hash değeri GET metodu ile yönlendirme yapılır ve ödeme sayfası açılmış olur.

PaybyMe bu sayfada son kullanıcıdan alacağı ödeme kanalına ilişkin bilgilerle (örn: Cep Telefonu numarası) ödeme işlemine başlar.

Örnek
//PaybyMe tarafındaki RequestPage urline ilgili datalarla requestte yapıldıktan sonra, response Parse edilip, ErrorDesc parametresi içerisinde bulunan Hash değeri alınır

var response = client.Execute(request);
string Status = "";
string ErrorCode = "";
string ErrorDesc = "";
var Resp = HttpUtility.ParseQueryString(response.Content);
foreach (var res in Resp.Keys)
{
  if (key.ToString() == "Status")
      Status = Resp[res.ToString()];
  if (key.ToString() == "ErrorCode")
      ErrorCode = Resp[res.ToString()];
  if (key.ToString() == "ErrorDesc")
      ErrorDesc = Resp[res.ToString()];
}
if (Status == "1")
{
  Response.Redirect(payUrl + "?Hash=" + ErrorDesc);
}

Payment Page

ThirdParty’nin ödeme işlemini gerçekleştirebilmesi için son kullanıcıyı yönlendirdiği PayByMe tarafından sunulan ödeme sayfasıdır. (Sadece RequestPage response’undan alınan hash değeri ile açılabilir.) PaybyMe tarafından verilecek olan ödeme sayfasına, responseda bulunan ErrorDesc parametresindaki Hash değeri GET metodu ile yönlendirme yapılır ve ödeme sayfası açılmış olur.

PaybyMe bu sayfada son kullanıcıdan alacağı ödeme kanalına ilişkin bilgilerle (örn: Cep Telefonu numarası) ödeme işlemine başlar.

Örnek
//PaybyMe tarafındaki RequestPage urline ilgili datalarla requestte yapıldıktan sonra, response Parse edilip, ErrorDesc parametresi içerisinde bulunan Hash değeri alınır

function get_hash($result)
{
 $params = parse_str($result);
 if(!is_null($params) && !is_null($params['ErrorCode'] && $params['ErrorCode'] == '1000')) {
    $hash = $params['ErrorDesc'];
 } else {
    (!is_null($params) && !is_null($params['ErrorCode']) ? die($params['ErrorCode']) : die('An Error Occoured!'));
 }
 return $hash;
}
function user_redirect($hash)
{
     header("Location: $payment_url);
}

Redirect Page

Son kullanıcıyı Ödeme penceresi kapatıldığında sadece bilgilendirme amacıyla kullanılacak olan, ThirdParty tarafında hazırlanmış sayfadır. Ödeme işleminin başarılı şekilde sonuçlanması durumunda PaybyMe kullanıcıyı otomatik olarak bu sayfaya yönlendirir. Bu sayfada sadece “ödemeniz başarılı” gibi bir bilgilendirme olmalıdır ve hak verme işlemi bu sayfa üzerinden kesinlikle yapılmamalıdır.

Redirect Page

Son kullanıcıyı Ödeme penceresi kapatıldığında sadece bilgilendirme amacıyla kullanılacak olan, ThirdParty tarafında hazırlanmış sayfadır. Ödeme işleminin başarılı şekilde sonuçlanması durumunda PaybyMe kullanıcıyı otomatik olarak bu sayfaya yönlendirir. Bu sayfada sadece “ödemeniz başarılı” gibi bir bilgilendirme olmalıdır ve hak verme işlemi bu sayfa üzerinden kesinlikle yapılmamalıdır.

Error Page

Son kullanıcıyı Ödeme penceresi kapatıldığında sadece bilgilendirme amacıyla kullanılacak olan, ThirdParty tarafında hazırlanmış sayfadır. Ödeme işleminin başarısız şekilde sonuçlanması durumunda PaybyMe kullanıcıyı otomatik olarak bu sayfaya yönlendirir.. Bu sayfada sadece “ödemeniz başarısız” gibi bir bilgilendirme olmalıdır.

Notify Page

PayByMe ödeme işlemini gerçekleştirip gerçekleştiremediğinin sonucunu, ThirdParty’nin NotifyPage’ine HTTP POST ile aşağıdaki değerleri göndererek bildirir. ThirdParty, NotifyPage’e gönderilen verilerin kendisine ulaştığını belirtmek için PayByMe’ye her koşulda (ücretlendirme Başarlı veya Başarısız) “OK” değerini response etmelidir. Bu response ulaşmadığı takdirde PayByMe aynı işlem için sonucu belirli aralıklarla göndermeye devam edecektir. Bu Server to Server gerçekleşen bir işlemdir.

Kullanıcıya hak verilmesi: NotifyPage’e bilgi, PayByMe Server’ından Thirdparty Server’ına doğru gelmektedir. Son kullanıcıların buraya erişememesi güvenlik açısından önemlidir. Bu sebeple sadece NotifyPage’e ödeme işleminin başarılı olduğu (status=1) bilgisi geldiğinde kullanıcıya hak verilmelidir.

protected string
    status = null,
    errorCode = null,
    errorDesc = null,
    syncId = null,
    price = null,
    operatorId = null,
    assetCode = null,
    secretKey = null;

protected void Page_Load(object sender, EventArgs e)
{
    //SecretKey tanımlamalarla birlikte verilecektir
    if(secretKey == "mySecretKey")
    {
        status      = Request.Params["status"];
        errorCode   = Request.Params["errorCode"];
        errorDesc   = Request.Params["errorDesc"];
        syncId      = Request.Params["syncId"];
        price       = Request.Params["price"];
        operatorId  = Request.Params["operatorId"];
        assetCode   = Request.Params["assetCode"];
        secretKey   = Request.Params["secretKey"];

        if (status == 1)
	{
	    // Log successful
	}
	else
	{
	    // Log payment unsuccessful
	}

        Response.Write("OK");
    }
}

NotifyPage Server2Server requestlerin gerçekleştiği sayfa olup, kullanıcıya hakların verileceği sayfa burasıdır. Kullanıcı hak tanımlarını RedirectPage'de vermek güvenlik açığı oluşturacaktır.

Notify Page

PayByMe ödeme işlemini gerçekleştirip gerçekleştiremediğinin sonucunu, ThirdParty’nin NotifyPage’ine HTTP POST ile aşağıdaki değerleri göndererek bildirir. ThirdParty, NotifyPage’e gönderilen verilerin kendisine ulaştığını belirtmek için PayByMe’ye her koşulda (ücretlendirme Başarlı veya Başarısız) “OK” değerini response etmelidir. Bu response ulaşmadığı takdirde PayByMe aynı işlem için sonucu belirli aralıklarla göndermeye devam edecektir. Bu Server to Server gerçekleşen bir işlemdir.

Kullanıcıya hak verilmesi: NotifyPage’e bilgi, PayByMe Server’ından Thirdparty Server’ına doğru gelmektedir. Son kullanıcıların buraya erişememesi güvenlik açısından önemlidir. Bu sebeple sadece NotifyPage’e ödeme işleminin başarılı olduğu (status=1) bilgisi geldiğinde kullanıcıya hak verilmelidir.

$mySecretKey= 'secretKEy';
$status		= $_POST["status"];
$errorCode	= $_POST["errorCode"];
$errorDesc	= $_POST["errorDesc"];
$syncId		= $_POST["syncId"];
$price		= $_POST["price"];
$operatorId	= $_POST["operatorId"];
$secretKey	= $_POST["secretKey"];
$date		= date("Y:m:d H:i:s");
//SecretKey tanımlamalarla birlikte verilecektir
if($secretKey == $mySecretKey) {
                                                		if ($status == 1)
	{
		// Log success
	}
	else
	{
		// Log error
	}
	echo 'OK';
}
else
{
	echo 'Error!';
}

NotifyPage Server2Server requestlerin gerçekleştiği sayfa olup, kullanıcıya hakların verileceği sayfa burasıdır. Kullanıcı hak tanımlarını RedirectPage'de vermek güvenlik açığı oluşturacaktır.

ErrorCode

PaybyMe, ThirdParty tarafından gelecek requestlere ve de ödeme durumlarını belirlemek için çeşitli ErrorCodelarla sizi bilgilendirir.

PaybyMe tarafına yolladığınız her requestlerinize karşılık alacağınız responselarda ve NotifyPage inizde ödeme durumlarını belirlemek adına aşağıdaki ErrorCode değerleriyle karşılaşabilirsiniz.

ErrorCode Listesi
1000SUCCESS
1001Success Incomplete - Dept
2001Insufficient Credit
2002Invalid Account
2003Invalid Msisdn
2004Invalid Price
2005Charge Error
2006Quota Limit Error
2007MicroPayment Not Allowed
2008PRS Not Allowed
2009Invalid Parameter
2010Charge Connection Error
2011Invalid Pin/Tan
2012MicroPayment Not Active
2013Enterprise Not Allowed
2014Subscriber PaymentType Not Allowed
2601Invalid PIN
2602Max Try Exceeded
2603Invalid Captcha
2604Captcha Max Try Exceeded
3007Not Subscriber
3008Already Subscriber
5001Invalid User/Pass
5002Invalid Action
5501Fatal Error
5502IP Limit Exceeded
5503Msisdn Limit Exceeded
5504No Match
5505Time Out/User did not confirm payment
5506Cancelled By User
5507Gateway not active
5508Msisdn is in PayByMe blacklist
5509IP Blocked
5510Minute Base Operation Count Limit Exceeded