Top Up Wallet

Credits wallet after a supported external payment gateway transaction.

Required body fields: amount, paymentGateway, currency. Conditional: reference required for Paystack; paymentIntentId required for Stripe; paymentId required for PayPal. currency is code such as NGN, USD, GBP.

Response fields: message, transactionId, amount, walletBalance.

Possible errors:

• 400: Invalid amount - amount is missing, non-numeric, or less than 1.
• 404: User not found - authenticated customer was not found downstream.
• 404: Currency not found - supplied currency code is unknown.
• 400: Payment method is disabled - selected gateway is not active for the currency.
• 400: This transaction cannot be completed - duplicate reference/payment id detected.
• 400: Reference is required - Paystack top-up requires reference.
• 400: Payment Intent is required - Stripe top-up requires paymentIntentId.
• 400: Payment Id is required - PayPal top-up requires paymentId.
• 400: Missing One or More Required Parameters - required body/query fields were not supplied.
• 401: Unauthorized - token is missing, expired, invalid, or the account/token pair was not found.
• 403: Access denied - gateway traffic guard/rate policy blocked the request.
• 429: Too many requests - gateway rate limit exceeded.
• 500: Unexpected Error - unhandled gateway or downstream service failure.