Wallet Payments (Per-User Wallets)
Wallet Payments
Wallet payments are designed for account-based payment flows where each end user is assigned a dedicated wallet and maintains a persistent balance over time.
This model is ideal for platforms, brokers, and applications where users deposit funds multiple times and interact with an ongoing balance.
How wallet payments work
Wallet payments follow a per-user wallet model:
- A user is created in 3PAY
- A dedicated wallet is assigned to that user
- Funds deposited to the wallet are credited to the user balance
- The balance persists across transactions
- Funds can be withdrawn or transferred according to permissions
Each wallet belongs to one user only.
User creation (required)
Before a wallet can be used, a user must be created in 3PAY.
Required user fields
The following fields are required when creating a user:
| Field | Type | Required | Description |
|---|---|---|---|
userId | string | ✅ | Unique identifier for the user in your system |
email | string | ✅ | User email address |
phone | string | ❌ | User phone number |
firstName | string | ❌ | User first name |
lastName | string | ❌ | User last name |
description | string | ❌ | Optional internal description |
userIdmust be unique and consistent across your system and 3PAY.
Wallet assignment
Once a user is created:
- A wallet is automatically associated with the user
- The wallet is used for all deposits and balance tracking
- Wallets are network-specific (e.g. ERC20, TRC20)
Wallet addresses are persistent and do not change between deposits.
Accepting payments into user wallets
To accept funds:
- Retrieve the user’s wallet details (address + network)
- Share the wallet address with the user
- User sends funds to the wallet
- 3PAY detects and confirms the on-chain transaction
- User balance is updated once settlement is complete
This flow does not require invoices.
Wallet balance & visibility
3PAY provides APIs to retrieve wallet information for a specific user.
Merchants can:
- Retrieve the current wallet balance for a user
- Retrieve wallet details, including wallet address and network
These APIs allow you to:
- Display balances inside your application
- Reconcile deposits per user
- Trigger downstream logic (trading, access, payouts)
Sandbox testing
Wallet payments can be tested in the sandbox environment.
| Network Type | Asset | Standard | Test Network |
|---|---|---|---|
| Ethereum | USDT | ERC20 | Sepolia |
| Tron | USDT | TRC20 | Nile |
If you need a testnet wallet or testnet funds, contact the 3PAY support team.
Integrating wallet payments
Wallet payments are typically used when:
- Users have accounts in your system
- Multiple deposits per user are expected
- Balances must persist over time
- Invoices are not required per transaction
If you only need one-time payments, consider Invoice Payments instead.
API reference links
Use the API Reference for implementation details.
Place the following links here using ReadMe’s API Reference linking feature:
- 🔗 Create User → link to
POST /users - 🔗 Get User Wallet Details → link to
GET /users/{userId}/wallet - 🔗 Get User Wallet Balance → link to
GET /users/{userId}/balance - 🔗 Wallet Deposit Webhooks → link to relevant webhook events
This keeps wallet logic cleanly separated between Guides and API Reference.
Important notes
- Each user has one wallet per supported network
- Sending funds on the wrong network may result in failed or delayed deposits
- Wallet balances are updated only after required confirmations
- Wallet addresses should be treated as sensitive information
Updated 17 days ago