Skip to main content

​
Prerequisites

Before you begin, make sure you have:

Hedge Pay Account

Sign up at dashboard.hedgepay.com

API Credentials

Get your API key and Partner ID from the dashboard

​
Installation

Choose your preferred SDK:
  • JavaScript/TypeScript
  • React
  • Python
  • cURL
npm install @hedge/sdk-core
# or
yarn add @hedge/sdk-core

​
Initialize the SDK

import { HedgeSDK } from '@hedge/sdk-core';

const hedge = new HedgeSDK({
  apiKey: process.env.HEDGE_API_KEY,
  partnerId: process.env.HEDGE_PARTNER_ID,
  environment: 'sandbox' // or 'production'
});

// Authenticate
await hedge.authenticate();

​
Step 1: Create a User

Every round-up account needs a user. Create one for your customer: 
const user = await hedge.users.create({
  email: '[email protected]',
  firstName: 'Jane',
  lastName: 'Smith',
  partnerId: 'your-partner-id',
  externalId: 'your-internal-user-id' // Optional
});

console.log('User created:', user.id);

​
Step 2: Connect a Bank Account

Generate a link token for your user to connect their bank account: 
// Generate link token
const { linkToken } = await hedge.accounts.connect(user.id);

// Use this token with our UI component or build your own
// The user will be redirected to connect their bank
For React applications, use our pre-built <BankConnection> component for the smoothest integration

​
Step 3: Configure Round-up Settings

Set up how round-ups should work for this user: 
const settings = await hedge.roundups.updateSettings(user.id, {
  enabled: true,
  multiplier: 1,        // 1x, 2x, 3x, or 5x
  maxRoundupAmount: 5,  // Cap at $5 per transaction
  destinationAccountId: 'dest-account-id'
});

console.log('Round-ups enabled:', settings.enabled);

​
Step 4: Process a Transaction

When a transaction occurs, calculate and process the round-up: 
// Process a $4.25 purchase
const transaction = await hedge.transactions.process({
  userId: user.id,
  amount: 4.25,
  merchantName: 'Coffee Shop',
  transactionId: 'txn-123'
});

// Round-up amount: $0.75 (rounds to $5.00)
console.log('Round-up amount:', transaction.roundupAmount);

​
Step 5: Listen for Webhooks

Set up webhooks to receive real-time updates: 
// Register webhook endpoint
await hedge.webhooks.register({
  url: 'https://your-app.com/webhooks/hedge',
  events: ['transfer.completed', 'transfer.failed', 'roundup.processed']
});

// Handle webhook in your server
app.post('/webhooks/hedge', (req, res) => {
  const signature = req.headers['x-hedge-signature'];
  
  if (hedge.webhooks.verify(req.body, signature)) {
    const { event, data } = req.body;
    
    switch(event) {
      case 'transfer.completed':
        console.log('Transfer completed:', data.transferId);
        break;
      case 'roundup.processed':
        console.log('Round-up processed:', data.amount);
        break;
    }
    
    res.status(200).send('OK');
  } else {
    res.status(401).send('Invalid signature');
  }
});

​
Complete React Example

Here’s a full React component with round-ups: 
import React, { useState } from 'react';
import { 
  HedgeProvider, 
  RoundupSettings, 
  BankConnection,
  useHedge 
} from '@hedge/sdk-react';

function RoundupApp() {
  const { user, createUser, isLoading } = useHedge();
  const [email, setEmail] = useState('');

  const handleSignup = async () => {
    await createUser({
      email,
      firstName: 'John',
      lastName: 'Doe'
    });
  };

  if (!user) {
    return (
      <div>
        <input 
          type="email" 
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          placeholder="Enter email"
        />
        <button onClick={handleSignup} disabled={isLoading}>
          Sign Up for Round-ups
        </button>
      </div>
    );
  }

  return (
    <div>
      <h2>Welcome, {user.firstName}!</h2>
      
      <BankConnection 
        userId={user.id}
        onSuccess={(account) => {
          console.log('Bank connected:', account);
        }}
      />
      
      <RoundupSettings 
        userId={user.id}
        theme="minimal"
      />
    </div>
  );
}

export default function App() {
  return (
    <HedgeProvider 
      apiKey={process.env.REACT_APP_HEDGE_API_KEY}
      partnerId={process.env.REACT_APP_HEDGE_PARTNER_ID}
    >
      <RoundupApp />
    </HedgeProvider>
  );
}

​
Testing in Sandbox

The sandbox environment provides test bank accounts and simulated transactions. Use these test credentials:
  • Bank: Test Bank
  • Username: user_good
  • Password: pass_good

​
Next Steps

API Reference

Explore all available endpoints

Webhook Events

Learn about webhook events

Going to Production

Production deployment checklist

Security Best Practices

Secure your integration