The Unified Payment Format: PAYIN_ORANGE_CI

json{
    "amount": 5000,
    "currency": "XOF",
    "country": "CI",
    "payment_method": "mobile_money",
    "payment_method_detail": "orange_money",
    "customer": {
        "phone": "+2250709757296",
        "email": "[email protected]"
    }
}

PAYIN_ORANGE_CI
  |     |     |
  |     |     └── Country code (CI = Ivory Coast)
  |     └──────── Operator (ORANGE = Orange Money)
  └────────────── Operation type (PAYIN = payment in)

json{
    "amount": 5000,
    "payment_method": "PAYIN_ORANGE_CI",
    "customer": {
        "phone": "+2250709757296"
    }
}

PAYIN_{OPERATOR}_{COUNTRY_CODE}

python# services/routing.py

COUNTRY_CURRENCY_MAP = {
    # UEMOA Zone (West African CFA Franc)
    "CI": "XOF",   # Ivory Coast
    "SN": "XOF",   # Senegal
    "ML": "XOF",   # Mali
    "BF": "XOF",   # Burkina Faso
    "BJ": "XOF",   # Benin
    "TG": "XOF",   # Togo
    "NE": "XOF",   # Niger
    "GW": "XOF",   # Guinea-Bissau

    # CEMAC Zone (Central African CFA Franc)
    "CM": "XAF",   # Cameroon
    "GA": "XAF",   # Gabon
    "CG": "XAF",   # Congo
    "TD": "XAF",   # Chad
    "CF": "XAF",   # Central African Republic
    "GQ": "XAF",   # Equatorial Guinea

    # East Africa
    "KE": "KES",   # Kenya
    "TZ": "TZS",   # Tanzania
    "UG": "UGX",   # Uganda
    "RW": "RWF",   # Rwanda

    # Southern Africa
    "ZA": "ZAR",   # South Africa
    "ZM": "ZMW",   # Zambia
    "MW": "MWK",   # Malawi
    "MZ": "MZN",   # Mozambique

    # West Africa (non-CFA)
    "GH": "GHS",   # Ghana
    "NG": "NGN",   # Nigeria
    "SL": "SLE",   # Sierra Leone
    "GM": "GMD",   # Gambia
    "GN": "GNF",   # Guinea

    # Other
    "MG": "MGA",   # Madagascar
    "CD": "CDF",   # Democratic Republic of Congo
    "EG": "EGP",   # Egypt

    # Global (multi-currency)
    "GLOBAL": None,
}

python# In routes/payments.py
@router.post("/v1/payments")
async def initiate_payment(request: Request, data: PaymentInitiate, auth: dict = Depends(get_auth_context)):
    # Resolve the unified payment method
    method_info = resolve_payment_method(data.payment_method)
    # method_info = {
    #     "code": "PAYIN_ORANGE_CI",
    #     "operator": "ORANGE",
    #     "country": "CI",
    #     "currency": "XOF",
    # }

    # Currency is auto-detected (merchant can override for GLOBAL methods)
    currency = data.currency or method_info["currency"]
    if not currency:
        raise HTTPException(
            400, "Currency required for global payment methods"
        )

    country = method_info["country"]

    # Auto-generate customer email from phone hash
    if not data.customer.get("email") and data.customer.get("phone"):
        phone_hash = hashlib.md5(
            data.customer["phone"].encode()
        ).hexdigest()[:8]
        data.customer["email"] = f"{phone_hash}@mail.0fee.dev"

    # Route to provider
    route = await get_provider_for_unified_method(
        data.payment_method, auth["app_id"], auth["environment"]
    )
    # route = {
    #     "provider_id": "paiementpro",
    #     "provider_method_code": "OMCIV2",
    #     "priority": 1,
    # }

    # ... initiate payment with provider ...

bashcurl -X POST https://api.0fee.dev/v1/payments \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "payment_method": "PAYIN_ORANGE_CI",
    "customer": {
      "phone": "+2250709757296",
      "firstName": "Amadou",
      "lastName": "Diallo"
    }
  }'

json{
    "success": true,
    "data": {
        "id": "txn_749b8b1afbd846eaba95",
        "status": "pending",
        "provider": "paiementpro",
        "amount": 5000,
        "currency": "XOF",
        "country": "CI",
        "payment_method": "PAYIN_ORANGE_CI",
        "customer": {
            "phone": "+2250709757296",
            "email": "[email protected]"
        },
        "created_at": "2025-12-12T10:15:30Z"
    }
}

bash# Get all methods for Ivory Coast
curl https://api.0fee.dev/v1/countries/CI

{
    "country": "CI",
    "name": "Ivory Coast",
    "currency": "XOF",
    "payment_methods": [
        {
            "code": "PAYIN_ORANGE_CI",
            "name": "Orange Money",
            "type": "mobile_money",
            "operator": "Orange"
        },
        {
            "code": "PAYIN_MTN_CI",
            "name": "MTN Mobile Money",
            "type": "mobile_money",
            "operator": "MTN"
        },
        {
            "code": "PAYIN_WAVE_CI",
            "name": "Wave",
            "type": "mobile_money",
            "operator": "Wave"
        },
        {
            "code": "PAYIN_MOOV_CI",
            "name": "Moov Money",
            "type": "mobile_money",
            "operator": "Moov"
        },
        {
            "code": "PAYIN_CARD_GLOBAL",
            "name": "Card Payment",
            "type": "card",
            "operator": null
        }
    ]
}

bash# Get details for a specific method
curl https://api.0fee.dev/v1/payin-methods/PAYIN_ORANGE_CI

{
    "code": "PAYIN_ORANGE_CI",
    "name": "Orange Money Ivory Coast",
    "country": "CI",
    "currency": "XOF",
    "type": "mobile_money",
    "operator": "Orange",
    "min_amount": 100,
    "max_amount": 1000000,
    "providers": [
        {"provider_id": "paiementpro", "priority": 1},
        {"provider_id": "pawapay", "priority": 2},
        {"provider_id": "hub2", "priority": 3}
    ]
}