DengiOnline

2017-07-29 03:29:12

Payment Notification

Notification to URL

After receiving the notification of successful payment from the Payment System, the System notifies the Partner.

Project needs:

  • payment notification URL (specify in the Technical settings in the Merchant's personal account);
  • the handler to accept and recognize requests from the System and reply, how the System expects.

Parameters of Payment Notification Request

The System sends the request to the payment notification URL provided by the Project in the Technical settings during integration.

The System uses the following rules:

  • method - POST;
  • format - XML;
  • encoding - UTF-8.

Parameter

Description

Format

Mandatory

amount

Payment amount in RUB. If payment currency is not RUB, it is converted into RUB according to conversion rates on the day of payment notification. The payment amount may differ from the invoice amount.

To receive payment notifications in the invoice currency, contact the technical support specialists

decimal(10.2),

delimiter — decimal point

Yes

init_order_currency

Is equal to the the paymentCurrency parameter while it was sent in the invoice request

 

string(3),

ISO 4217 alfa-3

Yes

userid

User or Order ID (coincides with the nickname indicated in the invoice request)

string(256)

Yes

paymentid

Unique payment ID in the System

int(30)

Yes

key

Request signature. Formed as hash using MD5 algorithm. Consists of the following parameters (concatenated):

  • amount

  • userid

  • paymentid

  • secret key

md5(amount.userid.
paymentid.secret key)
For example: md5(5.00test_user123456
seсretkey)

Yes

paymode

Payment mode ID (coincides with mode_type in the invoice request)

int(10)

Yes

userid_extra

Additional information required for payment identification on the Project side (coincides with nick_extra in the invoice request)

NOTE! The parameter is not valid for payment kiosks networks

string(500)

No

orderid

Payment ID in the Project system (coincides with order_id in the invoice request)

NOTE! The parameter is not valid for payment kiosks networks

string(30)

Yes

 

amount_transfer

Payment amount in the system clearing currency

decimal(10.4)

No

Sent only when multi-currency account option is turned on

currency_transfer

System clearing currency

char(3),
ISO 4217 alfa-3

Parameters of the response

Every notification request from the System should be answered by the Project.

If there is no response, the notification request will be repeated. The period of repeated notification requests for each paymode may vary from 1.5 hours to 1 week. The request frequency varies from 1 to 30 minutes.

In certain cases when the Project response fails or has the NO value, some payment methods do not repeat payment requests. This procedure is based on specific payment system API features.

NOTE!

The minimal handler on the project side should check the value of incoming parameter paymentid.

  1. If the request contains the paymentid previously used in the Project system, the response is to contain the previous operation status.

  2. If the paymentid is used for the first time in the Project system, the response should indicate the possibility of accepting the payment.

Uniqueness of the requests should be guaranteed by the Project which also should return responses according to the payment status: notification requests from the System may be sent repeatedly.

If HTTP Status value in the response header is not equal to 200 (ОК), the request will be considered invalid regardless to its contents.

To send the response use the following rules:

  • method - POST;
  • format - XML;
  • encoding - UTF-8.
Parameter Description Format Mandatory

id

Payment ID in the Project system

string (64)

No

code

Response code

YES — notification accepted

NO — ID does not exist

YES/NO

(case-sensitive)

Yes

comment

Response code details 
The text depends on the Project.
The text will be shown at the System Partner Account.

string (400)

No

Response example

<?xml version="1.0" encoding="UTF-8"?> 
<result> 
  <id>666666</id> 
  <code>YES</code> 
</result>

Example code for a minimal request handler (PHP)

//Response generation 
function sendResponse($status, $message = ''){
    $response = '<?xml version="1.0" encoding="UTF-8"?>'."\n";
    $response .= '<result>'."\n"; 
        $response .= '<code>'.$status.'</code>'."\n"; 
    $response .= '<comment>'.$message.'</comment>'."\n";
    $response .= '</result>';
    die($response); 
} 
 
//Check for duplicate notifications 
function checkDuplicate($ODPaymentID){ 
    $sql = "SELECT status FROM billing_table WHERE od_payment_id = ".intval($ODPaymentID);
    $query = mysql_query($sql); 
    if(mysql_num_rows($query) == 0){ 
        return FALSE;
    } 
    $status = mysql_result($query, 0, 'status'); 
 
    //Payment was successful 
    if($status == 'SUCCESS'){ 
        return TRUE;
    } 
    else{ 
        return FALSE; 
    } 
} 
$secretKey = 'IT\'S_A_PROJECT_SECRET_WORD'; 
$projectHash = md5($_POST['amount'].$_POST['userid'].$_POST['paymentid'].$secretKey); 
if($projectHash != $_POST['key']){ 
    sendResponse('NO', 'Incorrect security signature');
} 

if(filter_var($_POST['amount'], FILTER_VALIDATE_FLOAT) && filter_var($_POST['paymentid'], FILTER_VALIDATE_INT) && floatval($_POST['amount']) > 0 && intval($_POST['paymentid']) > 0){ 
 
    //Request to accept the payment 
    if(!checkDuplicate($_POST['paymentid'])){ 
        //accepting payment towards the recipient 
        //sending current payment status 
        sendResponse(..., 'Current payment status'); 
    } 
    else{ sendResponse('YES', 'Payment already accepted');
    } 
}