Currency Codes

FLUID Network uses ISO 4217 currency codes for all transactions. This reference provides details on the supported currency, formatting rules, and validation requirements.

Supported Currency

FLUID Network currently operates exclusively in Ghana and supports:

Currency	Code	Symbol	Decimal Places	Country
Ghanaian Cedi	`GHS`	₵	2	Ghana

SINGLE CURRENCY LAUNCH

FLUID Network is launching with Ghana-only support. All transactions must use GHS (Ghanaian Cedi). Future expansion to additional countries and currencies is planned.

Currency Format Requirements

General Rules

All currency amounts must follow these requirements:

Format: Decimal number with exactly 2 decimal places
Separator: Use period (.) as decimal separator (not comma)
No currency symbols: Use numeric values only
No thousands separators: Do not include commas or spaces
Currency Code: Must always be GHS (uppercase)

Valid Examples:

Invalid Examples:

100          # Missing decimal places
100.5        # Only 1 decimal place
100.000      # Too many decimal places
1,000.00     # Contains comma separator
₵100.00      # Contains currency symbol

JSON Request Format

json

{
  "amount": 100.00,
  "currency": "GHS"
}

Validation Rules

Amount Validation:

Must be a positive number
Must have exactly 2 decimal places
Must be within GHS transaction limits
Cannot be zero or negative

Currency Code Validation:

Must be GHS (uppercase)
Case-sensitive validation
Must match ISO 4217 standard

GHS - Ghanaian Cedi

Currency Information:

Country: Ghana
Symbol: ₵
Decimal Places: 2
ISO Code: GHS
Numeric Code: 936
Subunit: Pesewa (1 GHS = 100 pesewas)

Transaction Limits

Limit	Amount	Notes
Minimum Transaction	₵1.00	Enforced per transaction
Maximum Transaction	₵10,000.00	May vary by bank
Daily Limit	₵50,000.00	Cumulative per payment provider

BANK-SPECIFIC LIMITS

Individual banks may have lower transaction limits. Always check bank-specific limits using the List Banks API.

Supported Banks

All banks in the FLUID Network operate in Ghana and use GHS:

Example Bank Ghana (EXB)
Sample Bank (SAM)
Demo Bank Ghana (DEM)
Test Bank Ghana (TST)

Example Transaction

json

{
  "phone_number": "+233241234567",
  "bank_identifier": "EXB",
  "amount": 150.00,
  "currency": "GHS",
  "narration": "Payment for goods",
  "partner_reference": "ORD-12345"
}

Currency Validation

API Validation

The FLUID API validates currency codes and amounts at multiple stages:

Valid Request:

bash

curl -X POST https://api.fluid-network.com/api/v1/payment-providers/debit-requests/charge \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+233241234567",
    "bank_identifier": "EXB",
    "amount": 100.00,
    "currency": "GHS",
    "narration": "Test payment",
    "partner_reference": "TEST-001"
  }'

Validation Errors

Invalid Currency Code:

json

{
  "success": false,
  "error": {
    "code": 3422,
    "message": "Validation failed",
    "category": "validation"
  },
  "details": {
    "currency": ["must be GHS"]
  }
}

Invalid Amount Format:

json

{
  "success": false,
  "error": {
    "code": 3422,
    "message": "Validation failed",
    "category": "validation"
  },
  "details": {
    "amount": ["must have exactly 2 decimal places"]
  }
}

Amount Below Minimum:

json

{
  "success": false,
  "error": {
    "code": 3422,
    "message": "Validation failed",
    "category": "validation"
  },
  "details": {
    "amount": ["must be at least 1.00 GHS"]
  }
}

Amount Above Maximum:

json

{
  "success": false,
  "error": {
    "code": 3422,
    "message": "Validation failed",
    "category": "validation"
  },
  "details": {
    "amount": ["must not exceed 10000.00 GHS"]
  }
}

Implementation Examples

Amount Formatting

Format amount to 2 decimal places:

bash

# Bash example
amount=100
formatted_amount=$(printf "%.2f" "$amount")
echo "$formatted_amount"  # Output: 100.00

# Validate decimal places
if [[ $formatted_amount =~ ^[0-9]+\.[0-9]{2}$ ]]; then
  echo "Valid format"
else
  echo "Invalid format"
fi

Language-Specific Implementations:

JavaScript: parseFloat(amount).toFixed(2)
Python: f"{amount:.2f}" or "{:.2f}".format(amount)
PHP: number_format($amount, 2, '.', '')
Ruby: "%.2f" % amount or format("%.2f", amount)

Currency Validation

Validate currency code:

bash

# Bash example
currency="GHS"

if [ "$currency" = "GHS" ]; then
  echo "Currency valid"
else
  echo "Invalid currency: Only GHS is supported"
fi

Implementation Notes:

Currency code must be exactly GHS (uppercase)
Reject lowercase ghs or mixed case Ghs
No other currency codes are accepted

Amount Range Validation

Validate amount is within GHS limits:

bash

# Bash example
amount=150.00
currency="GHS"
min_amount=1.00
max_amount=10000.00

# Convert to pesewas for comparison
amount_pesewas=$(echo "$amount * 100" | bc | cut -d. -f1)
min_pesewas=$(echo "$min_amount * 100" | bc | cut -d. -f1)
max_pesewas=$(echo "$max_amount * 100" | bc | cut -d. -f1)

if [ "$amount_pesewas" -lt "$min_pesewas" ]; then
  echo "Amount too low: minimum is ₵$min_amount"
elif [ "$amount_pesewas" -gt "$max_pesewas" ]; then
  echo "Amount too high: maximum is ₵$max_amount"
else
  echo "Amount is valid"
fi

Implementation Notes:

Compare amounts as integers (multiply by 100 to avoid float precision issues)
Validate before making API calls to provide better user feedback
Consider bank-specific limits which may differ from defaults

Best Practices

Currency Handling:

✅ Always use GHS as the currency code
✅ Always format amounts with exactly 2 decimal places
✅ Store amounts as integers in pesewas (1 GHS = 100 pesewas)
✅ Use uppercase GHS (not ghs or Ghs)
✅ Check amount is within ₵1.00 - ₵10,000.00 range before API call
✅ Use proper data types (Decimal/BigDecimal, not Float)
✅ Display ₵ symbol in user interface

Avoid Common Mistakes:

❌ Don't use currencies other than GHS (NGN, KES, USD not supported)
❌ Don't use floating-point arithmetic for money (precision errors)
❌ Don't include currency symbols in API requests
❌ Don't use comma as decimal separator
❌ Don't include thousands separators in amounts
❌ Don't forget to validate decimal places

Working with Pesewas

Converting Between GHS and Pesewas

GHS to Pesewas:

bash

# Multiply by 100 to get pesewas
ghs_amount=100.50
pesewas=$(echo "$ghs_amount * 100" | bc | cut -d. -f1)
echo "$pesewas"  # Output: 10050

Pesewas to GHS:

bash

# Divide by 100 to get GHS
pesewas=10050
ghs_amount=$(echo "scale=2; $pesewas / 100" | bc)
echo "$ghs_amount"  # Output: 100.50

Why Use Pesewas:

Avoid floating-point precision errors
Store amounts as integers in database
Perform accurate calculations without rounding issues
Convert to GHS with 2 decimals only when displaying or sending to API

Testing

Sandbox Testing

Use these test amounts in sandbox environment (all in GHS):

Successful Transactions:

100.00 - Completes successfully
50.00 - Completes after brief delay
250.00 - Completes successfully

Failed Transactions:

0.50 - Below minimum (validation error)
99999.00 - Above maximum (validation error)
100.5 - Invalid decimal format (validation error)
100 - Missing decimals (validation error)

Edge Cases:

1.00 - Minimum valid amount
10000.00 - Maximum valid amount
9999.99 - Near maximum

Test Request Example

bash

curl -X POST https://sandbox-api.fluid-network.com/api/v1/payment-providers/debit-requests/charge \
  -H "Authorization: Token YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+233241234567",
    "bank_identifier": "EXB",
    "amount": 100.00,
    "currency": "GHS",
    "narration": "Test GHS payment",
    "partner_reference": "TEST-GHS-001"
  }'

Error Handling

Common Currency Errors

Error	Cause	Solution
`currency must be GHS`	Wrong currency code provided	Use `GHS` (uppercase only)
`amount must have 2 decimal places`	Wrong decimal format	Format: `100.00` not `100` or `100.5`
`amount below minimum`	Amount < ₵1.00	Use minimum ₵1.00
`amount above maximum`	Amount > ₵10,000.00	Split into multiple transactions or check bank limit

Error Response Format

json

{
  "success": false,
  "error": {
    "code": 3422,
    "message": "Validation failed",
    "category": "validation"
  },
  "details": {
    "amount": ["must have exactly 2 decimal places"],
    "currency": ["must be GHS"]
  }
}

Country Codes Reference - Ghana phone format and codes
List Banks API - Check GHS transaction limits per bank
Create Charge API - Initiate GHS transactions
Error Codes Reference - Complete error code list

Support

Need help with currency codes or formatting?

Email: support@fluidnetwork.africa
Documentation: https://fluidnetwork.africa/docs

Currency Codes ​

Supported Currency ​

Currency Format Requirements ​

General Rules ​

JSON Request Format ​

Validation Rules ​

GHS - Ghanaian Cedi ​

Transaction Limits ​

Supported Banks ​

Example Transaction ​

Currency Validation ​

API Validation ​

Validation Errors ​

Implementation Examples ​

Amount Formatting ​

Currency Validation ​

Amount Range Validation ​

Best Practices ​

Working with Pesewas ​

Converting Between GHS and Pesewas ​

Testing ​

Sandbox Testing ​

Test Request Example ​

Error Handling ​

Common Currency Errors ​

Error Response Format ​

Related Resources ​

Support ​

Currency Codes

Supported Currency

Currency Format Requirements

General Rules

JSON Request Format

Validation Rules

GHS - Ghanaian Cedi

Transaction Limits

Supported Banks

Example Transaction

Currency Validation

API Validation

Validation Errors

Implementation Examples

Amount Formatting

Currency Validation

Amount Range Validation

Best Practices

Working with Pesewas

Converting Between GHS and Pesewas

Testing

Sandbox Testing

Test Request Example

Error Handling

Common Currency Errors

Error Response Format

Related Resources

Support