toyyibPay Payment Gateway

Use this skill for toyyibPay payment gateway integration work.

Source

Read references/toyyibpay-docs.md before giving factual API guidance or writing integration code. It contains source URLs, environment bases, endpoint map, callback hash rules, amount units, DuitNow QR fields, dashboard setup notes, pricing/support notes, WooCommerce setup notes, and WorkDo configuration notes from the provided docs plus follow-up source checks.

Read references/account-setup.md when user asks how to register, which API keys are needed, where credentials come from, or what dashboard setup is required.

Core Workflow

1. Identify environment: sandbox at dev.toyyibpay.com or production at toyyibpay.com.
2. Confirm credential scope: User Secret Key, Category Code, and optional Enterprise User Secret Key.
3. Create or reuse a toyyibPay Category, then create local pending payment before creating a Bill.
4. Create Bill server-side with fixed amount in cents, internal reference in billExternalReferenceNo, return URL, and callback URL.
5. Redirect customer to https://toyyibpay.com/{BillCode} or sandbox equivalent.
6. Verify callback hash with MD5(userSecretKey + status + order_id + refno + "ok").
7. Re-check payment using getBillTransactions when possible, then settle idempotently after status, amount, channel, provider, and reference match.

Core Facts

• Production API base: https://toyyibpay.com/index.php/api/
• Sandbox API base: replace toyyibpay.com with dev.toyyibpay.com and use sandbox credentials.
• Requests are POST; docs accept multipart/form-data or application/x-www-form-urlencoded.
• billAmount uses cents, for example 100 equals RM 1.00.
• Main flow: createCategory -> createBill -> hosted bill URL -> callback/return -> getBillTransactions.
• Payment status values in callbacks/return URLs: 1 success, 2 pending, 3 fail.
• getBillTransactions status filter values: 1 successful, 2 pending transaction, 3 unsuccessful, 4 pending.
• DuitNow QR requires account activation, enableDuitNowQR=1, and chargeDuitNowQR set when enabled.
• WorkDo-style setup usually needs Secret Key and Category Code.

Critical Rules

• Keep User Secret Key and Enterprise User Secret Key server-side only.
• Do not trust Return URL parameters for fulfilment; treat them as browser UX only.
• Reject callbacks when hash does not match the documented MD5 formula.
• Treat order_id as local external reference from billExternalReferenceNo; verify it maps to exactly one local pending payment.
• Verify callback amount and/or fetched billpaymentAmount against local expected amount before marking paid.
• Callback URL cannot be localhost; use public HTTPS or a tunnel for testing.
• Do not enable dynamic amount bills (billPriceSetting=0) for fixed-price orders unless local settlement can validate allowed amount.
• Do not invent payment channel availability, fees, card support, DNQR activation, settlement timing, or package limits. Verify live portal or current docs when these matter.

Loophole Review Loop

When asked whether a toyyibPay strategy is "100% confident", run this loop until no factual gaps remain:

1. List every trust boundary: browser return, backend checkout route, toyyibPay Bill API, callback receiver, database, fulfilment job, dashboard settings, and settlement report.
2. Check each bypass: fake success return, forged callback, MD5 hash mismatch, wrong order reference, wrong amount, wrong status, duplicated callback, pending marked as paid, dynamic amount over/underpayment, inactive/expired bill, sandbox/live credential mix, DNQR disabled account, missing public callback URL, and split-payment side effects.
3. Add fixes for each bypass: server-side Bill creation, local pending payment first, callback hash verification, transaction re-fetch, unique provider reference, strict amount/status checks, idempotent fulfilment, environment-separated config, expiry handling, and audit logs.
4. Re-read references/toyyibpay-docs.md sections relevant to any gap.
5. State remaining uncertainty explicitly if it depends on current account activation, dashboard package, payment channel enablement, pricing, settlement timing, or WorkDo product-specific settings.