Top-Up & Payout Management

Manage wallet top-ups and payout requests. Users can add funds via Chapa and request withdrawals to their bank accounts.

POST

/wallets/users/{userReferenceId}/topup

Create Wallet Top-Up Request

Initiate a wallet top-up using Chapa. Requires Authorization: Bearer <token>.

Query Parameters

Path:
userReferenceId: string (e.g., "ByF-USR-57988B")

Payment Methods:
Chapa | Bank_Transfer | Mobile_Money | Card

Request Body

Request

{
  "amount": 100,
  "paymentMethod": "Chapa",
  "redirectUrl": "https://example.com/callback",
  "notes": "Optional notes"
}

Response

Response (200 OK)

{
  "data": {
    "id": "uuid",
    "referenceId": "ByF-TOP-UP-3DCBCB",
    "amount": 100,
    "status": "Processing",
    "paymentMethod": "Chapa",
    "paymentUrl": "https://checkout.chapa.co/...",
    "createdAt": "2025-08-31T22:52:56.281Z",
    "wallet": { "referenceId": "ByF-USR-WAL-B7FFEC", "etbAvailableBalance": 0 }
  },
  "message": "Wallet top-up request created successfully",
  "success": true
}

GET

/wallets/topup/{walletReferenceId}/status

Get Top-Up Status

Check the status of a wallet top-up. Requires Authorization: Bearer <token>.

Query Parameters

Path:
walletReferenceId: string (e.g., "ByF-TOP-UP-3DCBCB")

Response

Response (200 OK)

{
  "data": {
    "referenceId": "ByF-TOP-UP-3DCBCB",
    "amount": 100,
    "status": "Completed",
    "paymentMethod": "Chapa",
    "completedAt": "2025-08-31T22:55:00Z"
  },
  "success": true
}

POST

/wallets/users/{userReferenceId}/payout-request

Create Payout Request

Request a withdrawal to a bank account. Requires Authorization: Bearer <token>.

Query Parameters

Path:
userReferenceId: string (e.g., "ByF-USR-57988B")

Request Body

Request

{
  "amount": "100.00",
  "bankCode": "044",
  "accountNumber": "1234567890",
  "accountName": "John Doe",
  "reason": "Monthly payout request"
}

Response

Response (200 OK)

{
  "data": {
    "id": "uuid",
    "referenceId": "ByF-PAY-REQ-81CA16",
    "requestedAmount": "100.00",
    "status": "Pending",
    "bankCode": "044",
    "accountNumber": "1234567890",
    "accountName": "John Doe",
    "reason": "Monthly payout request",
    "createdAt": "2025-09-01T18:45:20.655Z"
  },
  "message": "Payout request created successfully",
  "success": true
}

GET

/wallets/payout-requests/{referenceId}/status

Get Payout Request Status

Check the status of a payout request. Requires Authorization: Bearer <token>.

Query Parameters

Path:
referenceId: string (e.g., "ByF-PAY-REQ-81CA16")

Status Values:
Pending | Approved | Processing | Completed | Rejected | Failed

Response

Response (200 OK)

{
  "data": {
    "referenceId": "ByF-PAY-REQ-81CA16",
    "requestedAmount": "100.00",
    "status": "Approved",
    "processedAt": "2025-09-01T19:00:00Z",
    "adminNotes": "Approved after verification"
  },
  "success": true
}

POST

/wallets/payout-requests/{referenceId}/cancel

Cancel Payout Request

Cancel a pending payout request. Requires Authorization: Bearer <token>.

Query Parameters

Path:
referenceId: string (e.g., "ByF-PAY-REQ-81CA16")

Response

Response (200 OK)

{
  "success": true,
  "message": "Payout request cancelled successfully"
}

GET

/wallets/rate-limit/stats

Get Rate Limit Statistics

Retrieve rate limiting statistics for the authenticated user. Requires Authorization: Bearer <token>.

Response

Response (200 OK)

{
  "data": {
    "daily": { "count": 3, "limit": 10, "remaining": 7 },
    "weekly": { "count": 3, "limit": 50, "remaining": 47 },
    "monthly": { "count": 3, "limit": 200, "remaining": 197 }
  },
  "message": "Rate limit statistics retrieved successfully",
  "success": true
}