API Integration Overview

This page gives you a quick orientation to the 3PAY API. For detailed reference, see the linked guides below.

Environments

Sandbox and production are completely separate systems. API keys, webhooks, and balances do not carry over.

Authentication

All API endpoints require the apikey header. Some endpoints additionally require the x-api-secret header.

// Basic authentication (all endpoints)
headers: { apikey: "your-api-key" }

// Enhanced authentication (recommended, required for approve/reject)
headers: {
  apikey: "your-api-key",
  "x-api-secret": "your-api-secret"
}

See Authentication & Security for the full auth model, rate limits, and security features.

Integration Models

3PAY supports three integration patterns:

1. Invoice Payments (One-Time)

Create payment links for individual transactions. Best for e-commerce checkout.

POST /api/v1/transaction/create → Payment URL
Customer pays → Webhook confirmation

Invoice Payments guide

2. Wallet Payments (Per-User)

Assign persistent wallet addresses to users. Best for platforms with user accounts.

POST /api/v1/public/wallet/generate → Wallet addresses
User deposits → Auto-detected → Webhook confirmation

Wallet Payments guide

3. Withdrawals & Payouts (Outbound)

Send USDT to external wallets via API or dashboard.

POST /api/v1/public/user/withdrawal/create → Auto-approved withdrawal
Dashboard payout → OTP → Immediate execution

Pay-Outs & Withdrawals guide

Webhooks

3PAY sends real-time HTTP POST notifications for all transaction events. Configure your webhook URL in the dashboard and verify signatures using HMAC-SHA256.

Webhook Handling guide

Quick Links