Institutional-grade Payments API

Welcome to the GammaPay developer portal. Our API is built on REST principles, designed to help you integrate seamlessly with over 20+ blockchain networks using a single unified interface.

Creating a Wallet

The wallet creation wizard walks you through a 3-step process:

API Credentials (Per-Wallet)

Every wallet has its own isolated API key pair. These credentials are used to authenticate API requests for that specific wallet.

Deposit Addresses

GammaPay uses BIP44 HD derivation (m/44'/coin_type'/0'/0/index) to generate unique deposit addresses for each wallet.

• One address per invoice — addresses are never reused across invoices to maintain privacy and simplify tracking.
• Labels:Optionally assign a label when generating an address (e.g., "Customer #1234").
• QR Codes: Each address comes with an auto-generated QR code for easy display.
• Monitoring: All generated addresses are automatically monitored by the blockchain scanner.

Wallet Settings & Controls

Invoice Status Flow

Edge Cases

• Underpayment: Status becomes underpaid after expiry.
• Overpayment: Marked paid. Excess funds credited to wallet balance.
• Multiple Transactions: Remains confirming until total received ≥ expected.
• Wrong Network/Token: Funds are lost permanently. Always display the correct network.

Adding a Whitelist Address

Verification Flow (Anti-Phishing)

The verification email contains an anti-phishing image that you selected when setting up 2FA. This ensures the email genuinely came from GammaPay and is not a phishing attempt.

Managing Whitelisted Addresses

• View All: The whitelist tab shows all addresses with their label, truncated address, status, and date added.
• Copy Address: Click the copy icon to copy the full address to clipboard.
• Remove: Click the trash icon to remove an address. Confirmation dialog prevents accidental removal. Once removed, withdrawals to that address are immediately blocked.
• Resend Verification: For pending addresses, you can resend the verification email from the verification modal.
• Polling: The dashboard automatically polls for verification status — once you confirm via email, the UI updates without manual refresh.

Whitelist API Endpoints

{
  "flag": 1,
  "data": {
    "addresses": [
      {
        "id": "uuid",
        "address": "0x7066F72B...",
        "label": "Main Treasury",
        "email_confirmed": true,
        "is_active": true,
        "added_at": "2026-06-01T10:00:00Z"
      }
    ]
  }
}

{
  "flag": 1,
  "msg": "Verification email sent",
  "data": {
    "whitelist_id": "uuid",
    "category": "animals",
    "correct_picture": "photo-id",
    "options": ["photo-1", "photo-2", "photo-3"]
  }
}

Two-Factor Authentication (2FA)

TOTP (Time-based One-Time Password) adds a second layer of security. It is required for withdrawals, whitelist management, and API key operations.

Setup Flow

1. Verify Password: Enter your current account password to initiate setup.
2. Scan QR Code: Scan the displayed QR code with your authenticator app (Google Authenticator, Authy, 1Password, etc.). Or manually enter the secret key.
3. Select Anti-Phishing Image: Choose a personalized image from categories (Animals, Vehicles, Objects). This image appears in all security emails from GammaPay.
4. Verify Code: Enter the 6-digit code from your authenticator app to confirm setup.
5. Save Recovery Codes: Download and securely store your one-time backup recovery codes. These are the only way to regain access if you lose your authenticator device.

Anti-Phishing Image Protection

During 2FA setup, you select a personalized security image. This image is embedded in all official GammaPay emails (whitelist verification, login alerts, etc.).

IP Whitelisting (Account-Level)

When enabled, API requests are only accepted from IP addresses you specify. This is a global toggle that applies to all wallets on your account.

• Toggle on/off from Security → IP Whitelisting
• Configure IPs per-wallet in the wallet settings (Deposit & Withdraw tab → Security Whitelist section)
• Supports both individual IPs and domains
• Requests from non-whitelisted IPs receive a 403 Forbidden response

Login Shield

Login Shield adds an extra verification step when logging in from an unrecognized device or IP address.

• When enabled, login from a new device/location triggers an email confirmation.
• The account remains locked until the email link is clicked.
• Prevents unauthorized access even if password is compromised (without 2FA).
• Toggle on/off from Security settings.

Session Management

• Active Sessions: View all currently active sessions (device, IP, browser, last active time).
• Terminate Sessions: Remotely log out any active session from the Active Sessions page.
• Session Timeout: Configure auto-logout after inactivity (configurable from Notifications settings).
• Login History: Full audit log of all login attempts (successful and failed) with IP, timestamp, and device info.

Crypto vs USD Payments

Handling Underpayments

• Monitor for the payment.underpaid webhook event.
• The webhook payload includes amount_received_coin and shortfall_coin.
• You can manually mark the invoice as paid in the dashboard if the shortfall is negligible.
• Otherwise, the invoice remains underpaid until the remaining balance is sent to the same address.

Test Your Integration

• Use testnet coins: Create wallets for testnet assets (ETH Sepolia, USDT Nile, etc.).
• Faucets: Get free testnet tokens from Sepolia faucets for ETH/ERC20 or Nile faucet for TRC20.
• Webhook testing:Use the built-in "Test Webhook" button in the dashboard or tools like webhook.site.
• API Logs: Monitor all requests in real-time from the API Logs tab.

Security Best Practices

• Never share your api_secret — store it only on your backend server, never in frontend code or version control.
• Enable 2FA immediately— it's required for withdrawals and provides critical protection.
• Verify webhook signatures — always validate the HMAC signature before processing webhook events.
• Use IP whitelisting — restrict API access to your known server IPs.
• Set daily withdrawal limits — cap exposure in case of credential compromise.
• Rotate keys periodically — rotate API keys and webhook secrets on a regular schedule.
• Monitor API logs — watch for unexpected IPs or unusual request patterns.
• Use idempotency keys — prevent duplicate charges from retry logic.