paid-tw/skills

Overview

This skill implements PAYUNi webhook handling for payment notification endpoints. It provides signature (CheckCode) verification, replay-attack prevention, and order status update patterns you can drop into a PHP-based backend. The goal is a secure, testable webhook receiver that fits common frameworks and databases.

How this skill works

The skill shows how to parse incoming webhook payloads, compute and verify the CheckCode using HashKey/HashIV and SHA256, and compare signatures using a constant-time method to prevent timing attacks. It includes guidance for deduplicating webhooks by logging TradeNo or payload checksum, updating order records when Status is SUCCESS or FAIL, and exposing a health-check endpoint. It also outlines SQL schema and sample functions to check and mark processed webhooks.

When to use it

• You need a secure PAYUNi NotifyURL endpoint for production or testing.
• Integrating PAYUNi into an existing PHP app, API framework, or serverless function.
• You must validate payment notifications and prevent duplicate processing.
• Setting up local testing with ngrok or staging webhook flows.
• When you require clear logging and audit trails for payment callbacks.

Best practices

• Always validate CheckCode calculated from sorted params with HashKey/HashIV and SHA256.
• Use constant-time string comparison (timingSafeEqual equivalent) to avoid timing attacks.
• Record processed TradeNo or checksum in a persistent table to stop replay attacks.
• Serve webhook endpoints over HTTPS and restrict access where possible.
• Log raw webhook payloads and processing results for auditing and troubleshooting.

Example use cases

• A PHP e-commerce app that updates order status to 'paid' after PAYUNi notifies success.
• A microservice that receives PAYUNi webhooks, validates signatures, and dispatches events to an order-processing queue.
• A staging environment using ngrok to expose a local webhook endpoint for end-to-end testing.
• A merchant dashboard that reconciles incoming TradeNo values against stored orders and flags mismatches.
• A payments team implementing idempotent webhook handling by storing webhook_requests and skipping duplicates.