Overview

Customs Upload Notification is an asynchronous notification sent by Oceanpayment to merchants after obtaining the customs upload result (approved or rejected).

Before You Begin

Information

Please refer to the complete 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's internal refund serial number
refund_reference	string	Merchant's internal refund reference number
notice_type	string	Business push type identityCheck: Identity verification customsUpload: Payment voucher upload result
push_status	string	Business result status 0: Failed 1: Successful
push_details	string	Detailed information of the push
push_id	string	Business status transaction ID, Oceanpayment unique ID • For refunds, equals the refund ID
verify_department	string	Verification authority
verify_id	string	Verification authority transaction serial number
sub_order_number	string	Merchant sub-order number, returned when orders are split

Notification Types

In the Customs Upload Notification parameters:

• notice_type: distinguishes the type of customs upload notification.
• push_status: indicates the result of the customs upload.
• push_details: provides detailed information about the customs upload.

Example XML Response

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <account>995149</account>
  <terminal>99514901</terminal>
  <signValue>0DB0C564E97C1459250333E67F1FCD8B0789BB1D2A3A0D87E878B1CC8A7485F6</signValue>
  <payment_dateTime>2024-11-24 19:43:27</payment_dateTime>
  <payment_debitTime>2024-11-24 19:43:27</payment_debitTime>
  <push_dateTime>2024-12-01 17:55:43</push_dateTime>
  <order_number>110529-EVEVSY11438</order_number>
  <order_currency>CNY</order_currency>
  <order_amount>0.01</order_amount>
  <order_notes></order_notes>
  <card_type></card_type>
  <card_country></card_country>
  <payment_id>211124194326789278592</payment_id>
  <refund_number></refund_number>
  <refund_reference></refund_reference>
  <notice_type>customsUpload</notice_type>
  <push_id></push_id>
  <push_status>1</push_status>
  <push_details>1:Success</push_details>
  <verify_department>OTHERS</payment_cpdTime>
  <verify_id>42000028632025091986588035</verify_id>
  <sub_order_number>110529-EVEVSY11438-1</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['verify_department'] = (string)$xml->verify_department;
	$_REQUEST['verify_id'] = (string)$xml->verify_id;
	$_REQUEST['sub_order_number'] = (string)$xml->sub_order_number;
}

// 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
Customs Submission	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'])) {
    //Notice type
    if ($_REQUEST['notice_type'] == 'identityCheck') {				 
       // identityCheck		
    }elseif{
       // customsUpload
    }			 
}else{			 
  // Validation failed	  				 
}		
echo "receive-ok";
exit;