Mock Fund Wallet

Credit a user wallet directly for integration testing on staging. This creates a completed internal deposit (quote, transaction, and ledger entries) without simulating an external provider webhook or requiring a Virtual Bank Account (VBA).

⚠️ Staging only: This endpoint is blocked in production.

Endpoint

POST /api/v1/client/mock/fund-wallet

Description

Credits a wallet balance for testing. The endpoint:

Supports any active platform currency (e.g. USD, GHS, NGN)
Creates a completed internal deposit quote and transaction
Posts ledger entries so balances match production funding behavior
Can fund the business owner ("self") or a customer linked to your business

Use this when you need wallet balance for payouts, transfers, or exchange flows without going through VBA deposit simulation.

When to use something else

VBA / rail deposit testing — use POST /api/v1/client/mock/simulate-deposit to exercise deposit webhooks and provider rails.

Production or internal ops — admins use POST /api/v1/admin/wallets/fund (admin JWT; available in all environments, not a mock route).

Authentication

Requires HMAC authentication (Business API Key):

Note: For HMAC authentication details, see the Authentication guide.

Request Body

json

{  "user_id": "self",  "currency": "GHS",  "amount": "1000",  "narration": "Staging test funding"}

{  "user_id": "self",  "currency": "GHS",  "amount": "1000",  "narration": "Staging test funding"}

Field	Type	Required	Description
`user_id`	string	Yes	`"self"` to fund your business owner account, or the UUID of a customer registered under your business
`currency`	string	Yes	ISO 4217 code (3 letters, uppercase). Must be an active currency on the platform
`amount`	string	Yes	Amount to credit (numeric; commas allowed, e.g. `"1,000.50"`)
`narration`	string	No	Reason for the credit. Defaults to `"Client mock wallet funding (staging)"` if omitted

`user_id` values

Value	Who gets funded
`"self"`	The user who owns the business tied to your API key
Customer UUID	A user linked to your business via business–customer relationship

Success Response (201 Created)

json

{  "wallet": {    "id": "uuid",    "user_id": "uuid",    "currency": "GHS",    "currency_name": "Ghanaian Cedi",    "ledger_balance": "995.00",    "available_balance": "995.00",    "status": "ACTIVE"  },  "quote_id": "uuid",  "transaction_id": "uuid",  "transaction_reference": "TXN..."}

{  "wallet": {    "id": "uuid",    "user_id": "uuid",    "currency": "GHS",    "currency_name": "Ghanaian Cedi",    "ledger_balance": "995.00",    "available_balance": "995.00",    "status": "ACTIVE"  },  "quote_id": "uuid",  "transaction_id": "uuid",  "transaction_reference": "TXN..."}

Field	Description
`wallet`	Updated wallet after funding (balances reflect deposit fees if applicable)
`quote_id`	Internal deposit quote created for this funding
`transaction_id`	Completed transaction ID
`transaction_reference`	Human-readable transaction reference

Error Responses

Status Code	Description
`400`	Invalid request (bad amount, invalid currency code, inactive/unsupported currency)
`401`	Unauthorized — invalid or missing API key or signature
`403`	Forbidden — production environment, or `user_id` does not belong to your business
`404`	`user_id` does not exist
`500`	Internal server error

Example: cURL

Fund your business owner wallet in USD:

bash

curl -X POST "https://transfaar-test-a8d2cb980af2.herokuapp.com/api/v1/client/mock/fund-wallet" \  -H "x-api-key: your_api_key_here" \  -H "x-timestamp: 2025-01-30T12:20:15Z" \  -H "x-signature: generated_signature_here" \  -H "Content-Type: application/json" \  -d '{    "user_id": "self",    "currency": "USD",    "amount": "500.00",    "narration": "Staging balance for payout tests"  }'

curl -X POST "https://transfaar-test-a8d2cb980af2.herokuapp.com/api/v1/client/mock/fund-wallet" \  -H "x-api-key: your_api_key_here" \  -H "x-timestamp: 2025-01-30T12:20:15Z" \  -H "x-signature: generated_signature_here" \  -H "Content-Type: application/json" \  -d '{    "user_id": "self",    "currency": "USD",    "amount": "500.00",    "narration": "Staging balance for payout tests"  }'

Fund a registered customer in GHS:

bash

curl -X POST "https://transfaar-test-a8d2cb980af2.herokuapp.com/api/v1/client/mock/fund-wallet" \  -H "x-api-key: your_api_key_here" \  -H "x-timestamp: 2025-01-30T12:20:15Z" \  -H "x-signature: generated_signature_here" \  -H "Content-Type: application/json" \  -d '{    "user_id": "550e8400-e29b-41d4-a716-446655440000",    "currency": "GHS",    "amount": "10000"  }'

curl -X POST "https://transfaar-test-a8d2cb980af2.herokuapp.com/api/v1/client/mock/fund-wallet" \  -H "x-api-key: your_api_key_here" \  -H "x-timestamp: 2025-01-30T12:20:15Z" \  -H "x-signature: generated_signature_here" \  -H "Content-Type: application/json" \  -d '{    "user_id": "550e8400-e29b-41d4-a716-446655440000",    "currency": "GHS",    "amount": "10000"  }'

Example: HTTP Request

http

POST /api/v1/client/mock/fund-wallet HTTP/1.1Host: transfaar-test-a8d2cb980af2.herokuapp.comx-api-key: your_api_key_herex-timestamp: 2025-01-30T12:20:15Zx-signature: generated_signature_hereContent-Type: application/json
{  "user_id": "self",  "currency": "NGN",  "amount": "250000",  "narration": "Integration test"}

POST /api/v1/client/mock/fund-wallet HTTP/1.1Host: transfaar-test-a8d2cb980af2.herokuapp.comx-api-key: your_api_key_herex-timestamp: 2025-01-30T12:20:15Zx-signature: generated_signature_hereContent-Type: application/json
{  "user_id": "self",  "currency": "NGN",  "amount": "250000",  "narration": "Integration test"}

Notes

Active currencies only — inactive currencies (for example KES until enabled on your environment) return 400 with an unsupported currency error. Use GET /api/v1/client/currencies to see which codes are active.
Fees — Wallet deposit fee configuration may reduce the credited amount versus the requested amount (same as real internal deposits).
Wallet creation — If the user has no wallet for the currency, one is created automatically before funding.
Production — Returns 403; mock endpoints are not available in production.