Transaction Notifications
Webhooks provide an efficient server-to-server real-time communication mechanism, allowing Oceanpayment to proactively send notification messages to your server when specific events occur—such as successful or failed payments, or other business transactions. Compared to polling, this approach is faster and more reliable.
Notification Types
Webhook notifications are triggered under the following conditions:
- Payment Status Notifications Updates on payment success, failure, etc.
- Business Order Notifications Updates for refunds, high-risk orders, disputes, chargebacks, fraudulent orders, or order adjustments.
- Customs Submission Notifications Updates related to customs submission results.
Key Features
- Notification Format:
xml； - Required Parameter:
noticeUrlfrom the transaction request. If not provided, no notifications will be sent. - Supported Ports: 80 and 443 only.
- CDN Considerations: Do not configure noticeUrl to point to a CDN-proxied address. CDN caching may prevent notifications from reaching your origin server. Use the direct server IP or a domain not accelerated by CDN.
Outbound IP Addresses
Merchants may whitelist the following Oceanpayment IPs if required:
- 153.254.110.82
- 218.213.69.2
- 52.77.42.94
- 52.220.14.99
- 183.47.51.150
- 47.76.241.251
- 203.131.246.62
Notification Flow
Notification Standards
All Webhook notifications follow the following general guidelines. Request method:
- HTTP Method:
POST - Content-Type:
application/xml - Encoding:
UTF-8
Validation Steps
- Retrieve the
signValuefrom the notification. - Calculate the signature according to the Payments and Business Orders signing rules.
- Compare the calculated signature with the signValue.
- If they match, the notification is valid and can be processed; return the plain text
receive-ok. - If they do not match, the notification may be tampered with or untrusted. Log the event, discard the notification, but still return receive-ok.
Retry Mechanism (Important)
To ensure reliability, Oceanpayment implements an automatic retry mechanism, with a maximum of 5 attempts.
| Retry | Interval from First Push | Description |
|---|---|---|
| 1 | Immediately after transaction | Initial push |
| 2 | 10 minutes | First retry |
| 3 | 30 minutes | Second retry |
| 4 | 60 minutes | Third retry |
| 5 | 24 hours | Final retry |
Notes
- Termination Condition: Once Oceanpayment receives the exact string receive-ok from your server after any push, the notification cycle ends.
- Final Termination: If no receive-ok is received after all 5 attempts, the cycle ends and no further pushes are made.
- Important: Returning anything other than the exact string receive-ok—including extra spaces, line breaks, JSON, or other content—will be treated as a failure and trigger the next retry.
Idempotency
Because retries may result in duplicate notifications, your processing logic must ensure idempotency.
Troubleshooting
| Issue | Possible Cause | Solution |
|---|---|---|
| No notifications received | • noticeUrl not provided• address inaccessible • server firewall blocks | • Ensure noticeUrl is set • test accessibility • check firewall/security group rules |
| Notifications stop after 5 retries | Server never returned receive-ok | • nsure the endpoint returns plain text receive-ok • check for server errors or 500 responses |
| Signature validation always fails | • Incorrect merchant key (secureCode) • parameter ordering or concatenation wrong • algorithm mismatch | • Confirm the correct key • follow signature generation rules strictly • ensure SHA256 algorithm is used |