Skip to main content

Overview​

Oceanpayment APIs use SHA256 signatures to ensure the integrity and authenticity of data. Each request includes a SHA256 hash of key parameters, and the receiver verifies the returned signature to confirm that the data has not been altered during transmission.

Note
  • The structure for generating and verifying signatures differs between integration types, such as Payments and Order Management.
  • Key Management: The secureCode—used for signature generation and verification—must be stored securely. It should never be exposed to the client or any insecure environment. Always obtain it through official Oceanpayment channels.

Signature Generation Steps (Merchant Side)​

When sending a request to the Oceanpayment gateway, merchants should generate the signValue as follows:

  1. Prepare Parameters: Collect all non-empty request parameters that need to be included in the signature. Be mindful of special characters that may affect hashing.
  2. Concatenate Parameters: Combine the parameters into a single string according to the signature rules for your integration type Payments or Order Management.
  3. Compute Hash: Generate the SHA256 hash of the concatenated string and include it in your request to the Oceanpayment gateway.

Signature Verification Steps (Merchant Side)​

1.Upon receiving a response or notification from Oceanpayment, merchants must verify the authenticity of the data to ensure it originates from Oceanpayment and has not been tampered with:

  • Retrieve or parse all parameters returned by Oceanpayment.
  • Compute your own hash value using the same signature generation rules and compare it with the returned signValue.
  • If the values match, the verification is successful, confirming the data is authentic and untampered.
  • If they do not match, the data may have been altered or is untrustworthy, and should be treated as invalid.

2.Signature verification occurs in three main scenarios:

  • Real-time response verification :
    • Typically performed on the backend when receiving pay_url or MOTO_url. This is not the final payment result (which may require redirecting to the payment or 3D verification page).
    • It can also apply when receiving XML payment results directly.
    • Order Management API responses also require verification.
  • Synchronous response verification (backUrl):
    • When receiving synchronous responses via backUrl, verify the signature using form data.
    • The signature structure is fixed across all integration methods.
  • Asynchronous notification (noticeUrl):
    • For webhook notifications, refer to the Webhook verification guide.

Handling Special Characters​

To ensure consistent signature verification, all fields included in the signature must meet the following requirements; otherwise, the generated signatures may not match:

  • Trim leading and trailing whitespace and escape or replace special characters, including double quotes ("), less-than (<), greater-than (>), and single quotes (').
  • Concatenate fields strictly following the order defined by Oceanpayment.
//PHP
function OceanHtmlSpecialChars($parameter){
  // Trim leading and trailing whitespace
  $parameter = trim($parameter); 
  // Replace symbols with empty string
  $parameter = str_replace(array("<",">","'","\""),array(" "," "," "," "),$parameter); 
  return $parameter;
}

Hash Signature Example​

//PHP
$signValue = hash("sha256",$account.$terminal.$backUrl.$order_number.$order_currency.$order_amount.$billing_firstName.$billing_lastName.$billing_email.$secureCode);