React SDK

Installation

npm install @hedgepayments/react

yarn add @hedgepayments/react

pnpm add @hedgepayments/react

Quick Start

Wrap your app with the provider and start using components:

import { HedgePaymentsProvider, HedgePurchase } from '@hedgepayments/react'

function App() {
  return (
    <HedgePaymentsProvider
      merchantId="your_merchant_id"
      env="sandbox"
    >
      <CheckoutPage />
    </HedgePaymentsProvider>
  )
}

function CheckoutPage() {
  return (
    <HedgePurchase
      amount={9999}
      onSuccess={(result) => console.log('Payment successful:', result)}
      onError={(error) => console.error('Payment failed:', error)}
    />
  )
}

HedgePaymentsProvider

The provider component that initializes the SDK and provides context to all child components.

HedgePurchase

Full checkout component with payment method selection, card form, and payment processing.

import { HedgePurchase } from '@hedgepayments/react'

<HedgePurchase
  // Required
  amount={9999}                    // Amount in cents

  // Optional - Payment configuration
  currency="USD"                   // Default: USD
  email="customer@example.com"     // Pre-fill customer email
  paymentMethods={['card', 'ach', 'crypto']}  // Enabled methods

  // Optional - Settlement
  settlementType="USDC"            // 'Credits' | 'USDC' | 'Bank'
  settlementWallet="0x..."         // For USDC settlement

  // Optional - Subscriptions
  planCode="monthly_pro"           // Subscription plan code

  // Optional - Callbacks
  onSuccess={(result) => {}}       // Payment succeeded
  onError={(error) => {}}          // Payment failed
  onReady={() => {}}               // Component loaded

  // Optional - Styling
  height={600}                     // Component height in pixels
  className="my-checkout"          // Additional CSS classes
/>

HedgeCardForm

Standalone card input form for collecting and tokenizing card details. Use this when you need a custom checkout UI.

import { HedgeCardForm, useHedgePayments } from '@hedgepayments/react'

function CustomCheckout() {
  const { tokenize, processing, error } = useHedgePayments()

  const handleSubmit = async (e) => {
    e.preventDefault()

    try {
      const token = await tokenize()
      // Send token to your backend
      await processPayment(token)
    } catch (err) {
      console.error('Tokenization failed:', err)
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <HedgeCardForm
        onReady={() => console.log('Card form ready')}
        onFocus={(field) => console.log('Focused:', field)}
        onBlur={(field) => console.log('Blurred:', field)}
        onError={(err) => console.error('Form error:', err)}
        styles={{
          base: {
            fontSize: '16px',
            color: '#333',
            fontFamily: 'Inter, sans-serif'
          },
          invalid: {
            color: '#ef4444'
          }
        }}
      />

      {error && <p className="text-red-500">{error.message}</p>}

      <button type="submit" disabled={processing}>
        {processing ? 'Processing...' : 'Pay Now'}
      </button>
    </form>
  )
}

HedgeWithdraw

Component for withdrawing funds to bank accounts, cards, or crypto wallets.

import { HedgeWithdraw } from '@hedgepayments/react'

<HedgeWithdraw
  // Required for crypto withdrawals
  wallet={connectedWallet}
  connection={solanaConnection}

  // Optional
  amount={10000}                   // Pre-fill amount (in cents)
  lockAmount={true}                // Disable amount editing
  email="user@example.com"         // Pre-fill email
  tokens={['USDC', 'SOL']}         // Limit available tokens

  // Callbacks
  onSuccess={(tx) => console.log('Withdrawal successful:', tx)}
  onError={(err) => console.error('Withdrawal failed:', err)}
/>

useHedgePayments Hook

Access SDK methods and state from any component within the provider.

import { useHedgePayments } from '@hedgepayments/react'

function MyComponent() {
  const {
    // Card tokenization
    tokenize,              // () => Promise<string> - Tokenize card form

    // State
    processing,            // boolean - Payment in progress
    error,                 // Error | null - Current error
    ready,                 // boolean - SDK initialized

    // Bank linking
    createBankToken,       // (opts) => Promise<string>

    // Utilities
    getSessionKey,         // () => Promise<string>
    validateCard,          // () => ValidationResult
  } = useHedgePayments()

  // Use in your component...
}

Customizing Styles

Match the payment components to your application's design:

<HedgePaymentsProvider
  merchantId="your_merchant_id"
  env="sandbox"
  theme={{
    // Colors
    primary: '#10B981',        // Brand color
    background: '#ffffff',     // Background color
    text: '#1f2937',          // Text color
    error: '#ef4444',         // Error color

    // Typography
    fontFamily: 'Inter, sans-serif',
    fontSize: '16px',

    // Borders
    borderRadius: '8px',
    borderColor: '#e5e7eb',

    // Inputs
    inputBackground: '#f9fafb',
    inputPadding: '12px 16px',
  }}
>
  <App />
</HedgePaymentsProvider>

TypeScript Support

Full TypeScript definitions are included:

import type {
  HedgePaymentsProviderProps,
  HedgePurchaseProps,
  HedgeCardFormProps,
  HedgeWithdrawProps,
  PaymentResult,
  TokenizeResult,
  PaymentMethod,
  SettlementType,
} from '@hedgepayments/react'

// All components and hooks are fully typed
const handleSuccess = (result: PaymentResult) => {
  console.log(result.transactionId)
  console.log(result.amount)
  console.log(result.status)
}