fastpay-checkout-sdk

Browser SDKs for FastPay's non-custodial crypto checkout — the customer's own wallet signs and pays a merchant directly; FastPay never holds the funds. See docs/payment-gateway-api.md in the API repo for the full endpoint reference these SDKs talk to.

Published from fastpay-lab (the API/relay repo), not the marketing website — these files call the relay's own /v1/payment-requests/* and /v1/checkout/sessions/* routes directly, so keeping the SDK source in the same repo as the API it's a client for means a route change and the SDK change that follows it ship together, reviewed by the same test suite, instead of drifting across two repos with no shared CI. See public/sdk/ in that repo for the source.

Four files, two independent flows

| File | For | Consumed as | |---|---|---| | fastpay-checkout.js | The hosted checkout page itself (public/checkout/index.html) - talks to the payer's own connected wallet on every checkout network (see Wallets) | <script src>, attaches window.FastPayCheckout | | fastpay-embed.js | A merchant's own page, mounting the hosted checkout page inline as an iframe | <script src>, attaches window.FastPayEmbed | | fastpay-react.js | A merchant's React app, wrapping the same iframe embed as a component | import { FastPayCheckoutProvider, FastPayCheckout, useFastPayCheckout } from 'fastpay-checkout-sdk/react' | | checkout.js | The Checkout Sessions flow specifically (cs_... ids, window.GatewayCheckout) - a separate, independently-shipped SDK targeting a different id namespace than the three above (pr_... payment-request ids) | <script src> or <script data-gateway-checkout="cs_..."> auto-detect |

fastpay-checkout.js/fastpay-embed.js and checkout.js are both thin wrappers around the same static hosted checkout page — either works against either kind of id in practice, but they ship as independent files with no shared code (see the API repo's own CLAUDE.md for why).

Published via Trusted Publishing from .github/workflows/publish-sdk.yml — no long-lived npm token stored anywhere.

Wallets, per network (1.1.0)

FastPayCheckout.processPayment(paymentRequestId, callbacks) reads the request's network from the relay and connects the matching wallet family - nothing to configure per chain:

| Network | Wallet | How | |---|---|---| | Every EVM network | MetaMask, Rabby, Trust, … | window.ethereum + window.ethers v6 (unchanged from 1.0) | | solana | Phantom, Solflare, Backpack, … | Wallet Standard solana:signAndSendTransaction | | sui | Slush, Suiet, … | Wallet Standard sui:signAndExecuteTransaction | | aptos | Petra, Pontem, … | AIP-62 aptos:signAndSubmitTransaction, legacy window.aptos fallback | | tron | TronLink | window.tronLink / window.tronWeb (TRC20 approval handled) | | ton | Tonkeeper, MyTonWallet, … | TonConnect UI 3.0.2, loaded on demand from jsDelivr with a Subresource Integrity hash; manifest served by the relay at /checkout/tonconnect-manifest.json |

Options: chains ({ solana: 'solana:mainnet', sui: 'sui:mainnet' } by default), preferredWallets ({ solana: 'Phantom' } when several are installed), tonConnect (manifestUrl/url/integrity overrides), confirmPolling ({ intervalMs: 3000, maxAttempts: 40 }). Callbacks: onConnect(family), onApprove(approval), onDisburse(intent), onConfirming(txHash), onSuccess(txHash), onError(error). Non-EVM confirmations are polled (a just-broadcast transaction can read pending for a few seconds). For TON the SDK reports the signed message BOC and the relay derives the hash.

Usage (CDN, no build step)

<script src="https://cdn.jsdelivr.net/npm/fastpay-checkout-sdk@1/fastpay-embed.js"></script>
<script>
  const embed = new FastPayEmbed({ relayUrl: 'https://relay.f-pay.com' });
  embed.mount('#checkout-container', { paymentRequestId: 'pr_...' });
</script>

Or via unpkg: https://unpkg.com/fastpay-checkout-sdk@1/fastpay-embed.js. Pin an exact version (@1.0.0) rather than a floating major (@1) for anything you don't control the deploy timing of — see Versioning below.

Usage (React, bundled)

npm install fastpay-checkout-sdk

import { FastPayCheckoutProvider, FastPayCheckout } from 'fastpay-checkout-sdk/react';

function Page() {
  return (
    <FastPayCheckoutProvider relayUrl="https://relay.f-pay.com" paymentRequestId="pr_...">
      <FastPayCheckout />
    </FastPayCheckoutProvider>
  );
}

Versioning

Tags on the fastpay-lab repo (sdk-v1.0.1, etc.) drive publishing — each tag publishes exactly that version, deliberately, not on every merge to main. A merchant integration embedding these files directly in a live checkout page should pin an exact version rather than tracking latest, the same way you'd pin any third-party script a payment flow depends on.

Self-hosted alternative

Every file here is also served directly by the relay process itself, unversioned, at /sdk/<file>.js — useful for an integration that wants to avoid a third-party CDN dependency entirely. The CDN-published version here exists for reach/caching, not to replace that option.