API Documentation

Welcome to the Hybrid Payment Gateway API. This API allows you to accept both fiat (credit cards, PayPal) and cryptocurrency (BTC, ETH, USDT) payments through a unified interface.

Authentication

For admin endpoints, include the JWT token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

Create Fiat Payment

Create a new fiat payment (card or PayPal).

Request Body

{
  "merchantId": "merchant_123",
  "amount": 99.99,
  "currency": "USD",
  "method": "card",  // or "paypal"
  "customerEmail": "customer@example.com"  // optional
}

Response

{
  "success": true,
  "payment": {
    "id": "abc-123-def",
    "merchantId": "merchant_123",
    "amount": 99.99,
    "currency": "USD",
    "method": "card",
    "status": "pending",
    "provider": "stripe",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Get Fiat Payment

Retrieve a fiat payment by ID.

Response

{
  "payment": {
    "id": "abc-123-def",
    "status": "approved",  // pending, processing, approved, rejected
    "amount": 99.99,
    "currency": "USD",
    "method": "card",
    "processedAt": "2024-01-15T10:35:00Z"
  }
}

List Fiat Payments

List all fiat payments with stats.

Approve Fiat Payment

Approve a pending fiat payment (admin only).

Request Body

{
  "adminId": "admin_1"
}

Reject Fiat Payment

Reject a pending fiat payment (admin only).

Request Body

{
  "adminId": "admin_1",
  "reason": "Suspicious activity detected"
}

Create Crypto Payment

Create a new cryptocurrency payment.

Request Body

{
  "merchantId": "merchant_123",
  "cryptocurrency": "BTC",  // BTC, ETH, or USDT
  "amount": 0.00334,
  "fiatAmount": 299.00,
  "fiatCurrency": "USD",
  "walletAddress": "bc1q...",
  "rate": 89500
}

Response

{
  "success": true,
  "payment": {
    "id": "xyz-789-abc",
    "cryptocurrency": "BTC",
    "cryptoAmount": 0.00334,
    "fiatAmount": 299.00,
    "walletAddress": "bc1q...",
    "status": "pending",
    "requiredConfirmations": 3
  }
}

Submit Transaction Hash

Submit the blockchain transaction hash after customer sends crypto.

Request Body

{
  "txHash": "0x1234567890abcdef..."
}

Get Crypto Payment

Retrieve a crypto payment by ID.

Response

{
  "payment": {
    "id": "xyz-789-abc",
    "status": "submitted",  // pending, submitted, verified, approved, rejected
    "cryptocurrency": "BTC",
    "cryptoAmount": 0.00334,
    "txHash": "0x1234...",
    "confirmations": 2,
    "requiredConfirmations": 3
  }
}

Approve Crypto Payment

Approve a verified crypto payment (admin only).

Get Exchange Rates

Get current exchange rates for all supported currencies.

Response

{
  "crypto": {
    "BTC": { "usd": 89500 },
    "ETH": { "usd": 3025 },
    "USDT": { "usd": 1 }
  },
  "fiat": {
    "EUR": { "rate": 0.92 },
    "GBP": { "rate": 0.79 }
  },
  "lastUpdated": "2024-01-15T10:30:00Z"
}

Convert to Crypto

Convert a fiat amount to cryptocurrency.

Query Parameters

• amount - Fiat amount to convert
• currency - Fiat currency (USD, EUR, etc.)
• crypto - Target cryptocurrency (BTC, ETH, USDT)

Response

{
  "fiatAmount": 100,
  "fiatCurrency": "USD",
  "cryptocurrency": "BTC",
  "cryptoAmount": 0.001117,
  "rate": 89500,
  "timestamp": "2024-01-15T10:30:00Z"
}

Get Fee Configuration

Get current fee configuration.

Response

{
  "config": {
    "globalPlatformFee": 1.5,
    "fiat": {
      "stripe": { "percentage": 2.9, "fixed": 0.30 },
      "paypal": { "percentage": 3.49, "fixed": 0.49 }
    },
    "crypto": {
      "bitcoin": { "percentage": 1.0 },
      "ethereum": { "percentage": 0.5 },
      "usdt": { "percentage": 0.5 }
    }
  }
}

Get Crypto Wallet

Get wallet address for receiving crypto payments.

Response

{
  "wallet": {
    "cryptocurrency": "BTC",
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "network": "mainnet"
  }
}

Generate Payment QR Code

Generate a QR code for crypto payment.

Request Body

{
  "cryptocurrency": "BTC",
  "address": "bc1q...",
  "amount": 0.00334
}

Response

{
  "qr": {
    "qrCodeUrl": "data:image/png;base64,...",
    "paymentUri": "bitcoin:bc1q...?amount=0.00334"
  }
}

Status Codes