en
en

How API Works?

When user starts the payment from the web-site, ThirdParty Company sends required parameters to PayByMe RequestPage over a HTTP request using HTTP POST. If the parameters are correct then PayByMe sends a response to ThirdParty as "Status=1&ErrorCode=1000&ErrorDesc=HashValue".

If it is taken Status=1 from response text and the payment is ready to process, ThirdParty redirects the user with the hash value which was taken in ErrorDesc to PaymentPage with the GET method and user arrives to PaymentPage.

If Status=0, ThirdParty redirects user to ErrorPage (No Redirection to PaymentPage) and does not start to payment process.

After payment user will be redirected to RedirectPage on ThirdParty’s side and the payment process will end.

PayByMe POSTs the result of the payment to the NotifyPage on ThirdParty’s side. PayByMe System expects ThirdParty Company to return “OK” string on response text, else PayByMe System will log the notification request as error and retries to notify after some time again.

API Guide

RequestPage, PaymentPage, RedirectPage and ErrorPage is a system which works together to charge and ends the payment process.

NotifyPage is a information system which sends notifications to ThirdParty about payment result. PaybyMe system can send payment notifications to NotifyPage url which is based on 80 or 443 ports.

These systems work independently from each other.

Request Page

ThirdParty Company sends required parameters to PayByMe RequestPage over a HTTP request using HTTP POST and starts the payment process.

After ThirdParty’s request to RequestPage, PayByMe sends a response text to define success or failure of the payment request.

If it is taken Status=1 from response text and the payment is ready to process, ThirdParty redirects the hash value which was taken in ErrorDesc to PaymentPage with the GET method and user arrives to PaymentPage. PaymentPage can be opened only with the hash value, otherwise it will not work.

If Status=0, ThirdParty redirects user to ErrorPage and does not start to payment process.

class Program
{
    static void Main(string[] args)
    {
    string RequestPageUrl = "Url will be given.";
    string payUrl = "Url will be given.";
    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);

Definitions of variables are done. Then these values are sent to the RequestPage Url on PaybyMe side via HTTP POST and response value is received.

Request Page

ThirdParty Company sends required parameters to PayByMe RequestPage over a HTTP request using HTTP POST and starts the payment process.

After ThirdParty’s request to RequestPage, PayByMe sends a response text to define success or failure of the payment request.

If it is taken Status=1 from response text and the payment is ready to process, ThirdParty redirects the hash value which was taken in ErrorDesc to PaymentPage with the GET method and user arrives to PaymentPage. PaymentPage can be opened only with the hash value, otherwise it will not work.

If Status=0, ThirdParty redirects user to ErrorPage and does not start to payment process.

$request_url	= 'URL will be given.';
$payment_url	= 'URL will be given.';
$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';

Definitions of variables are done. Then these values are sent to the RequestPage Url on PaybyMe side via HTTP POST and response value is received.

// 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 will redirect user to PaymentPage on PayByMe’s side to make payment. PaymentPage can be opened only with the hash value with GET method which received in ErrorDesc in RequestPage.

On this page PayByMe requires the related information (e.g. msisdn for mobile payment) from end-user and payment process begins.

Sample
//After making a request to the RequestPage on PaybyMe side with regarded datas, response gets parsed and the Hash value in ErrorDesc parameter is retrivied.

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 will redirect user to PaymentPage on PayByMe’s side to make payment. PaymentPage can be opened only with the hash value with GET method which received in ErrorDesc in RequestPage.

On this page PayByMe requires the related information (e.g. msisdn for mobile payment) from end-user and payment process begins.

Sample
//After making a request to the RequestPage on PaybyMe side with regarded datas, response gets parsed and the Hash value in ErrorDesc parameter is retrivied.

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

PayByMe System redirects the user to this page (when user close the payment page) just to inform the user about successful payment. RedirectPage is on ThirdParty’s side. It is only written information text like “Payment is successful” and absolutely shouldn’t be given credits to user on this page.

Redirect Page

PayByMe System redirects the user to this page (when user close the payment page) just to inform the user about successful payment. RedirectPage is on ThirdParty’s side. It is only written information text like “Payment is successful” and absolutely shouldn’t be given credits to user on this page.

Error Page

PayByMe System redirects the user to this page (when user close the payment page) just to inform about unsuccessful payment. ErrorPage is on ThirdParty’s side. It is only written information text like “Payment is unsuccessful”.

Notify Page

PaybyMe reports the result of the payment process to the ThirdParty’s NotifyPage by sending below values via HTTP POST. ThirdParty must respond with an "OK" value in each condition (Charging is successfull or unsuccessful) to indicate that the data sent to NotifyPage is received. If this response does not arrive, PayByMe will continue to send the result for the same transaction periodically. This is a Server to Server process.

Giving of benefits to the user: Information comes to the NotifyPage from PaybyMe Server to Thirdparty Server. It is important for security purposes that end user can not reach here. For this reason, benefits must only be given to the end user when the information is received in Status=1 state.

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 will be given.
    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 is the page where the Server2Server requests are made and the user is given the benefits. Giving user benefit qualifications in the RedirectPage will be a security breach.

Notify Page

PaybyMe reports the result of the payment process to the ThirdParty’s NotifyPage by sending below values via HTTP POST. ThirdParty must respond with an "OK" value in each condition (Charging is successfull or unsuccessful) to indicate that the data sent to NotifyPage is received. If this response does not arrive, PayByMe will continue to send the result for the same transaction periodically. This is a Server to Server process.

Giving of benefits to the user: Information comes to the NotifyPage from PaybyMe Server to Thirdparty Server. It is important for security purposes that end user can not reach here. For this reason, benefits must only be given to the end user when the information is received in Status=1 state.

$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 will be given.
if($secretKey == $mySecretKey) {
                                                		if ($status == 1)
	{
		// Log success
	}
	else
	{
		// Log error
	}
	echo 'OK';
}
else
{
	echo 'Error!';
}

NotifyPage is the page where the Server2Server requests are made and the user is given the benefits. Giving user benefit qualifications in the RedirectPage will be a security breach.

ErrorCode

PaybyMe notifies you with certain ErrorCodes for Thirdparty requests in order to determine Payment statuses.

You can receive below ErrorCode values in response for the requests you send to PaybyMe side and on your NotifyPage in order to determine payment statuses.

ErrorCode List
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