Developer docs

gFinOS Tap — native card protocol

The gFinOS card runs entirely on our own rails. Any NFC-capable smartphone can pay — no Apple Wallet, no Google Wallet, no third-party issuer required. External providers are optional add-ons, never dependencies.

How a tap actually works

1. Mint. The payer calls mintTapToken. The server returns a signed HMAC-SHA256 payload capturing { card, user, currency, cap, nonce, exp, deviceHash }.
2. Broadcast. On Android Chrome we write the token to an NDEF url record via the Web NFC API — the phone becomes an NFC tag. On iOS or older phones the identical token is displayed as a QR code. Both paths carry the same signed bytes.
3. Read. The merchant terminal (any device with NFC or a camera) reads the token, adds its own ARQC challenge(sandbox EMV, HMAC-SHA256 over UN + ATC + amount + currency + pairing code).
4. Verify. verifyTapAndAuthorize checks signature, expiry, per-card daily limit, terminal ARQC, device velocity (5 taps / 5 min triggers step-up), and mints a card authorization.
5. Capture & settle. Immediate or delayed capture debits the payer wallet in local platform currency, contributes 0.5% to the Cooperative Treasury, and emits tap.verified, tap.authorization_created, tap.captured, tap.failed webhooks.

Phone compatibility matrix

Device	Path	Wallet app needed?
Android + Chrome/Edge (NFC)	Web NFC (NDEF)	No
Android without NFC	On-screen QR	No
iOS (any Safari)	On-screen QR	No
Feature phones w/ camera scanner	QR	No
Any phone paired to gFinOS POS	Sandbox EMV / ARQC	No

Provider strategy — native default, third-parties optional

1 of 6 providers active. The native rail is guaranteed; everything else is off unless explicitly enabled.

gFinOS Native (JVDEGCR)
issue · authorize · capture · refund · void · dispute · nfc_tap · 3ds_step_up · settlement
Fully in-platform. Works on any NFC-capable Android via Web NFC and on any phone at all via the QR fallback. No wallet app required.
Active
Apple Wallet Pass (optional)
wallet_pass
Adds an iOS Wallet pass for convenience. Payment still runs on gFinOS.
Optional (off)
Google Wallet Pass (optional)
wallet_pass
Optional (off)
Samsung Wallet Pass (optional)
wallet_pass
Optional (off)
Stripe Issuing (optional, external rail)
issue · authorize · capture · refund · settlement
Only used if a customer explicitly wants a Visa/MC-branded card.
Optional (off)
Marqeta (optional, external rail)
issue · authorize · capture · refund · settlement
Optional (off)

Security model

Tokens are HMAC-SHA256 signed with a server-only key; the client never sees the secret.
Every token is single-use and expires in 15–600 seconds.
Amount is capped at mint time — merchants can never charge above the cap.
Device fingerprint travels inside the token; new devices trigger 6-digit step-up.
Terminal pairing uses a per-device secret; ARQC round-trip binds amount + currency + counter.
Every step emits an audit_events row and a signed settlement hash on the gFinOS ledger.

Try tap →API reference