Get Wallets API

The Get Wallet API fetches a user's wallet based on the specified currency and country parameters.

Endpoint

GET {{baseURL}}/v1/wallet?currency={currency}&country={country}

This API requires two query parameters: currency and country.

Request Example

curl --location --request GET '{{baseURL}}/v1/wallet?currency=NGN&country=NG' \
--header 'x-api-key: `YOUR_API_KEY' \
--header 'Content-Type: application/json'

Request Headers

Header	Description	Required	Example Value
`x-api-key`	API key for authentication	✅ Yes	`YOUR_API_KEY`
`Content-Type`	The content type of the request	✅ Yes	`application/json`

Query Parameters

Parameter	Type	Description	Required	Example Value
`currency`	String	The currency code for the wallet (ISO 4217)	✅ Yes	`NGN`
`country`	String	The country code (ISO 3166-1 alpha-2)	✅ Yes	`NG`

Sucessful Response Example (200 OK)

If the request is successful, the API returns the following JSON response:

response.json

{
    "message": "wallets fetched successfully",
    "status": "success",
    "data": [
        {
            "id": "cfd2de64-a896-4405-8736-xxxxxxxxxxxxx",
            "balance": 23094071.00,
            "currency": "NGN",
            "country": "NG"
        }
    ]
}

Response Breakdown**

General Information

Field	Type	Description
`message`	String	Confirmation message indicating success
`status`	String	Indicates success or failure

Data Details

Field	Type	Description
`id`	String	Unique identifier for the wallet
`balance`	Number	Wallet balance
`currency`	String	Currency code (e.g., NGN)
`country`	String	Country code (e.g., NG)

Error Responses

Status Code	Meaning	Example Response	How to Handle
400	Bad Request (Missing or Invalid Query Params)	currency and country are required	Ensure both `currency` and `country` query parameters are included and valid.
401	Unauthorized (Invalid API Key)	Invalid authentication credentials	Check that the `x-api-key` header is present and the key is valid.
403	Forbidden (Non-whitelisted IP)	Your IP address is not allowed to access this service	Add your IP to the allowed list in the API Management section of the Dashboard.
404	Wallet Not Found	Wallet for the given currency and country not found	Confirm that a wallet exists for the provided `currency` and `country` combination.
422	Unprocessable Entity	Invalid parameter value	Validate the `currency` and `country` values against supported formats and values.
429	Too Many Requests	API rate limit exceed	Implement retry logic with backoff; do not exceed allowed number of requests per second.
500	Internal Server Error	An unexpected error occurred on the server	Retry the request after some time or contact support if issue persists.

Best Practices

✅ Include a valid x-api-key in the request headers to authenticate the request.
✅ Ensure that the currency and country parameters are valid and correctly formatted.
✅ Handle potential errors in case the wallet data is not found or the request fails.

How Wallets work in meCash Get Wallet Balance