@swype-org/deposit

Lightweight merchant deposit SDK — open a hosted Blink payment flow, handle completion, zero runtime dependencies.

Quick Start

npm install @swype-org/deposit

import { Deposit } from '@swype-org/deposit';

const deposit = new Deposit({ signer: '/api/sign-payment' });

document.getElementById('deposit-btn')!.addEventListener('click', async () => {
  try {
    const { transfer: result } = await deposit.requestDeposit({
      amount: 50,
      chainId: 8453,
      address: '0x...', // destination wallet
      token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
    });
    console.log('Transfer complete:', result.id, result.status);
  } catch (error) {
    console.error('Transfer failed:', error);
  }
});

Important: requestDeposit() must be called from a user-gesture handler (click, keypress, etc.) so the browser allows the iframe to open.

React Hook

A dedicated React entry point eliminates all boilerplate:

npm install @swype-org/deposit react

import { useBlinkDeposit } from '@swype-org/deposit/react';

function DepositButton() {
  const { status, result, error, displayMessage, requestDeposit } = useBlinkDeposit({
    signer: '/api/sign-payment',
  });

  return (
    <>
      <button
        onClick={() =>
          requestDeposit({ amount: 50, chainId: 8453, address: '0x...', token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' })
        }
        disabled={status === 'signer-loading'}
      >
        {status === 'signer-loading' ? 'Preparing…' : 'Deposit'}
      </button>
      {error && <p>{displayMessage}</p>}
      {result && <p>Transfer {result.transfer.id} complete!</p>}
    </>
  );
}

The hook returns reactive status, result, error, displayMessage, and isActive values, plus requestDeposit, focus, and close actions. It manages the Deposit lifecycle and cleans up on unmount.

How It Works

Merchant App / SDK              Merchant Signer                Hosted Flow (iframe)
     │                               │                               │
     │  1. requestDeposit(request)    │                               │
     │──────────────────────────────► │                               │
     │                                │  2. signer(data) or POST URL  │
     │                                │  (includes webviewBaseUrl)    │
     │  3. { signature, payload, ...} │                               │
     │◄───────────────────────────────│                               │
     │                                                                │
     │  4. SDK builds URL, opens iframe                               │
     │───────────────────────────────────────────────────────────────► │
     │                                                                │
     │  5. User completes payment in hosted flow                      │
     │                                                                │
     │  6. postMessage: blink:transfer-complete                       │
     │◄──────────────────────────────────────────────────────────────  │
     │                                                                │
     │  7. Promise resolves with DepositResult                        │

Configuration

const deposit = new Deposit({
  signer: '/api/sign-payment',
  webviewBaseUrl: 'https://pay.blink.cash',
  hostedFlowOrigin: 'https://pay.blink.cash',
  containerElement: document.getElementById('deposit-root')!,
  signerTimeoutMs: 15_000,
  flowTimeoutMs: 300_000,
  enableFullWidget: true,
  debug: false,
});

enableFullWidget

Controls whether the hosted flow may show the full widget (the Deposit Options entry screen for unauthenticated users). Defaults to true. The full widget only appears when this option is enabled and the merchant's backend config has it enabled — disabling either turns it off. Set it to false to force the hosted flow straight to the standard deposit flow regardless of merchant config.

Error Handling

Every error is a DepositError with a machine-readable code:

import { DepositError, getDisplayMessage } from '@swype-org/deposit';

try {
  await deposit.requestDeposit({ /* ... */ });
} catch (err) {
  if (err instanceof DepositError) {
    showToast(getDisplayMessage(err));
  }
}

Events

transfer.on('complete', (result) => { /* DepositResult */ });
transfer.on('error', (error) => { /* DepositError */ });
transfer.on('close', () => { /* iframe closed */ });
transfer.on('status-change', (status) => { /* DepositStatus */ });

Lifecycle

transfer.focus();   // No-op — retained for API compatibility
transfer.close();   // Close the iframe without waiting for completion
transfer.destroy(); // Tear down and release all resources (call on unmount)

TypeScript

All types are exported:

import type {
  DepositConfig,
  DepositStatus,
  DepositRequest,
  DepositResult,
  SignerFunction,
  SignerRequest,
  SignerResponse,
  TransferSummary,
} from '@swype-org/deposit'; 

import type { DepositErrorCode } from '@swype-org/deposit';

Security & content integrity

The deposit UI loads live from https://pay.blink.cash every render — the standard model for embedded payment UIs (it lets us ship security/fraud fixes instantly). We do not version-pin the iframe; instead:

• Verifiable build manifest — every deploy publishes https://pay.blink.cash/manifest.json with the build version, source commit, and a SHA-256 of every served file, so you can confirm exactly what we serve.

• Lock the iframe origin — add a CSP to your page so the iframe can only ever load from Swype:

  Content-Security-Policy: frame-src https://pay.blink.cash; script-src 'self';

See docs/iframe-security.md for the full security model (CSP, postMessage hardening, Privy origin allow-listing, passkey delegation, and SRI rationale).

Backward Compatibility

The previous Checkout-named symbols are re-exported as deprecated aliases:

import { Checkout } from '@swype-org/deposit';       // deprecated alias for Transfer
import { CheckoutError } from '@swype-org/deposit';   // deprecated alias for DepositError
import { useBlinkCheckout } from '@swype-org/deposit/react'; // deprecated alias for useBlinkDeposit