Use this skill for Share Commerce online payment gateway integration work (Share Commerce Sdn Bhd, Kuala Lumpur).
Source
Read references/share-commerce-api.md before giving factual API guidance or writing integration code. It holds the endpoint catalogue, every request/response field table, the SCSign algorithms per endpoint with verified worked examples, status/response code enums, payment method codes, and the documented doc inconsistencies.
Read references/account-setup.md when the user asks how to onboard, which credentials exist, where they come from, staging vs production, IP whitelisting, callback URL registration, plugins, or pricing.
Read references/source-map.md when choosing which official page or plugin file backs a fact, and for coverage notes.
Core Workflow
- Identify environment: staging (
stagingpayment.share-commerce.com) or production (payment.share-commerce.com). - Identify surface: hosted Payment Request (
/payment), Seemless iframe (/seemlesspayment), Pre-Auth (/CreateCheckout/PreAuth), Recurring (/CreateCheckout/Recurring), or a plugin. - Confirm onboarding: Merchant ID, Secret Key, and testing credentials per environment (emailed by Share Commerce), server IP whitelisted, callback URL registered with Share Commerce.
- Create a local pending order with a unique
MerchantOrderNobefore building the request. - Build the request server-side and compute
SCSignserver-side; never ship the Secret Key to the browser. - Send the browser to the gateway (auto-submitted form POST or GET URL), or redirect to the returned
CheckoutUrl. - Treat the browser return to
RedirectUrlas UX only, even though it is signed. - Verify the server-to-server callback
SCSignwith HMAC-SHA256 over the exact received values, then settle idempotently. - Use
/enquiry(or/PreAuth/Enquiry,/Recurring/Enquiry) as fallback when the callback is missing. - Re-check amount, currency,
MerchantOrderNo,MerchantID, andRespCode == "00"before marking paid.
Core Facts
- Staging base:
https://stagingpayment.share-commerce.com. Production base:https://payment.share-commerce.com. - Hosted payment:
GETorPOST /payment. Requery:POST /enquiry. Void (same day only):POST /Payment/Void. - Auth is
MerchantIDplus an HMAC-SHA256SCSignkeyed with the merchant Secret Key. No bearer token or API key header. - Form-style calls (
/payment,/seemlesspayment,/PreAuth,/CreateCheckout/PreAuth) carrySCSignas a field: HMAC of all field values concatenated in order, no separators. - JSON server calls (
/enquiry,/Payment/Void,/PreAuth/*,/CreateCheckout/Recurring,/Recurring/Enquiry) carrySCSignin an HTTP header: HMAC of the raw JSON body. PaymentMethodandVersioningare in the request sign string only when you send them (current plugins send both withVersioning=7).- Redirect (GET query) and callback (HTTP POST JSON) carry
SCSign: HMAC over the received values in order, excludingSCSign. - Response code
RespCode:00success,09pending,99failed,IEapplication error,10voided. - Amounts are ringgit decimals with 2 places (
Decimal(18,2), e.g.101.50), not sen. - Callback URL is not a request field; Share Commerce stores it at onboarding.
- No refund API is documented; only same-day
Payment/Void(full void, responseFULL_REFUNDED). - Official plugins: WooCommerce, OpenCart 3/4, Magento 2, PrestaShop 1.7 (github.com/share-commerce), EasyStore built in.
Critical Rules
- Keep the Secret Key server-side. Different keys for staging and production.
- Do not copy sample sign strings from the docs page: they contain hidden characters (a zero-width space in
https://, a non-breaking space in a description). - Sign the exact strings you send, in the exact order you send them. Do not reformat amounts (
101.50must stay101.50, not101.5). - For callbacks, verify over the raw JSON values as received; decoding numbers to floats changes
101.50to101.5in many languages. - Use constant-time comparison for SCSign (the official plugins use
==; do better). - Do not fulfil from the redirect alone; wait for a verified callback or a verified Enquiry result.
- Treat
RespCodeas a string ("00"). Exception:/CreateCheckout/PreAuthreturns integer1/9. Recurring/CreateCheckoutandCreateCheckout/PreAuthresponses are not signed; trust only later signed redirect/callback/enquiry data.- Settlement must be idempotent on
MerchantOrderNoplusTxnRefNo. - Some published sample hashes do not reproduce (see api reference). Prove your signer against staging before go-live.
Completion Criteria
A Share Commerce integration is done only when:
- Requests are built and signed server-side with the environment's Secret Key.
- Every request field is present (optional fields as empty strings) in the documented order.
- The callback handler verifies SCSign over the received values, constant-time, before any state change, and returns a 200 response (the official plugins reply
OK). - Settlement checks
MerchantID,MerchantOrderNo,TxnAmount,CurrencyCode,RespCode, and storesTxnRefNo. - Duplicate callbacks, redirect-after-callback, and Enquiry fallback are idempotent.
- Tests cover bad signature, tampered amount, wrong order number,
09pending,99failed,IE, and duplicate success. - Config documents
SHARECOMMERCE_MERCHANT_ID,SHARECOMMERCE_SECRET_KEY,SHARECOMMERCE_ENV, the redirect URL, and the callback URL registered with Share Commerce, per environment.
Loophole Review Loop
When asked whether a Share Commerce strategy is "100% confident", run this loop until no factual gaps remain:
- List trust boundaries: browser form/redirect, iframe postMessage, backend signer, Share Commerce gateway, callback receiver, raw-body parser, database, fulfilment job, void job, Enquiry poller, whitelisted IPs.
- Check bypasses: forged redirect query, forged postMessage, forged callback, signature over re-serialised JSON, float-formatted amount, wrong field order, missing optional field, sandbox/production key mix, reused
MerchantOrderNo, pending09treated as paid, void after day end, unsigned CreateCheckout response trusted. - Add fixes: server-side signing, raw-value verification, constant-time compare, strict amount/currency/order checks, durable event log, unique constraints, Enquiry fallback, per-environment config.
- Re-read
references/share-commerce-api.mdsections relevant to any gap. - State remaining uncertainty: unverified doc sample hashes, Payment Enquiry signing input, callback retry policy, seemless response
Signaturealgorithm, refund availability, pricing, and settlement timing must be confirmed with Share Commerce.