Authentication
All rate endpoints require an API key passed via the X-API-Key header. Public endpoints like /health do not require authentication.
# Example authenticated request curl -X GET https://fx.gofreshpay.com/api/v1/rates/CDF \ -H "X-API-Key: your_api_key_here"
Contact the Moko Afrika team to obtain your partner API key.
Base URL
https://fx.gofreshpay.com
All API endpoints are relative to this base URL. HTTPS is required.
Endpoints
GET
/health
Service health check
▶
Returns API status. No authentication required.
Response 200
{ "status": "healthy", "timestamp": "2026-03-11T06:00:00.000000", "service": "FX Rate Card API" }
Try it live
GET
/api/v1/rates/{currency}
Get rate card
🔒
▶
Returns the current rate card including buy/sell rates, market data, margin info, and examples.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| currency required | string | CDF or UGX |
Headers
| Header | Value |
|---|---|
| X-API-Key required | Your partner API key |
Example Request
curl -X GET https://fx.gofreshpay.com/api/v1/rates/CDF \
-H "X-API-Key: your_api_key_here"
Response 200
{ "currency_pair": "USD/CDF", "base_currency": "USD", "target_currency": "CDF", "rates": { "buy_rate": { "value": 2165.52, "description": "Rate when we send USD to partner", "direction": "us_to_partner" }, "sell_rate": { "value": 2242.66, "description": "Rate when partner sends USD to us", "direction": "partner_to_us" }, "mid_rate": { "value": 2204.09, "description": "Market recommended rate (reference only)" } }, "margin": { "percentage": 3.5, "amount_per_usd": 77.14 }, "market_data": { "official_rate": 2188.28, "median": 2162.11, "sources_collected": 5 }, "valid_until": "2026-03-11T18:00:00" }
Try it live
Currency
API Key
GET
/api/v1/rates
Get all rate cards
🔒
▶
Returns rate cards for all supported currencies in a single request.
Headers
| Header | Value |
|---|---|
| X-API-Key required | Your partner API key |
Response 200
{ "partner": "Uganda Partner", "fetched_at": "2026-03-11T06:00:00.000000", "currencies": { "CDF": { /* Full CDF rate card */ }, "UGX": { /* Full UGX rate card */ } } }
Try it live
API Key
POST
/api/v1/calculate
Calculate conversion
🔒
▶
Calculate the local currency amount to collect or pay for a given USD amount.
Request Body application/json
| Field | Type | Description |
|---|---|---|
| currency required | string | CDF or UGX |
| usd_amount required | number | Amount in USD (must be > 0) |
| direction required | string | to_drc — partner sends to DRCfrom_drc — DRC sends to partner |
Example Request
curl -X POST https://fx.gofreshpay.com/api/v1/calculate \ -H "X-API-Key: your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "currency": "UGX", "usd_amount": 100, "direction": "to_drc" }'
Response 200
{ "currency": "UGX", "usd_amount": 100, "local_currency_amount": 378450.00, "rate_used": 3784.50, "rate_type": "sell", "direction": "to_drc", "description": "Partner collects 378450.00 UGX", "calculated_at": "2026-03-11T06:00:00.000000", "rate_valid_until": "2026-03-11T18:00:00" }
Try it live
API Key
Currency
USD Amount
Direction
Rate Types
Understanding which rate to use for your transactions:
| Rate | Direction | When to Use |
|---|---|---|
| sell_rate | Partner → DRC | Partner sends USD to Moko Afrika. Collect this amount in local currency from the sender. |
| buy_rate | DRC → Partner | Moko Afrika sends USD to partner. We pay this amount in local currency per 1 USD. |
| mid_rate | Reference | Market recommended rate. Not used for transactions. |
Rate cards are valid for 6 hours. Always check the
valid_until field. Expired cards include a warning field.Error Codes
| Status | Error | Description |
|---|---|---|
| 401 | Unauthorized | Missing or invalid API key |
| 400 | Bad Request | Invalid currency, missing fields, or malformed JSON |
| 404 | Not Found | No rate data available for requested currency |
| 500 | Internal Error | Server-side error |
Error Response Format
{ "error": "Unauthorized", "message": "Invalid or missing API key" }
Supported Currencies
| Code | Currency | Country | Data Sources |
|---|---|---|---|
| CDF | Congolese Franc | DR Congo | BCC, Xe.com, ExchangeRate-API, Fawazahmed, ExchangeRate-v4 |
| UGX | Ugandan Shilling | Uganda | Xe.com, ExchangeRate-API, Fawazahmed, ExchangeRate-v4 |