# 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:**
```json
{
"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**
```json
{
"status": "error",
"message": "Customer email is required for API requests."
}
```
```json
{
"status": "error",
"message": "Redirect URL is required for API requests."
}
```
* **401 Unauthorized**
```json
{
"error": "Unauthorized"
}
```
* **403 Forbidden**
```json
{
"status": "error",
"message": "You do not have permission to access this company's wallet."
}
```
* **404 Not Found**
```json
{
"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**
```json
{
"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:**
```json
{
"status": "success",
"transaction_status": "pending",
"transaction": {
"transaction_reference": "TOPUP_1234567890",
"amount": 1000.00,
"status": "pending",
"type": "top_up"
}
}
```
**Error Responses:**
* **401 Unauthorized**
```json
{
"error": "Unauthorized"
}
```
* **403 Forbidden**
```json
{
"status": "error",
"message": "You do not have permission to access this company's transactions."
}
```
* **404 Not Found**
```json
{
"status": "error",
"message": "Transaction not found."
}
```
* **500 Internal Server Error**
```json
{
"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:**
```http
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": "user@example.com",
"redirect_url": "https://yourapp.com/payment/callback",
"company_id": 123
}
```
**Response:**
```json
{
"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:**
```http
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):**
```json
{
"status": "success",
"transaction_status": "pending",
"transaction": {
"transaction_reference": "TOPUP_1234567890",
"amount": 5000.00,
"status": "pending",
"type": "top_up"
}
}
```
**Response (Success):**
```json
{
"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 .
***
**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.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.gangmates.com/api-documentation/api-reference/wallet-top-up.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.