Overview

Business Order Notifications provide detailed information when an order encounters an exception, such as a refund, high-risk order, chargeback, dispute, or fraud.

Before You Begin

Information

Please refer to the complete Oceanpayment retry mechanism and guidelines.

Parameter	Type	Description	Example
account	string	Oceanpayment account number
terminal	string	Oceanpayment terminal number
signValue	string	Security signature used to verify transaction integrity, SHA256 encrypted
payment_dateTime	string	Order payment time
payment_debitTime	string	Completion time
push_dateTime	string	Push time
order_number	string	Website order number
order_currency	string	Order transaction currency, using ISO 4217 code
order_amount	string	Order amount, supports up to 2 decimal places, e.g., 1.00
order_notes	string	Order notes, returned as-is
card_type	string	Card type
card_country	string	Card issuing country
payment_id	string	Payment ID, unique Oceanpayment transaction number
refund_number	string	Merchant internal refund serial number
refund_reference	string	Merchant internal refund reference number
notice_type	string	Business push type refund: Full refund partialRefund: Partial refund chargeBack: Chargeback re-presentment: Dispute retrieval: Retrieval request reversal-retrieval: Reversal retrieval fraud: Fraud ARN: Refund proof highRisk: High-risk order
push_status	string	Business result status 0: Failed 1: Successful 2: In dispute (only for notice_type re-presentment)
push_details	string	Detailed information of the push
push_id	string	Business status transaction ID,Oceanpayment unique ID For refunds, equals the refund ID
payment_cpdTime	string	Exception occurrence time Returned when notice_type is chargeBack, fraud, re-presentment, or retrieval Typically represents the time the exceptional order occurred

Notification Types

In the Business Order Notification parameters:

• notice_type: distinguishes the type of order exception.
• push_status: indicates the result of the exception notification.
• push_details: provides detailed information about the exception.
• payment_cpdTime: indicates when the exception occurred.

Note

This notification is for business order events. To take action on the exception, please access your Oceanpayment account backend.

Example XML Response

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <account>995149</account>
  <terminal>99514901</terminal>
  <signValue>0DB0C564E97C1459250333E67F1FCD8B0789BB1D2A3A0D87E878B1CC8A7485F6</signValue>
  <payment_dateTime>2021-11-24 19:43:27</payment_dateTime>
  <payment_debitTime>2021-11-24 19:43:27</payment_debitTime>
  <push_dateTime>2021-12-01 17:55:43</push_dateTime>
  <order_number>110529-EVEVSY11438</order_number>
  <order_currency>USD</order_currency>
  <order_amount>0.01</order_amount>
  <order_notes></order_notes>
  <card_type>Maestro</card_type>
  <card_country>IT</card_country>
  <payment_id>211124194326789278592</payment_id>
  <refund_number></refund_number>
  <refund_reference></refund_reference>
  <notice_type>Refund</notice_type>
  <push_id>5433634</push_id>
  <push_status>1</push_status>
  <push_details>Others</push_details>
  <payment_cpdTime>2021-11-24 19:43:27</payment_cpdTime>
</response>

Receiving Example

Notifications are sent to the noticeUrl provided in the transaction request.

PHP

// Get XML of push input stream
$xml_str = file_get_contents("php://input");
// Check whether the returned input stream is XML 
if(xml_parser($xml_str)){
	$xml = simplexml_load_string($xml_str);		
	// Assign the push parameters to $_REQUEST
	$_REQUEST['account'] = (string)$xml->account;
	$_REQUEST['terminal'] = (string)$xml->terminal;
	$_REQUEST['signValue'] = (string)$xml->signValue;
	$_REQUEST['payment_dateTime'] = (string)$xml->payment_dateTime;
	$_REQUEST['payment_debitTime'] = (string)$xml->payment_debitTime;
	$_REQUEST['push_dateTime'] = (string)$xml->push_dateTime;
	$_REQUEST['order_number'] = (string)$xml->order_number;		
	$_REQUEST['order_currency'] = (string)$xml->order_currency;	
	$_REQUEST['order_amount']= (string)$xml->order_amount;
	$_REQUEST['order_notes'] = (string)$xml->order_notes;
	$_REQUEST['card_type'] = (string)$xml->card_type;
	$_REQUEST['card_country'] = (string)$xml->card_country;		
	$_REQUEST['payment_id'] = (string)$xml->payment_id;
	$_REQUEST['refund_number']= (string)$xml->refund_number;
	$_REQUEST['refund_reference'] = (string)$xml->refund_reference;	
	$_REQUEST['notice_type'] = (string)$xml->notice_type;		
	$_REQUEST['push_id'] = (string)$xml->push_id;
	$_REQUEST['push_status'] = (string)$xml->push_status;
	$_REQUEST['push_details'] = (string)$xml->push_details;
	$_REQUEST['payment_cpdTime'] = (string)$xml->payment_cpdTime;
}

// Check whether it is XML
function xml_parser($str){
	$xml_parser = xml_parser_create();
	if(!xml_parse($xml_parser,$str,true)){
		xml_parser_free($xml_parser);
		return false;
	}else {
		return true;
	}
}

Signature Security Verification

Type	Signature Structure
Business Orders	account+terminal+order_number+payment_id+refund_number+push_id+push_status+push_details+secureCode

Signature Verification Example

PHP

$_REQUEST['signValue'] = (string)$xml->signValue;

// Get the local secureCode value  
$secureCode = {secureCode};  
$local_signValue = hash("sha256",$_REQUEST['account'].$_REQUEST['terminal'].$_REQUEST['order_number'].$_REQUEST['payment_id'].$_REQUEST['refund_number'].$_REQUEST['push_id'].$_REQUEST['push_status'].$_REQUEST['push_details'].$secureCode);
// Encrypted string validation
if (strtolower($local_signValue) == strtolower($_REQUEST['signValue'])) {
    // Business order type
    if ($_REQUEST['notice_type'] == 'Refund') {				 
       // Refund	
    }elseif{
       // Other types, etc.
    }			 
}else{			 
  // Validation failed	  				 
}		
echo "receive-ok";
exit;