Wallet Payments (Per-User Wallets)

Assign persistent wallet addresses to each user. Unlike invoice payments, wallet addresses remain active indefinitely. Deposits are auto-detected every 10 seconds and credited to the user's balance.

Ideal for exchanges, gaming platforms, CFD/forex brokers, or any app with user accounts.

How It Works

1. Generate Wallet     →  POST /api/v1/public/wallet/generate
2. Share Address       →  Give user their TRC20/ERC20 deposit address
3. User Deposits       →  User sends USDT
4. Auto-Detection      →  Cron detects deposit every 10 seconds
5. Webhook             →  Deposit confirmation sent
6. Check Balance       →  GET /api/v1/public/wallet/balance/{userId}

Each user gets two addresses — one TRC20, one ERC20 — generated in a single API call.

Rate Limits

Endpoint	Tier	Limit
`POST /public/wallet/generate`	Wallet Gen	20 / 15 min
`GET /public/wallet/view/{userId}`	Standard	100 / 15 min
`GET /public/wallet/balance/{userId}`	Standard	100 / 15 min
`POST /public/wallet/updateBalance`	Financial	30 / 15 min
`GET /public/user/transaction/list`	Standard	100 / 15 min

Generate a Wallet

POST /api/v1/public/wallet/generate

Auth: apikey header

Parameter	Type	Required	Description
`userId`	string	Yes	Your internal user ID
`email`	string	Yes	User's email
`firstName`	string	No	User's first name
`lastName`	string	No	User's last name
`phone`	string	No	User's phone
`callbackUrl`	string	No	Webhook URL for this user's deposits
`isActive`	boolean	No	Monitor this wallet (default: true)

const response = await axios.post(
  "https://pay.3pa-y.com/api/v1/public/wallet/generate",
  { userId: "user-12345", email: "[email protected]", firstName: "Alice" },
  { headers: { apikey: "your-api-key" } }
);

// response.data.data.wallets:
// [{ walletAddress: "0x742d...", walletNetwork: "USDT-ERC20" },
//  { walletAddress: "TN7oG...", walletNetwork: "USDT-TRC20" }]

Idempotent: If a wallet exists for this userId, the existing wallet is returned (fields updated if changed).

Get Wallet Details

GET /api/v1/public/wallet/view/{userId}

Returns wallet addresses, user info, and isActive status.

Check Balance

GET /api/v1/public/wallet/balance/{userId}

const response = await axios.get(
  "https://pay.3pa-y.com/api/v1/public/wallet/balance/user-12345",
  { headers: { apikey: "your-api-key" } }
);
// response.data.data.totalBalance → 250.00
// response.data.data.wallets → per-network balance, deposit count, last deposit

Update Balance

Manually adjust a user's wallet balance (corrections, internal transfers):

POST /api/v1/public/wallet/updateBalance

Rate limit: Financial — 30 / 15 min

Parameter	Type	Required	Description
`userId`	string	Yes	Your internal user ID
`walletAddress`	string	Yes	Specific wallet to update
`amount`	number	Yes	Amount to add (positive)
`transactionHash`	string	Yes	Reference hash

Deposit Webhooks

When the payment detector identifies a wallet deposit, your webhook URL receives a notification with type: "deposit", status: "confirmed", the walletAddress, and deposit details.

Detection frequency: Every 10 seconds.

See Webhook Handling for payload structure and HMAC verification.

Fees

Same tiered fee system as invoice payments. Minimum: 1 USDT (TRC20) / 1.50 USDT (ERC20).

depositFeePayer controls who pays. Details: Settlement & Reconciliation

User Transaction History

GET /api/v1/public/user/transaction/list?userId=user-12345&type=deposit&page=1&limit=20

Parameter	Type	Required	Description
`userId`	string	Yes	Your internal user ID
`type`	string	No	`deposit`, `withdrawal`, `payout`
`status`	string	No	Filter by status
`page` / `limit`	number	No	Pagination (default: 20, max: 100)

Error Handling

Error	Code	Solution
`userId and email are required`	400	Include both fields
`Failed to generate wallet addresses`	400	Retry after a few seconds
`Wallet not found for the specified userId`	404	Generate a wallet first
`Amount must be a valid positive number`	400	Send a positive number