@vonpay/test-cards

Canonical test card → outcome map for sandbox-embedded testing.

Internal workspace package. Not published to npm. Consumed by:

• @vonpay/vora-js — the sandbox iframe served at js.vonpay.com/v1/sandbox-iframe.html uses the allowlist to validate buyer-typed card numbers, and the outcome encoding to mint synthetic vp_pmt_test_* tokens.
• vonpay-checkout — the server-side mock binder uses decodeOutcome to read intent from the token prefix and emit the correct payment_intent.succeeded / .failed / .requires_action event with the documented decline reasons.

Both halves import from this package so the test-card allowlist + outcome mapping cannot drift.

Adding a new test card

1. Add the entry to TEST_CARDS in src/index.ts.
2. Update vonpay-docs/docs/reference/test-cards.md to document it (card number, brand, outcome, webhook event triggered).
3. Bump this package's version.
4. The shared constant flows automatically into both the iframe and the server-side binder on rebuild.

Why a shared package and not a hardcoded list in each repo

The iframe ships from js.vonpay.com (Cloudflare Worker + R2). The server-side binder ships from checkout.vonpay.com (Next.js on Vercel). If the two used independent lists, a card-number typo in either side would create a "field accepts but server rejects" or "field rejects but server would have accepted" divergence — silent dev-experience drift. Sharing the constants makes this class of bug a build error rather than a runtime mystery.

Safety locks

The allowlist is the load-bearing safety lock for the non-PCI sandbox iframe: real card numbers are NOT in the list, so even if a buyer typed one (against the iframe's UI guards), lookupTestCard() returns null and the mock never accepts a token mint based on real card data. Defense in depth — both the iframe-side validation AND the server-side token-mint endpoint check against the same list.