@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,
  debug: false,
});

Error Handling

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

| Code | Meaning | | ------------------------ | ----------------------------------------------- | | DEPOSIT_DISMISSED | User closed the transfer before completing | | SIGNER_REQUEST_FAILED | Signer returned a non-2xx response | | SIGNER_NETWORK_ERROR | Network failure reaching the signer | | SIGNER_RESPONSE_INVALID| Signer response missing required fields | | SIGNER_TIMEOUT | Signer did not respond within signerTimeoutMs | | FLOW_TIMEOUT | Entire flow exceeded flowTimeoutMs | | INVALID_REQUEST | Bad input (amount, address, etc.) |

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';

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