HedgePayments API Documentation

Overview

Process a payment transaction using various payment methods including credit cards, bank transfers, cryptocurrency, or internal wallet transfers. This endpoint supports both one-time payments and authorizations. Powered by CoinFlow: This endpoint uses CoinFlow’s payment infrastructure for processing card, ACH, and crypto payments.

Authentication

Authorization: Bearer YOUR_API_KEY

Request Body

amount

number

required

Transaction amount in the smallest currency unit (cents for fiat, wei/lamports for crypto)Examples:

USD: 10000 = $100.00
EUR: 5000 = €50.00
SOL: 1000000000 = 1 SOL
USDC: 1000000 = 1 USDC (6 decimals)

currency

string

required

Three-letter currency code (ISO 4217) or crypto tickerSupported: USD, EUR, GBP, BTC, ETH, SOL, USDC, USDT

method

string

required

Payment method to useOptions:

card - Credit/debit card
ach - ACH bank transfer (US only)
wire - Wire transfer
wallet - Wallet-to-wallet transfer
crypto - Direct cryptocurrency payment
apple_pay - Apple Pay
google_pay - Google Pay

paymentMethodId

string

ID of a saved payment method (for card, ACH, bank transfers)Required for: card, ach, wallet methods when not using one-time tokens

sourceWalletId

string

Wallet ID to debit funds from (required for wallet-to-wallet transfers)

destinationWalletId

string

Wallet ID to credit funds to (required for wallet-to-wallet transfers)

description

string

Human-readable description of the transactionExample: "Order #12345 - Premium Subscription"

metadata

object

Custom key-value pairs to attach to the transactionExample:

{
  "orderId": "order_12345",
  "productId": "prod_premium_monthly",
  "customerId": "cust_abc123"
}

idempotencyKey

string

Unique key to prevent duplicate transactions (recommended for all requests)Example: "payment-order_12345-2025-11-18"

Request Examples

{
  "amount": 10000,
  "currency": "USD",
  "method": "card",
  "paymentMethodId": "pm_card_abc123",
  "description": "Premium Subscription - Monthly",
  "metadata": {
    "orderId": "order_12345",
    "plan": "premium_monthly"
  },
  "idempotencyKey": "payment-order_12345-2025-11-18"
}

Response

string

Unique transaction identifier

type

string

Transaction type: deposit, withdrawal, transfer_in, transfer_out, payment, refund, fee, adjustment

status

string

Current status: pending, processing, completed, failed, reversed, refunded, cancelled

amount

number

Transaction amount in smallest currency unit

currency

string

Currency code

fee

number

Processing fee charged

netAmount

number

Net amount after fees (amount - fee)

sourceWalletId

string

Wallet debited (if applicable)

destinationWalletId

string

Wallet credited (if applicable)

paymentMethodId

string

Payment method used

description

string

Transaction description

metadata

object

Custom metadata attached

createdAt

string

ISO 8601 creation timestamp

completedAt

string

ISO 8601 completion timestamp (null if not completed)

Response Examples

{
  "id": "txn_9x8y7z6a5b4c",
  "type": "payment",
  "status": "completed",
  "amount": 10000,
  "currency": "USD",
  "fee": 320,
  "netAmount": 9680,
  "paymentMethodId": "pm_card_abc123",
  "description": "Premium Subscription - Monthly",
  "metadata": {
    "orderId": "order_12345",
    "plan": "premium_monthly"
  },
  "createdAt": "2025-11-18T22:30:00Z",
  "completedAt": "2025-11-18T22:30:02Z"
}

Code Examples

import { HedgePayments } from '@hedgepayments/sdk';

const hedge = new HedgePayments(process.env.HEDGE_API_KEY);

async function processPayment() {
  try {
    const transaction = await hedge.transactions.create({
      amount: 10000, // $100.00
      currency: 'USD',
      method: 'card',
      paymentMethodId: 'pm_card_abc123',
      description: 'Premium Subscription',
      metadata: {
        orderId: 'order_12345',
        customerId: 'cust_abc'
      },
      idempotencyKey: `payment-${Date.now()}`
    });

    if (transaction.status === 'completed') {
      console.log('Payment successful:', transaction.id);
      // Fulfill order
    } else {
      console.log('Payment pending:', transaction.status);
      // Wait for webhook
    }

    return transaction;
  } catch (error) {
    if (error.code === 'INSUFFICIENT_FUNDS') {
      console.log('Payment declined - insufficient funds');
    } else if (error.code === 'CARD_DECLINED') {
      console.log('Card declined by issuer');
    }
    throw error;
  }
}

Payment Methods Comparison

Method	Processing Time	Settlement	Fees	Reversible	Geographic
Card	Instant	T+1 to T+3	~2.9% + $0.30	Yes (chargebacks)	Global
ACH	1-3 days	T+3 to T+5	~1%	Yes (returns)	US only
Wire	1-3 days	Same day	$25 flat	No	Global
Wallet	Instant	Instant	0%	No	Global
Crypto	5-60 min	Instant	Network fees	No	Global
Apple Pay	Instant	T+1 to T+3	~2.9% + $0.30	Yes	Global
Google Pay	Instant	T+1 to T+3	~2.9% + $0.30	Yes	Global

Error Codes

Code	HTTP	Description	Action
`INSUFFICIENT_FUNDS`	402	Not enough balance	Add funds or use different payment method
`CARD_DECLINED`	402	Card issuer declined	Contact card issuer or try different card
`INVALID_PAYMENT_METHOD`	400	Payment method not valid for currency	Use supported method
`PAYMENT_METHOD_NOT_FOUND`	404	Payment method ID doesn’t exist	Verify payment method ID
`AMOUNT_TOO_SMALL`	400	Below minimum amount	Increase amount (min $0.50)
`AMOUNT_TOO_LARGE`	400	Exceeds limits	Split into multiple transactions
`DUPLICATE_TRANSACTION`	409	Idempotency key already used	Use unique key or retrieve existing
`RATE_LIMIT_EXCEEDED`	429	Too many requests	Implement backoff

Webhooks

Transaction events trigger webhooks:

{
  "event": "transaction.completed",
  "data": {
    "id": "txn_abc123",
    "amount": 10000,
    "currency": "USD",
    "status": "completed",
    "completedAt": "2025-11-18T22:30:02Z"
  }
}

Best Practices

1. Always Use Idempotency Keys

// Generate unique key per attempt
const idempotencyKey = `payment-${orderId}-${Date.now()}`;

const transaction = await hedge.transactions.create({
  amount: 10000,
  currency: 'USD',
  idempotencyKey // Prevents duplicate charges
});

2. Handle Async Payments

Some methods (ACH, wire) are asynchronous:

const transaction = await hedge.transactions.create({ ... });

if (transaction.status === 'processing') {
  // Don't fulfill order yet
  // Wait for webhook notification
  console.log('Payment pending, estimated:', transaction.estimatedCompletion);
} else if (transaction.status === 'completed') {
  // Instant payment - fulfill immediately
  fulfillOrder(orderId);
}

3. Implement Retry Logic

async function processPaymentWithRetry(data, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await hedge.transactions.create(data);
    } catch (error) {
      if (error.code === 'RATE_LIMIT_EXCEEDED' && i < maxRetries - 1) {
        await sleep(Math.pow(2, i) * 1000); // Exponential backoff
        continue;
      }
      throw error;
    }
  }
}

List Transactions - View transaction history
Get Transaction - Retrieve transaction details
Refund Transaction - Process refunds
Add Payment Method - Save payment methods

Support

Questions? Contact us:

API Reference

Process Payment

Overview

Authentication

Request Body

Request Examples

Response

Response Examples

Code Examples

Payment Methods Comparison

Error Codes

Webhooks

Best Practices

1. Always Use Idempotency Keys

2. Handle Async Payments

3. Implement Retry Logic

Support

API Reference

​Overview

​Authentication

​Request Body

​Request Examples

​Response

​Response Examples

​Code Examples

​Payment Methods Comparison

​Error Codes

​Webhooks

​Best Practices

​1. Always Use Idempotency Keys

​2. Handle Async Payments

​3. Implement Retry Logic

​Related Endpoints

​Support

Overview

Authentication

Request Body

Request Examples

Response

Response Examples

Code Examples

Payment Methods Comparison

Error Codes

Webhooks

Best Practices

1. Always Use Idempotency Keys

2. Handle Async Payments

3. Implement Retry Logic

Related Endpoints

Support