SyntaxilitY Ocean Payment Kit

A lightweight, production-ready integration kit for Ocean Payment Gateway.
This project provides secure checkout creation, signature generation, webhook handling, order verification, and payment status normalization.

It is designed for real-world e-commerce systems, SaaS platforms, and API-based payment infrastructures.

---

Features

• Secure Ocean Payment Checkout Creation
• SHA256 / HMAC Signature Support
• Webhook Verification (Fully Secure)
• Payment Status Normalization
• Order Tracking & Verification API
• Customer Tokenization (1-Click Payments)
• Inventory Reservation Flow Support
• Prisma-based persistence layer
• Socket.io real-time notifications support
• XML & JSON response handling

---

Payment Flow Overview

1. Create Checkout Order

Client sends:

POST /api/v1.0/payment/oceanpay/checkout

Request Payload

{
  "customerEmail": "john@example.com",
  "currency": "USD",
  "successUrl": "https://frontend.com/success",
  "cancelUrl": "https://frontend.com/cancel",
  "shipping": {
    "name": "John Doe",
    "phone": "+123456789",
    "address": {
      "line1": "Street 123",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "US"
    }
  },
  "items": [
    {
      "productId": 1,
      "name": "T-Shirt",
      "price": 10.99,
      "quantity": 2,
      "sku": "TS-001"
    }
  ]
}

---

Response

{
  "success": true,
  "message": "Ocean Payment created successfully",
  "data": {
    "paymentId": "OP123456",
    "orderNumber": "ORD-1700000000000",
    "amount": 21.98,
    "currency": "USD",
    "status": "pending",
    "checkout_url": "https://pay.oceanpayment.com/checkout",
    "isOneClick": false,
    "trackingId": "uuid-generated-id",
    "items": [
      {
        "name": "T-Shirt",
        "quantity": 2,
        "price": 10.99,
        "is_peptide": false,
        "images": []
      }
    ]
  }
}

---

2. Verify Payment Status

Client sends:

POST /api/v1.0/payment/oceanpay/verify

Request Payload

{
  "orderNumber": "ORD-1700000000000"
}

---

Response

{
  "success": true,
  "message": "Payment verified successfully",
  "data": {
    "paymentId": "OP123456",
    "orderNumber": "ORD-1700000000000",
    "amount": 21.98,
    "currency": "USD",
    "status": "paid",
    "trackingId": "uuid-generated-id",
    "items": [
      {
        "name": "T-Shirt",
        "quantity": 2,
        "price": 10.99,
        "is_peptide": false,
        "images": []
      }
    ]
  }
}

Payment Signature System

Signature Generation (Checkout)

Used before sending request to Ocean API.

account + terminal + backUrl + order_number + order_currency + order_amount
+ billing_firstName + billing_lastName + billing_email + secureCode

Example Output

SHA256: 8f2c3a91d0f5a9b...

---

Webhook Handling

Endpoint

POST /api/v1.0/webhook/oceanpay

---

Webhook Payload (XML or JSON)

<response>
  <account>12345</account>
  <terminal>67890</terminal>
  <order_number>ORD-123</order_number>
  <order_currency>USD</order_currency>
  <order_amount>21.98</order_amount>
  <payment_id>OP123456</payment_id>
  <payment_status>1</payment_status>
  <payment_details>80000:Transaction Approved</payment_details>
  <card_number>411111******1111</card_number>
</response>

---

Payment Status Mapping

Code	Status
1	paid
0	failed
6	processing
-1	pending

---

Webhook Response Logic

Success

{
  "success": true,
  "message": "receive-success"
}

---

Customer Tokenization (1-Click Payments)

If supported by Ocean:

Flow

1. First payment → token generated
2. Stored as:

oceanPaymentCustomerId

3. Next payment:

payMode: "token"
customer_id: "TOKEN_ID"

---

Inventory Handling

On Payment Success

• Stock is decremented
• Reserved stock is released

quantity: quantity - purchased
reserved: reserved - purchased

---

On Payment Failure

• Reserved stock is released only

---

Utilities Included

Signature Builders

• SHA256 Signature Generator
• HMAC SHA256 Generator
• Query Signature Builder

Helpers

• Location path builder
• Shipping normalizer
• Item formatter
• XML parser support

---

Security Features

• Request signature verification
• Webhook signature validation
• Input sanitization
• Ping-based gateway health check
• IP-safe request validation

---

Error Handling

Common Errors

Error	Reason
Invalid signValue	Signature mismatch
Order not found	Missing order in DB
Payment failed	Ocean response = 0
Unreachable gateway	Ping failure

---

Tech Stack

• Node.js
• Express.js
• Prisma ORM
• PostgreSQL
• Socket.io
• Axios
• XML2JS
• Crypto (Native)

---

License

MIT License

---

Author

Tariq Mehmood

http://github.com/TariqMehmood1004