Skip to content

Phase 3: stop implying kiosk/BNPL block go-live - #12

Merged
MRagabMob merged 1 commit into
mainfrom
phase3-untestable-methods
Aug 13, 2026
Merged

MRagabMob merged 1 commit into
mainfrom
phase3-untestable-methods

Conversation

@MRagabMob

Copy link
Copy Markdown
Collaborator

Phase 3 told merchants to go live "only after a full successful test run" — an exit criterion that, for kiosk and BNPL, could never be met, since sandbox cannot test those methods at all (confirmed by Paymob, recorded in #8).

What changed

Per Paymob: a card test is sufficient, and kiosk/BNPL must not block launch. That's correct and this repo already contains the reason — universal-prompt.md:209: "All methods go through the Intention API — there are no separate wallet/kiosk payment endpoints." Same Intention API, same Unified Checkout, same callback + HMAC path, so a passing card run validates effectively all of the merchant's own integration code.

Phase 3 now says that plainly: enable the remaining methods in the Dashboard and go live. The old test-credentials.md wording was worse than Phase 3 — it sent merchants to their account manager as though verification were a prerequisite — and is corrected to match.

What it stops short of claiming

It does not say the other methods are therefore verified, because hmac-verification.md:63 says the opposite:

"wallets and cards can return slightly different nested shapes"

and the HMAC concatenation includes the card-shaped source_data.pan / source_data.sub_type / source_data.type. A kiosk payment is cash at an outlet — there is no PAN. If those fields come back differently, the merchant's computed HMAC doesn't match, the callback is rejected, and a genuinely paid order never completes.

Worth being precise about the direction: that's lost revenue and support load, not a security hole — a shape mismatch causes over-rejection, never acceptance of a forged callback. And it costs about five minutes per method to rule out.

So step 7 lists four things a card test doesn't cover, to check on the first real transaction for each newly enabled method rather than before go-live:

  1. Integration ID — per-method, must be enabled on the account in the matching mode. Fails loudly with 404, so low risk.
  2. Callback field shape — log the first real callback per method, confirm the HMAC still matches.
  3. Kiosk settles asynchronously — the callback can arrive hours or days later, or never. Expect long-lived pending orders and lean on Transaction Inquiry rather than treating pending as failed. A card test never exercises this path, because cards settle at checkout.
  4. Refunds — kiosk and most BNPL don't support them (advanced-features.md:37), so don't ship a refund path that assumes they do.

Net effect: the guidance goes from "you cannot satisfy this, good luck" to "launch, then spend five minutes on your first live transaction per method."

Scope

  • SKILL.md Phase 3 only — the old step 7 becomes step 8, unchanged in substance. No payment logic, HMAC spec, endpoint, or safety rule touched.
  • references/test-credentials.md — the two "what that means in practice" bullets, aligned with Phase 3. The confirmed fact that kiosk/BNPL have no sandbox path is unchanged.
  • The ?partner=claude parameter is untouched.

Test plan

  • python scripts/validate.py passes, including the safety-contract term checks over SKILL.md
  • No "not achievable" / account-manager-prerequisite framing left anywhere in skills/
  • Phase 3 renumbers cleanly 1–8

Still open, unchanged by this PR

Apple Pay, Google Pay, and bank installments remain labelled "not confirmed either way" in test-credentials.md. Your note that a working card integration implies the others work covers the shared path, which is now stated — but whether those three have a sandbox path at all is still unanswered, so nothing is asserted about it.

Phase 3's exit criterion read as universal — "only after a full
successful test run" — while sandbox cannot test kiosk or BNPL at all,
so a merchant enabling either had an exit criterion they could never
meet. The earlier test-credentials.md wording made it worse by sending
them to their account manager as though verification were a prerequisite.

Per Paymob: a card test is sufficient. Every method uses the same
Intention API, Unified Checkout, and callback + HMAC path, so a passing
card run validates effectively all of the merchant's own code. Phase 3
now says that plainly and tells them to enable the rest and launch.

It does not claim the other methods are therefore fully verified, because
hmac-verification.md says wallets and cards return slightly different
nested shapes and the concatenation includes the card-shaped
source_data.pan/sub_type/type. A kiosk cash payment has no PAN, so a
shape difference makes the merchant's HMAC not match and a genuinely paid
order gets rejected. That is lost revenue, not a security hole, and it
costs five minutes to rule out. So step 7 lists four things to check on
the first real transaction per method rather than before go-live:
Integration ID, callback field shape, kiosk's asynchronous settlement,
and refund support.
@MRagabMob
MRagabMob merged commit 2f16bcb into main Aug 13, 2026
1 check passed
@MRagabMob
MRagabMob deleted the phase3-untestable-methods branch August 13, 2026 16:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant