API Technical Specification
Wallet Module
WALLET
1. Introduction
1.1 API Overview
| Aspect | Value |
|---|
| Base URL | /api/v1 |
| Authentication | Bearer JWT Token |
| Content-Type | application/json |
2. Wallet Endpoints
2.1 View Balance FR-002
| Method | Path | Description |
|---|
| GET | /wallet/balance | View wallet balance |
Response 200 OK:
{
"id": 1,
"currency": "VND",
"balance": 5000000,
"frozen_amount": 1000000,
"available_balance": 4000000,
"status": "active"
}
2.2 Set PIN FR-003
| Method | Path | Description |
|---|
| POST | /wallet/pin | Set or change wallet PIN |
Request Body:
{
"pin": "123456",
"confirm_pin": "123456"
}
2.3 View Transactions FR-004
| Method | Path | Description |
|---|
| GET | /wallet/transactions | View transaction history |
3. Transaction Endpoints
3.1 Deposit Funds FR-006
| Method | Path | Description |
|---|
| POST | /wallet/deposit | Deposit funds to wallet |
Request Body:
{
"amount": 1000000,
"currency": "VND",
"method": "bank_transfer",
"payment_method_id": 1
}
3.2 Request Withdrawal FR-007
| Method | Path | Description |
|---|
| POST | /wallet/withdraw | Request withdrawal |
Request Body:
{
"amount": 500000,
"payment_method_id": 1,
"pin": "123456"
}
3.3 Transfer Funds FR-008
| Method | Path | Description |
|---|
| POST | /wallet/transfer | Transfer to another wallet |
Request Body:
{
"recipient_email": "[email protected]",
"amount": 200000,
"pin": "123456"
}
4. Payment Endpoints
4.1 Pay for Service FR-011, FR-012
| Method | Path | Description |
|---|
| POST | /wallet/pay | Pay for recruitment service |
Request Body:
{
"order_type": "job_posting",
"related_id": 123,
"amount": 2000000,
"pin": "123456"
}
4.2 View Payment History FR-013
| Method | Path | Description |
|---|
| GET | /wallet/payment-orders | View payment order history |
5. Payment Methods Endpoints
| Method | Path | Description | Requirement |
|---|
| GET | /wallet/payment-methods | List payment methods | FR-005 |
| POST | /wallet/payment-methods | Add payment method | FR-005 |
| PATCH | /wallet/payment-methods/:id | Update payment method | FR-005 |
| DELETE | /wallet/payment-methods/:id | Remove payment method | FR-005 |
6. Admin Endpoints
| Method | Path | Description | Requirement |
|---|
| GET | /admin/wallet/payouts | List payout requests | FR-015 |
| PATCH | /admin/wallet/payouts/:id | Approve/reject payout | FR-015 |
| PATCH | /admin/wallet/wallets/:id/freeze | Freeze/unfreeze wallet | FR-015 |
| GET | /admin/wallet/wallets | List all wallets | FR-015 |
7. Webhook Endpoints
| Method | Path | Description |
|---|
| POST | /webhooks/payment/callback | Payment Gateway callback |
8. Error Codes
| Error Code | HTTP Status | Description |
|---|
| WALLET_001 | 404 | Wallet not found |
| WALLET_002 | 400 | Insufficient balance |
| WALLET_003 | 400 | Invalid PIN |
| WALLET_004 | 400 | Amount exceeds daily limit |
| WALLET_005 | 400 | Amount exceeds monthly limit |
| WALLET_006 | 400 | Amount below minimum |
| WALLET_007 | 400 | Wallet is frozen |
| WALLET_008 | 400 | Recipient wallet not found |
