HedgePayments API Documentation

Overview

The Hedge Pay API uses JWT (JSON Web Tokens) for authentication. All API requests must include a valid access token in the Authorization header.

Access tokens expire after 7 days. We recommend implementing automatic token refresh to avoid service interruptions.

Authentication Flow

Getting Your Credentials

Sign up at dashboard.hedgepay.com
Navigate to Settings → API Keys
Generate your API credentials:
- API Key: Public identifier for your application
- API Secret: Secret key (keep this secure!)
- Partner ID: Your unique partner identifier

Never expose your API Secret in client-side code or public repositories. Store it securely in environment variables.

Generate Access Token

Exchange your API credentials for an access token:

const response = await fetch('https://api.hedgepay.com/v1/auth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    api_key: 'pk_live_abc123...',
    api_secret: 'sk_live_xyz789...',
    partner_id: 'partner_123'
  })
});

const { access_token, expires_in } = await response.json();

// Store the token securely
localStorage.setItem('hedge_token', access_token);

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 604800,
  "partner_id": "partner_123",
  "scopes": [
    "users:read",
    "users:write",
    "accounts:read",
    "accounts:write",
    "transfers:read",
    "transfers:write"
  ]
}

Using the Access Token

Include the access token in the Authorization header for all API requests:

const response = await fetch('https://api.hedgepay.com/v1/users', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json'
  }
});

Token Refresh

Refresh your token before it expires to maintain uninterrupted service:

// Refresh token before expiry
const refreshToken = async () => {
  const response = await fetch('https://api.hedgepay.com/v1/auth/refresh', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${current_token}`,
      'Content-Type': 'application/json'
    }
  });
  
  const { access_token } = await response.json();
  return access_token;
};

// Auto-refresh implementation
setInterval(async () => {
  const newToken = await refreshToken();
  localStorage.setItem('hedge_token', newToken);
}, 6 * 24 * 60 * 60 * 1000); // Refresh every 6 days

Token Revocation

Revoke a token when it’s no longer needed:

await fetch('https://api.hedgepay.com/v1/auth/revoke', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json'
  }
});

Scopes and Permissions

Tokens are issued with specific scopes that determine API access:

Scope	Description
`users:read`	Read user information
`users:write`	Create and update users
`accounts:read`	View connected bank accounts
`accounts:write`	Connect and disconnect accounts
`transfers:read`	View transfer history
`transfers:write`	Initiate and cancel transfers
`roundups:read`	View round-up settings
`roundups:write`	Modify round-up settings
`webhooks:write`	Manage webhook subscriptions

Environment-Specific Endpoints

Production
Sandbox

Base URL: https://api.hedgepay.com
Auth URL: https://api.hedgepay.com/v1/auth/token

Error Handling

Authentication errors return standard HTTP status codes:

Status Code	Error	Description
`401`	`INVALID_CREDENTIALS`	Invalid API key or secret
`401`	`TOKEN_EXPIRED`	Access token has expired
`401`	`TOKEN_INVALID`	Malformed or invalid token
`403`	`INSUFFICIENT_SCOPE`	Token lacks required permissions
`429`	`RATE_LIMITED`	Too many authentication attempts

Error Response Example

{
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "The access token has expired. Please refresh or generate a new token.",
    "details": {
      "expired_at": "2024-01-15T10:30:00Z"
    }
  },
  "request_id": "req_abc123xyz"
}

Security Best Practices

Store Credentials Securely

Never commit API secrets to version control
Use environment variables or secret management services
Rotate API keys regularly
Use different keys for development and production

Implement Token Refresh

Refresh tokens before expiry
Handle refresh failures gracefully
Implement exponential backoff for retries
Store refresh timestamps

Secure Client Applications

Never expose API secrets in client-side code
Use server-side proxy for API calls
Implement CORS properly
Validate webhook signatures

Monitor and Audit

Log all authentication events
Monitor for unusual patterns
Set up alerts for failed authentications
Review API key usage regularly

SDK Authentication

Our SDKs handle authentication automatically:

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

const hedge = new HedgeSDK({
  apiKey: process.env.HEDGE_API_KEY,
  apiSecret: process.env.HEDGE_API_SECRET,
  partnerId: process.env.HEDGE_PARTNER_ID
});

// SDK handles token generation and refresh automatically
await hedge.authenticate();

Get Started

Core Concepts

Authentication

Overview

Authentication Flow

Getting Your Credentials

Generate Access Token

Response

Using the Access Token

Token Refresh

Token Revocation

Scopes and Permissions

Environment-Specific Endpoints

Error Handling

Error Response Example

Security Best Practices

SDK Authentication

Next Steps

API Reference

Webhooks

Get Started

Core Concepts

​Overview

​Authentication Flow

​Getting Your Credentials

​Generate Access Token

​Response

​Using the Access Token

​Token Refresh

​Token Revocation

​Scopes and Permissions

​Environment-Specific Endpoints

​Error Handling

​Error Response Example

​Security Best Practices

​SDK Authentication

​Next Steps

API Reference

Webhooks

Overview

Authentication Flow

Getting Your Credentials

Generate Access Token

Response

Using the Access Token

Token Refresh

Token Revocation

Scopes and Permissions

Environment-Specific Endpoints

Error Handling

Error Response Example

Security Best Practices

SDK Authentication

Next Steps