Refund

Those are the services managing the entire refund process for the payments made through the Payguru Payment Platform. All the refund process should be started by the merchant using the API components described below. Order Code is the main identifier for all the transactions to be refunded.

Get

It is the service enabling merchant to query Payguru Platform in order to access the refund details of a transaction by using the refund id generated by Payguru Platform and shared with the merchant beforehand.

>URL
 https://api.payguru.com/phs/refund/get
>HTTP Method
GET or POST
>Headers
FieldTypeDescription
merchantInteger - RequiredMerchant ID
tokenString - RequiredToken
>Parameters
FieldTypeDescription
idInteger - RequiredRefund ID
>Success
FieldTypeDescription
statusStringStatus Code: 000
messageStringMessage
dataArray[]Refund Detail
-idStringID
-merchantStringMerchant ID
-serviceStringService ID
-service_codeStringService ID
-transaction_idStringTransaction ID
-statusStringRefund Status #See
-create_timeStringCreate Time
-update_timeStringUpdate Time
-refund_timeStringRefund Time
-amountStringAmount
-refund_contactStringContact Name
-refund_ibanStringContact IBAN
-bank_idStringBank ID
-bank_nameStringBank ID
-bank_noStringBank ID
-bank_receipt_noStringBank Receipt No
>Error
FieldTypeDescription
statusStringStatus Code: #See
messageStringMessage
>Response Examples
{
    "status": "000",
    "message": "Success",
    "data": {
         "id": 13,
            "merchant_name": "PAYGURU DEMO",
            "merchant_id": 1,
            "service_name": "DEMO",
            "service_id": 4,
            "transaction_id": 28120,
            "status": 1,
            "create_time": "2018-01-18 13:48:39",
            "update_time": null,
            "refund_time": null,
            "amount": "0.50",
            "update_userid": null,
            "requested_by": null,
            "description": null,
            "note": null,
            "refund_contact": "Erdinç Karaman",
            "refund_iban": "TR800011100000000036888459",
            "bank_id": null,
            "bank_name": null,
            "bank_code": null,
            "bank_receipt_no": null
    }
}

{
    "status": "ERR_005",
    "message": "Invalid Service"
}
>Sample Codes
curl -X GET -H "token: {3E53E639-5173-D1B6-9368-68FCBCF72342}" -H "merchant: 123" --globoff "https://api.payguru.com/phs/refund/get?id=12345"

<?php
$curl = curl_init();
$url = "https://api.payguru.com/phs/refund/get";
$data = [
    "id"=>"12345",
];
$headers = [
    "token: {3E53E639-5173-D1B6-9368-68FCBCF72342}",
    "merchant: 123"
];
curl_setopt_array($curl, array(
  CURLOPT_URL => $url."?".http_build_query($data),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => $headers,
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

var client = new RestClient("https://api.payguru.com/phs/refund/get?id=12345");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "123");
request.AddHeader("token", "{3E53E639-5173-D1B6-9368-68FCBCF72342}");
IRestResponse response = client.Execute(request);
var o = JObject.Parse(response);
if (o["status"] == "000") {
    MessageBox.Show((string)o["data"]["id"]);
} else {
    MessageBox.Show((string)o["message"]);
}

import requests,json
url = "https://api.payguru.com/phs/refund/get"
querystring = {"id":"12345"}
headers = {
    "token": "{3E53E639-5173-D1B6-9368-68FCBCF72342}",
    "merchant": "123"
}
response = requests.request("GET", url, headers=headers, params=querystring)
if response.status_code == 200:
    o = json.loads(response.text)
    if o["status"] == "000":
        print o["data"]["id"]
    else:
        print o["message"]
else:
    print "Request Error"

Get By Order

It is basically the same service as the GET but using the order code instead of refund id. It enables the merchant to query the refund status of a particular order that could consist of more than one sub-orders, mainly in Market Place implementations. Since a unique order id may consist of multiple purchases from multiple sub-merchants under the same market place, this query may bring more than one refund records.

>URL
 https://api.payguru.com/phs/refund/getByOrder
>HTTP Method
GET or POST
>Headers
FieldTypeDescription
merchantInteger - RequiredMerchant ID
tokenString - RequiredToken
>Parameters
FieldTypeDescription
orderString - RequiredMerchant Order
>Success
FieldTypeDescription
statusStringStatus Code: 000
messageStringMessage
dataArray[]Refunds Detail
-idStringID
-merchantStringMerchant ID
-serviceStringService ID
-service_codeStringService ID
-transaction_idStringTransaction ID
-statusStringRefund Status #See
-create_timeStringCreate Time
-update_timeStringUpdate Time
-refund_timeStringRefund Time
-amountStringAmount
-refund_contactStringContact Name
-refund_ibanStringContact IBAN
-bank_idStringBank ID
-bank_nameStringBank ID
-bank_noStringBank ID
-bank_receipt_noStringBank Receipt No
>Error
FieldTypeDescription
statusStringStatus Code: #See
messageStringMessage
>Response Examples
{
    "status": "000",
    "message": "Success",
    "data": [
         {
            "id": 13,
            "merchant_name": "PAYGURU DEMO",
            "merchant_id": 1,
            "service_name": "DEMO",
            "service_id": 4,
            "transaction_id": 28120,
            "status": 1,
            "create_time": "2018-01-18 13:48:39",
            "update_time": null,
            "refund_time": null,
            "amount": "0.50",
            "requested_by": null,
            "description": null,
            "note": null,
            "refund_contact": "Payguru Test",
            "refund_iban": "TR12345678",
            "bank_id": null,
            "bank_name": null,
            "bank_code": null,
            "bank_receipt_no": null
         },
         {
            "id": 14,
            "merchant_name": "PAYGURU DEMO",
            "merchant_id": 1,
            "service_name": "DEMO",
            "service_id": 4,
            "transaction_id": 28120,
            "status": 2,
            "create_time": "2018-01-18 15:09:08",
            "update_time": "2018-01-19 15:09:08",
            "refund_time": null,
            "amount": "0.40",
            "requested_by": null,
            "description": null,
            "note": null,
            "refund_contact": "Payguru Test",
            "refund_iban": "TR12345678",
            "bank_id": null,
            "bank_name": null,
            "bank_code": null,
            "bank_receipt_no": null
        },
        {
            "id": 15,
            "merchant_name": "PAYGURU DEMO",
            "merchant_id": 1,
            "service_name": "DEMO",
            "service_id": 4,
            "transaction_id": 28120,
            "status": 3,
            "create_time": "2018-01-18 15:09:08",
            "update_time": "2018-01-19 15:09:08",
            "refund_time": "2018-01-19 09:00:00",
            "amount": "5",
            "requested_by": null,
            "description": "Complated at 09:00",
            "note": null,
            "refund_contact": "Payguru Test",
            "refund_iban": "TR12345678",
            "bank_id": 1,
            "bank_name": "Ziraat",
            "bank_code": "ziraatbank",
            "bank_receipt_no": "DEKONT1234"
        }
    ]
}

{
    "status": "ERR_005",
    "message": "Invalid Service"
}
>Sample Codes
curl -X GET -H "token: {3E53E639-5173-D1B6-9368-68FCBCF72342}" -H "merchant: 123" --globoff "https://api.payguru.com/phs/refund/getByOrder?order=12345"

<?php
$curl = curl_init();
$url = "https://api.payguru.com/phs/refund/getByOrder";
$data = [
    "order"=>"12345",
];
$headers = [
    "token: {3E53E639-5173-D1B6-9368-68FCBCF72342}",
    "merchant: 123"
];
curl_setopt_array($curl, array(
  CURLOPT_URL => $url."?".http_build_query($data),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => $headers,
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

var client = new RestClient("https://api.payguru.com/phs/refund/getByOrder?order=12345");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "123");
request.AddHeader("token", "{3E53E639-5173-D1B6-9368-68FCBCF72342}");
IRestResponse response = client.Execute(request);
var o = JObject.Parse(response);
if (o["status"] == "000") {
    MessageBox.Show((string)o["transaction"]["id"]);
} else {
    MessageBox.Show((string)o["message"]);
}

import requests,json
url = "https://api.payguru.com/phs/refund/getByOrder"
querystring = {"order":"12345"}
headers = {
    "token": "{3E53E639-5173-D1B6-9368-68FCBCF72342}",
    "merchant": "123"
}
response = requests.request("GET", url, headers=headers, params=querystring)
if response.status_code == 200:
    o = json.loads(response.text)
    if o["status"] == "000":
        print o["data"][0]["id"]
    else:
        print o["message"]
else:
    print "Request Error"

Create

It is the web service that creates a refund request. Merchant is expected to call this service to start a refund process for the transactions that are not "completed" or for the "purchase orders not fullfilled" yet.

>URL
 https://api.payguru.com/phs/refund/create
>HTTP Method
GET or POST
>Headers
FieldTypeDescription
merchantInteger - RequiredMerchant ID
tokenString - RequiredToken
>Parameters
FieldTypeDescription
codeString - RequiredService Code
amountString - RequiredAmount
orderString - RequiredMerchant Order
contactArray[] - RequiredContact Fields
-nameString - RequiredName
-ibanString - RequiredIBAN
>Success
FieldTypeDescription
statusStringStatus Code: 000
messageStringMessage
refund_idIntegerPayguru Refund ID
>Error
FieldTypeDescription
statusStringStatus Code: #See
messageStringMessage
>Response Examples
{
    "status": "000",
    "message": "Success",
    "refund_id": "123412345678",
}

{
    "status": "ERR_005",
    "message": "Invalid Service"
}
>Sample Codes
curl -X GET -H "token: {3E53E639-5173-D1B6-9368-68FCBCF72342}" -H "merchant: 123" --globoff "https://api.payguru.com/phs/refund/create?code=XXX&order=ORDER&contact[name]=Qwe ASD&contact[iban]=TR12345671234567&amount=1.00"

<?php
$curl = curl_init();
$url = "https://api.payguru.com/phs/refund/create";
$data = [
    "code"=>"XXX",
    "order"=>"ORDER",
    "contact"=>["name"=>"Qwe ASD","iban"=>"TR12345671234567"],
    "amount"=>1.00,
];
$headers = [
    "token: {3E53E639-5173-D1B6-9368-68FCBCF72342}",
    "merchant: 123"
];
curl_setopt_array($curl, array(
  CURLOPT_URL => $url."?".http_build_query($data),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => $headers,
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo json_decode($response,true)["refund_id"];
}

var client = new RestClient("https://api.payguru.com/phs/refund/create?code=XXX&order=ORDER&contact[name]=QweASD&contact[iban]=TR12345671234567&amount=1.00");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "123");
request.AddHeader("token", "{3E53E639-5173-D1B6-9368-68FCBCF72342}");
IRestResponse response = client.Execute(request);
var o = JObject.Parse(response);
if (o["status"] == "000") {
    MessageBox.Show((string)o["refund_id"]);
} else {
    MessageBox.Show((string)o["message"]);
}

import requests,json
url = "https://api.payguru.com/phs/refund/create"
querystring = {"code":"XXX","order":"ORDER","contact[name]":"Qwe ASD","contact[iban]":"TR12345671234567","amount":"1.00"}
headers = {
    "token": "{3E53E639-5173-D1B6-9368-68FCBCF72342}",
    "merchant": "123"
}
response = requests.request("GET", url, headers=headers, params=querystring)
if response.status_code == 200:
    o = json.loads(response.text)
    if o["status"] == "000":
        print o["data"][0]["id"]
    else:
        print o["message"]
else:
    print "Request Error"

Refund Notification

This service is used to transmit the results to the merchant of all the refund requests within a day. All the refunds made during that day are sent to the merchant with a single call to the notification url on the merchant platform.

>URL
 http://yoursite.com/PhsRefundNotifyService
>HTTP Method
GET or POST/JSON

Notify Key: md5( Service code + Merchant ID + Refund ID + Payguru Reference Code(Code In Request) + Order RefNo + Amount + Bank Code + Merchant Private Key + Service Private Key)

>Parameters
FieldTypeDescription
refund_idIntegerRefund ID
codeStringPayguru Order
orderStringMerchant Order
statusIntegerRefund Status #See
amountFloatRefund Amount
refund_contactStringRefund Contact Name
refund_ibanStringRefund Contact IBAN
refund_dateDateRefund Date
create_timeDateRefund Request Date
bank_noIntegerBank No
bank_idIntegerBank ID
bank_nameStringBank Name
bank_codeStringBank Code
bank_receipt_noString - RequiredBank Receipt No
keyString - RequiredRefund Notify Key #See
>Sample Codes
<?
$data = $_GET;
//$data["refund_id"] = Refund ID
//$data["code"] = Transaction Code
//$data["order"] = Order Refno
//$data["status"] = Refund Status
//$data["amount"] = Refund Amount
//$data["refund_contact"] = Refund Contact Name
//$data["refund_iban"] = Refund Contact IBAN
//$data["refund_date"] = Refund Date
//$data["create_time"] = Refund Request Date
//$data["bank_no"] = Bank No
//$data["bank_id"] = Bank ID
//$data["bank_name"] = Bank Name
//$data["bank_code"] = Bank Code
//$data["bank_receipt_no"] = Bank Receipt No
//$data["key"] = Notify Key
$localKey = md5("Service Code"."Merchant ID".$data["refund_id"].$data["code"].$data["order"].$data["amount"].$data["bank_code"]."Merchant Private Key"."Service Private Key");
if($localKey = $data["key"]){
     echo "OK";//If you accept this request, you must response with "OK"
//find transaction with order
}else{
    echo "Wrong Data";
}

<?
$data = json_decode(file_get_contents("php://input"),true);
//$data["refund_id"] = Refund ID
//$data["code"] = Transaction Code
//$data["order"] = Order Refno
//$data["status"] = Refund Status
//$data["amount"] = Refund Amount
//$data["refund_contact"] = Refund Contact Name
//$data["refund_iban"] = Refund Contact IBAN
//$data["refund_date"] = Refund Date
//$data["create_time"] = Refund Request Date
//$data["bank_no"] = Bank No
//$data["bank_id"] = Bank ID
//$data["bank_name"] = Bank Name
//$data["bank_code"] = Bank Code
//$data["bank_receipt_no"] = Bank Receipt No
//$data["key"] = Notify Key
$localKey = md5("Service Code"."Merchant ID".$data["refund_id"].$data["code"].$data["order"].$data["amount"].$data["bank_code"]."Merchant Private Key"."Service Private Key");
if($localKey = $data["key"]){
    echo "OK";//If you accept this request, you must response with "OK"
//find transaction with order
}else{
    echo "Wrong Data";
}