@validpay/react-native-sdk

Official React Native SDK for the ValidPay document verification API. AES-256-GCM client-side encryption, End-Cell issuance (blind rail) — a 3-of-3 XOR key split across the QR, the platform, and the independent KeyHalve rail, so no single party can read or reassemble the key — eight patented protections, and zero runtime dependencies.

The wire format is byte-compatible with the Python SDK and the Node SDK — an intent created with any ValidPay SDK can be verified with any other.

Installation

npm install @validpay/react-native-sdk

Setup — pluggable crypto backend

React Native does not include Web Crypto. Apps choose their own AES-256-GCM implementation (expo-crypto, react-native-quick-crypto, Web Crypto on RN-future, etc.) and inject it once at startup. The SDK uses your implementation everywhere — there's no native module bundled.

import { configure, CryptoProvider } from '@validpay/react-native-sdk';
import * as ExpoCrypto from 'expo-crypto';

class ExpoCryptoProvider implements CryptoProvider {
  async getRandomBytes(length: number): Promise<Uint8Array> {
    return ExpoCrypto.getRandomBytes(length);
  }
  async encrypt(plaintext: Uint8Array, key: Uint8Array): Promise<string> {
    // AES-256-GCM with a fresh 12-byte IV. Return base64 string of:
    //   iv (12 bytes) || authTag (16 bytes) || ciphertext
    // ...consult expo-crypto / react-native-quick-crypto docs for the call.
  }
  async decrypt(ciphertext: string, key: Uint8Array): Promise<Uint8Array> { /* … */ }
  async sha256(data: Uint8Array): Promise<string> {
    return ExpoCrypto.digestStringAsync(
      ExpoCrypto.CryptoDigestAlgorithm.SHA256,
      Buffer.from(data).toString('base64'),
      { encoding: ExpoCrypto.CryptoEncoding.HEX },
    );
  }
}

configure({ crypto: new ExpoCryptoProvider() });

If you use splitKey(), also import a synchronous random-bytes polyfill once at app entry:

import 'react-native-get-random-values';

This provides globalThis.crypto.getRandomValues, which splitKey() needs synchronously.

Quick start

import { ValidPayClient } from '@validpay/react-native-sdk';

const client = new ValidPayClient({ apiKey: 'vp_live_…' });

// 1. Issuer side — seal with End-Cell (recommended). The AES key is split
//    THREE ways: `key` is ShareA (rides the QR); one share goes to the
//    platform; one goes to the independent KeyHalve rail. No single party —
//    not the platform, not KeyHalve — can read or reassemble the key.
const result = await client.createEndCellIntent('check', {
  payee: 'Alice',
  amount: 1500,
});
console.log(result.retrievalId, result.key);
// → vp_abc123…   (public — embed in the QR)
// → ShareA (base64) — deliver ONLY to the intended verifier, out-of-band

// 2. Verifier side — fetch and decrypt (no API key needed). For End-Cell
//    intents, verifyIntent fetches the platform share + the rail share (the
//    rail's Ed25519 signature is verified against a PINNED key, fail-closed),
//    recombines in memory, decrypts locally, and re-checks the commitment hash.
const verified = await client.verifyIntent(result.retrievalId, result.key);
console.log(verified.payload);          // { payee: 'Alice', amount: 1500 }
console.log(verified.integrityVerified); // true

Simpler 2-share option: createSplitKeyIntent() splits the key between the document and the platform only — no independent rail share, so the platform alone could reconstruct. Prefer End-Cell above when independence from the platform matters.

⚠️ createIntent() is the legacy FULL-single-key flow — unlike the Node and Python SDKs, it performs no key split at all: the returned key is the complete AES key, so anyone holding the QR alone can decrypt. Use it only for backward compatibility with pre-split documents.

Building a verification URL

The retrievalId is public; the key is secret. buildVerifyUrl stamps them into a URL fragment (the # part — fragments are never sent to the server) on the canonical verifier origin, base64url-encoding the key so phone QR scanners and share-sheets don't mangle +, /, or =:

import { buildVerifyUrl } from '@validpay/react-native-sdk';

const url = buildVerifyUrl(result.retrievalId, result.key);
// → https://verify.keyhalve.com/verify/vp_abc123…#key=<base64url ShareA>
// Encode in a QR, paste in an email, scan with a phone camera.
// The /verify page reads the fragment client-side and decrypts locally.

Features

End-Cell issuance (blind rail) — createEndCellIntent / verifyIntent — leads the SDK: a 3-of-3 XOR key split across ShareA (QR) + platform + the independent KeyHalve rail, with the rail share Ed25519-signature-verified against a pinned key at verify time (fail-closed).

Plus eight patented protections, all live in this SDK:

| Patent | Feature | Method | | ------ | ----------------------------- | --------------------------------------------------- | | A | Multi-Hash Verification | computeCommitmentHash, automatic on verify | | B | Blind Content Escrow | encrypt / decrypt (client-side AES-256-GCM) | | C | Split-Key Verification | createSplitKeyIntent / verifySplitKeyIntent | | D | Time-Locked Verification | validFrom / validUntil on all create methods | | E | Selective Field Disclosure | createSelectiveIntent / verifySelectiveIntent | | F | Chain-of-Custody Tracking | getRevocationHistory | | G | Physical Medium Binding | computeBindingHash, createBoundIntent | | H | Blind Revocation | revokeIntent / reinstateIntent |

API reference

new ValidPayClient(options)

| Option | Type | Default | Notes | | ------------------ | -------- | ----------------------------- | -------------------------------------------------- | | apiKey | string | required | Bearer key from the issuer dashboard. | | baseUrl | string | https://api.validpay.com | Override for staging. | | timeoutMs | number | 10000 | Per-request timeout (AbortController). | | railBaseUrl | string | https://rail.keyhalve.com | KeyHalve rail (End-Cell share custody). | | railPublicKeySpki| string | pinned production key | Ed25519 SPKI (base64) the rail share is verified against. |

End-Cell (recommended)

client.createEndCellIntent(documentType, payload, opts?): Promise<CreateIntentResult>
// opts: { holders?, validFrom?, validUntil?, onBehalfOf? }

KeyHalve's blind-rail flow. Generates a key, encrypts the payload locally, and XOR-splits the key into ShareA (returned as key, for the QR) plus one share per holder. holders defaults to ['keyhalve', 'platform'] → a 3-of-3 split: the independent KeyHalve rail share + the platform share + ShareA. No single party can read or reassemble the key. Verify with verifyIntent (below), which fetches the platform + rail shares, verifies the rail's Ed25519 signature against a pinned key (fail-closed), recombines in memory, and decrypts. The full key never exists on any single system. Requires the API deployment to have End-Cell issuance enabled.

const result = await client.createEndCellIntent('check', { payee: 'Alice', amount: 1500 });
const verified = await client.verifyIntent(result.retrievalId, result.key);

The rail endpoint and pinned key default to the production KeyHalve rail; railBaseUrl / railPublicKeySpki client options exist for staging.

Core methods

client.createIntent(documentType, payload, opts?): Promise<CreateIntentResult>
client.createIntentBatch(intents): Promise<CreateIntentResult[]>   // ≤100 items
client.verifyIntent(retrievalId, key): Promise<VerifyIntentResult>

⚠️ Legacy: in this SDK createIntent is the FULL-single-key flow — it performs no key split at all (unlike createIntent in the Node/Python SDKs, which default to 2-share split-key). The returned key is the complete AES key: whoever holds the QR alone can decrypt. Prefer createEndCellIntent (3-share, above) or createSplitKeyIntent (2-share, below) for new documents.

verifyIntent handles single-key and End-Cell intents; for a split-key intent it throws split_key_required — use verifySplitKeyIntent instead.

Split-key (Patent C)

client.createSplitKeyIntent(documentType, payload, opts?): Promise<CreateIntentResult>
client.verifySplitKeyIntent(retrievalId, shareA): Promise<VerifyIntentResult>

createSplitKeyIntent returns Share A as the key field — embed it on the document as you would the regular key. Share B stays on the server and is fetched at verify time.

Platform delegation — onBehalfOf

If you integrate as a platform and seal on behalf of the businesses you serve, name the business on each seal. The verifier sees that business as the issuer ("who"), attributed through your platform ("through whom"), at the delegated trust rung. Those businesses never touch ValidPay, and ValidPay stays blind to the document contents.

const { retrievalId, key } = await client.createIntent(
  'lease',
  { unit: '4B', term: '12mo' },
  { onBehalfOf: { ref: 'landlord_8675309', name: 'Smith Properties LLC' } },
);

const result = await client.verifyIntent(retrievalId, key);
result.issuer;             // 'Smith Properties LLC'
result.verificationLevel;  // 'delegated'
result.delegatedBy;        // { platform: 'Your Platform', platformLevel: 'domain' }

Same ref ⇒ same tracked business (its documents and verification counts roll up). A sub-issuer surfaces as delegated only once your platform account is domain-verified.

Selective disclosure (Patent E)

client.createSelectiveIntent(
  documentType,
  payload,                                 // { fieldName: value }
  policy,                                  // { roleName: ['fieldName', …] }
  opts?,                                   // { splitKey?, validFrom?, validUntil? }
): Promise<CreateIntentResult>

client.verifySelectiveIntent(
  retrievalId,
  key,
  role = 'full',                           // 'full' decrypts everything
): Promise<VerifyIntentResult>

A full role with every field key is added to the policy automatically — that's the issuer view.

Time-locked verification (Patent D)

validFrom / validUntil (ISO-8601 strings) are accepted on every create method. Every verify result includes timeLockStatus ('valid', 'not_yet_valid', 'expired', or null). The SDK never withholds the payload — the caller decides whether to surface the status to the user.

const result = await client.createIntent('check', payload, {
  validFrom:  '2026-06-01T00:00:00Z',
  validUntil: '2026-12-31T23:59:59Z',
});

const verified = await client.verifyIntent(result.retrievalId, result.key);
// verified.timeLockStatus → 'valid' | 'not_yet_valid' | 'expired'

Revocation (Patent H)

client.revokeIntent(retrievalId, reason?): Promise<…>
client.reinstateIntent(retrievalId, reason?): Promise<…>
client.getRevocationHistory(retrievalId): Promise<Array<…>>

Revocation is "blind" — the server flips a status bit and stops returning the ciphertext. It never decrypts the payload.

Physical medium binding (Patent G)

import { computeBindingHash, compareBindingHashes } from '@validpay/react-native-sdk';

// Pre-process the binding-zone image to 8×8 grayscale with your image lib
// (expo-image-manipulator, react-native-image-resizer, etc.) and pass the
// raw bytes — this SDK doesn't bundle a JPEG/PNG decoder.
const imageBytes = new Uint8Array(64);     // 8×8 grayscale
const hash = await computeBindingHash(imageBytes);

const result = compareBindingHashes(hashA, hashB, /* threshold */ 10);
result.match;     // boolean
result.distance;  // Hamming distance

createBoundIntent issues a binding-aware intent in one call:

const result = await client.createBoundIntent(
  'check',
  { payee: 'Alice', amount: 1500 },
  bindingZoneImage,
  { threshold: 10 },
);

QR placement (buildVerifyUrl + resolveQrRect)

A verifiable document needs a scannable QR — encoding the verify URL — placed on it. This SDK gives you the canonical placement contract, shared verbatim with the Node and Python SDKs and the developer console's "Try it" tool, so a position picked once maps to the exact same spot everywhere.

import { buildVerifyUrl } from '@validpay/react-native-sdk';
import QRCode from 'react-native-qrcode-svg'; // your QR component of choice

const url = buildVerifyUrl(retrievalId, key);  // key is base64url'd into the #fragment
<QRCode value={url} size={160} />;

To stamp the QR onto a generated PDF, use the placement → points helper and hand the result to your PDF library (or do it server-side with @validpay/node-sdk's embedQr, which mints the PDF for you):

import { resolveQrRect, type QrPlacement } from '@validpay/react-native-sdk';

const placement: QrPlacement = { anchor: 'bottom-right', x: 36, y: 36, width: 90 };
const { x, y, size } = resolveQrRect(placement, pageWidthPt, pageHeightPt); // bottom-left points

Why no on-device embedQr? Editing PDF bytes on a phone isn't practical, so React Native ships only the pure contract. Render the QR for display, or seal the PDF where you build it. Keep the QR ≥ 72pt (1in) so it scans once printed (MIN_RECOMMENDED_QR_PT).

QrPlacement fields: anchor (page corner — top-left/top-right/bottom-left/bottom-right, default top-left), x/y (insets from that corner), width (QR side), units (pt/mm/in, default pt), page (1-based).

Errors

Every SDK and API failure is thrown as ValidPayError:

import { ValidPayError } from '@validpay/react-native-sdk';

try {
  await client.verifyIntent('vp_missing', 'key');
} catch (e) {
  if (e instanceof ValidPayError) {
    e.code;     // 'not_found' | 'unauthorized' | 'integrity_failure' | …
    e.status;   // HTTP status, when the error came from the API
    e.details;  // raw error body / extra context
  }
}

Cross-SDK compatibility

The wire format is identical across the Python, Node, and React Native SDKs:

base64(iv[12 bytes] || authTag[16 bytes] || ciphertext)

An intent created with validpay (Python) can be verified with this SDK, and vice versa. Tests in __tests__/crypto.test.ts decrypt a hand-crafted blob in the Python wire layout to enforce this guarantee.

License

MIT — see LICENSE.