Wallet Top-Up

Overview

The Wallet Top-Up API allows you to initiate a top-up to your company's wallet using supported payment providers. The top-up process involves initiating a payment, redirecting the user to the payment provider's checkout page, and handling the asynchronous verification of the transaction.

Asynchronous Transaction Verification

When a top-up is initiated, a background job is dispatched to verify the transaction after a certain delay (e.g., 2 minutes). This means that the transaction status may not be immediately updated to "success" even after the payment is completed. You can use the Check Transaction Status endpoint to poll for the transaction status.

Endpoints

Top-Up Wallet

Initiate a wallet top-up for a company.

• Endpoint: /api/wallet/top-up

• Method: POST

Headers:

Name	Type	Description	Required
Authorization	String	Bearer token (Bearer {api_token})	Yes
Content-Type	String	application/json	Yes

Body Parameters:

Name	Type	Description	Required
amount	Float	The amount to top up (in NGN).	Yes
customer_email	String	The email of the customer initiating the top-up.	Yes
redirect_url	String	The URL to redirect to after the payment is completed. Must be a domain authorized by the company.	Yes
company_id	Int	ID of the company to top up the wallet for (defaults to authenticated company if not provided).	No

Notes:

• Job Dispatching: Upon successful initiation, a background job is dispatched to verify the transaction after a delay (e.g., 2 minutes for Flutterwave, 5 minutes for Monnify). This handles asynchronous verification of the payment.

Success Response:

• Code: 200 OK

• Content:

  {
    "status": "success",
    "checkoutUrl": "https://checkout.flutterwave.com/v3/xyz123",
    "transactionReference": "TOPUP_1234567890"
  }

  Explanation:

  • checkoutUrl: The URL where the user should be redirected to complete the payment.

  • transactionReference: A unique reference for the transaction, used for tracking and verification.

Error Responses:

• 400 Bad Request

  {
    "status": "error",
    "message": "Customer email is required for API requests."
  }

  {
    "status": "error",
    "message": "Redirect URL is required for API requests."
  }

• 401 Unauthorized

  {
    "error": "Unauthorized"
  }

• 403 Forbidden

  {
    "status": "error",
    "message": "You do not have permission to access this company's wallet."
  }

• 404 Not Found

  {
    "status": "error",
    "message": "The company you are trying to access could not be found. Please verify the company ID and try again."
  }

• 500 Internal Server Error

  {
    "status": "error",
    "message": "An unexpected error occurred while initiating the top-up."
  }

---

Check Transaction Status

Check the status of a wallet transaction.

• Endpoint: /api/wallet/transaction/status

• Method: GET

Headers:

Name	Type	Description	Required
Authorization	String	Bearer token (Bearer {api_token})	Yes

Query Parameters:

Name	Type	Description	Required
transaction_reference	String	The transaction reference obtained when initiating the top-up.	Yes
company_id	Int	ID of the company to check the transaction for (optional).	No

Notes:

• Transaction Statuses:

  • pending: The transaction is pending verification. This is common immediately after initiating the top-up or if the payment provider hasn't confirmed the payment yet.

  • success: The transaction has been successfully verified, and the wallet balance has been updated.

  • failed: The transaction failed or was canceled.

Success Response:

• Code: 200 OK

• Content:

  {
    "status": "success",
    "transaction_status": "pending",
    "transaction": {
      "transaction_reference": "TOPUP_1234567890",
      "amount": 1000.00,
      "status": "pending",
      "type": "top_up"
    }
  }

Error Responses:

• 401 Unauthorized

  {
    "error": "Unauthorized"
  }

• 403 Forbidden

  {
    "status": "error",
    "message": "You do not have permission to access this company's transactions."
  }

• 404 Not Found

  {
    "status": "error",
    "message": "Transaction not found."
  }

• 500 Internal Server Error

  {
    "status": "error",
    "message": "An unexpected error occurred while checking the transaction status."
  }

---

Transaction Verification Process

The transaction verification is handled asynchronously via background jobs. After initiating a top-up:

• A background job is dispatched to verify the transaction after a delay.

• The job checks the payment provider's API to confirm the payment status.

• Once verified, the transaction status is updated accordingly in your wallet.

Implications:

• Delayed Status Updates: The transaction status may remain as "pending" for a short period even after payment completion.

• Polling for Status: Use the Check Transaction Status endpoint to poll for the updated status if needed.

• No Immediate Confirmation: Do not assume the transaction is successful immediately after payment; always check the transaction status.

---

General Information

Notes

• All timestamps are in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).

• Error messages are designed to be clear and provide guidance on how to correct the issue.

• Job Dispatching Context: Understanding that certain operations are handled asynchronously via background jobs is crucial for proper integration.

Common HTTP Status Codes

• 200 OK: The request was successful.

• 201 Created: The resource was created successfully.

• 400 Bad Request: The request was invalid or cannot be processed.

• 401 Unauthorized: Authentication failed or was not provided.

• 403 Forbidden: The user does not have permission to access the resource.

• 404 Not Found: The requested resource was not found.

• 422 Unprocessable Entity: Validation errors occurred.

• 429 Too Many Requests: Rate limit exceeded.

• 500 Internal Server Error: An unexpected error occurred on the server.

Rate Limiting

API endpoints may be subject to rate limiting. Exceeding the rate limit will result in a 429 Too Many Requests response.

---

Examples

1. Initiating Wallet Top-Up with Job Dispatch Context

Request:

POST /api/wallet/top-up HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "amount": 5000.00,
  "customer_email": "[e-mail]",
  "redirect_url": "https://yourapp.com/payment/callback",
  "company_id": 123
}

Response:

{
  "status": "success",
  "checkoutUrl": "https://checkout.flutterwave.com/v3/xyz123",
  "transactionReference": "TOPUP_1234567890"
}

Explanation:

• After receiving this response, redirect the user to the checkoutUrl to complete the payment.

• A background job has been dispatched to verify the transaction after a delay.

• Use the transactionReference to check the transaction status later.

2. Checking Transaction Status

Request:

GET /api/wallet/check-transaction-status?transaction_reference=TOPUP_1234567890&company_id=123 HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_TOKEN

Response (Pending):

{
  "status": "success",
  "transaction_status": "pending",
  "transaction": {
    "transaction_reference": "TOPUP_1234567890",
    "amount": 5000.00,
    "status": "pending",
    "type": "top_up"
  }
}

Response (Success):

{
  "status": "success",
  "transaction_status": "success",
  "transaction": {
    "transaction_reference": "TOPUP_1234567890",
    "amount": 5000.00,
    "status": "success",
    "type": "top_up"
  }
}

---

Security Considerations

• Authentication: Ensure that the Authorization header is included in every request that requires authentication.

• Authorization: Users can only manage resources for companies they are authorized to access.

• Input Validation: Validate all inputs to prevent SQL injection and other malicious inputs.

• Redirect URLs: For wallet top-ups, ensure that the redirect_url parameter points to a domain authorized by your company.

• Handling Asynchronous Operations: Be aware that certain operations are processed asynchronously. Design your application to handle delayed updates appropriately.

---

Best Practices

• Handle Pending Transactions: Implement logic to handle transactions that are in a "pending" state, and inform users accordingly.

• Use Webhooks (if available): If webhooks are provided, utilize them to receive real-time updates on transaction statuses.

• Retry Logic: Implement retry mechanisms when polling for transaction status, with exponential backoff to avoid hitting rate limits.

• Logging and Monitoring: Keep logs of transaction references and statuses for auditing and troubleshooting purposes.

---

Contact Support

If you encounter any issues or have questions about the API, please contact our support team at [e-mail].

---

Disclaimer: This API reference is provided for informational purposes and may be subject to change. Please refer to the latest documentation available for the most up-to-date information.