Overview

A payment notification is sent when a user completes a payment, containing detailed information about the transaction.

Before You Begin

Note

Please refer to the Oceanpayment retry mechanism and guidelines.

Parameters

Parameter	Type	Description	Example
notice_type	string	Notification type Fixed value: transaction
push_dateTime	string	Time the notification is sent
response_type	string	Callback type 0: browser return 1: server async notification
account	string	Oceanpayment account number
terminal	string	Oceanpayment terminal number
signValue	string	Security signature used to verify transaction integrity, SHA256 encrypted
methods	string	Payment method
order_number	string	Merchant order number
card_country	string	Card issuing country
order_currency	string	Transaction currency Using ISO 4217 code
order_amount	string	Transaction amount Max 2 decimals，For example：1.00 If amount = 0, no transaction is sent
order_notes	string	Order notes, returned as-is
card_number	string	Card number First 6 and last 4 digits
card_type	string	Card type
payment_country	string	Customer IP country
payment_id	string	Oceanpayment unique payment ID
quickpay_id	string	QuickPay ID (UUID format) Only for Subscripions/QuickPay payments
payment_status	string	Transaction status -1: pending 0: failed 1: success
payment_authType	string	Transaction type 0: Sale 1: PreAuth non-3D 2: 3D non-PreAuth 3: 3D PreAuth
payment_details	string	Payment details Can be displayed to the customer
payment_solutions	string	Solutions for failed payment Can be displayed to the customer
payment_risk	string	Failed risk rules in format Rule=Score;Rule=Score;...
payment_amount	string	Actual paid amount by customer
payment_exchangeRate	string	Exchange rate
pay_barCode	string	Order barcode
auth_reason	string	PreAuth operation reason
order_operator	string	Operator handling pre-auth in backend
auth_code	string	Credit card authorization code Returned for Credit Card, ApplePay, GooglePay only
pay_userId	string	Customer ID
card_cvvResultCode	string	Returned CVV Code and Description

Payment Status

payment_status indicates the result of the transaction in the asynchronous notification. See the full payment status reference for details.

Response Code

payment_details provides the transaction details in the format Code, Code:Description.

Example XML Response

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <notice_type>transaction</notice_type>
    <push_dateTime></push_dateTime>
    <response_type>1</response_type>
    <account>995149</account>
    <terminal>99514901</terminal>
    <signValue>0B1FAEDCD3DE9FB72F13A0DB80955479B00F2E6F7A4BF5C84A3403C1EAE489BE</signValue>
    <methods>Credit Card</methods>
    <order_number>NO12345678</order_number>
    <card_type>Visa</card_type>
    <card_country>US</card_country>
    <order_currency>USD</order_currency>
    <order_amount>1.99</order_amount>
    <order_notes></order_notes>
    <card_number>411111***1111</card_number>
    <payment_country>CN</payment_country>
    <payment_id>180808092746539010540</payment_id>
    <payment_authType>0</payment_authType>
    <payment_status>1</payment_status>
    <payment_details>Successful test transaction</payment_details>
    <payment_solutions></payment_solutions>
    <payment_risk></payment_risk>
    <payment_amount>1.00</payment_amount>
    <payment_exchangeRate></payment_exchangeRate>
    <pay_userId></pay_userId>
    <pay_barCode>5b87b4528d3a66e4a59e51577960d552461c997a32c71e3c</pay_barCode>
    <auth_reason></auth_reason>
    <order_operator></order_operator>
</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['response_type'] = (string)$xml->response_type;
	$_REQUEST['account'] = (string)$xml->account;
	$_REQUEST['terminal'] = (string)$xml->terminal;
	$_REQUEST['payment_id'] = (string)$xml->payment_id;
	$_REQUEST['order_number'] = (string)$xml->order_number;
	$_REQUEST['order_currency'] = (string)$xml->order_currency;
	$_REQUEST['order_amount']= (string)$xml->order_amount;
	$_REQUEST['payment_status']= (string)$xml->payment_status;
	$_REQUEST['payment_details'] = (string)$xml->payment_details;
	$_REQUEST['signValue'] = (string)$xml->signValue;
	$_REQUEST['order_notes'] = (string)$xml->order_notes;
	$_REQUEST['card_number'] = (string)$xml->card_number;
	$_REQUEST['payment_authType'] = (string)$xml->payment_authType;
	$_REQUEST['payment_risk'] = (string)$xml->payment_risk;
	$_REQUEST['methods'] = (string)$xml->methods;
	$_REQUEST['payment_country'] = (string)$xml->payment_country;
	$_REQUEST['payment_solutions'] = (string)$xml->payment_solutions;
}

// 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
Payments	account+terminal+order_number+order_currency+order_amount+order_notes+card_number+payment_id +payment_authType+payment_status+payment_details+payment_risk+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['order_currency'].$_REQUEST['order_amount'].$_REQUEST['order_notes'].$_REQUEST['card_number'].$_REQUEST['payment_id'].$_REQUEST['payment_authType'].$_REQUEST['payment_status'].$_REQUEST['payment_details'].$_REQUEST['payment_risk'].$secureCode);
// Encrypted string validation
if (strtolower($local_signValue) == strtolower($_REQUEST['signValue'])) {
    if ($_REQUEST['payment_status'] == 1) {				 
    // Payment successful  	
    }elseif($_REQUEST['payment_status'] == 0){				 
    // Payment failed			 
    }elseif($_REQUEST['payment_status'] == -1){
       // Pending  
       if ($_REQUEST['payment_authType'] == 1){
         // Pre-authorization pending  				
       }else{	
         //Payment failed  
       }		
    }			 
}else{			 
  // Validation failed	  				 
}		
echo "receive-ok";
exit;