Skip to main content
GET
/
pricing
/
calculate
# Basic conversion — no discrimination
curl "https://api.khaime.com/api/v1/partner/pricing/calculate?amount=10000&target_currency=NGN" \
  -H "X-API-Key: pk_sandbox_your_key"

# With product_id — discrimination applied if a rule exists for NG
curl "https://api.khaime.com/api/v1/partner/pricing/calculate?amount=10000&target_currency=NGN&product_id=3046" \
  -H "X-API-Key: pk_sandbox_your_key"

# USD is ambiguous — pass customer_country explicitly
curl "https://api.khaime.com/api/v1/partner/pricing/calculate?amount=10000&target_currency=USD&product_id=3046&customer_country=NG" \
  -H "X-API-Key: pk_sandbox_your_key"

# Auto-detect currency from customer IP
curl "https://api.khaime.com/api/v1/partner/pricing/calculate?amount=10000" \
  -H "X-API-Key: pk_sandbox_your_key"

Documentation Index

Fetch the complete documentation index at: https://docs.khaime.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Calculate Pricing

Convert an amount from the merchant’s baseline currency to a target currency using Khaime’s exchange rates. Useful for displaying localized prices before creating a charge. If target_currency is not provided, Khaime auto-detects the customer’s currency from their IP address. If product_id is provided, any active price discrimination rule for the customer’s country is applied to the amount before currency conversion.

​
Query Parameters

​
amount
integer
required
Amount in the merchant’s baseline currency (smallest unit: cents, kobo, etc.).
​
target_currency
string
Target currency code (e.g., NGN, EUR). If omitted, auto-detected from the customer’s IP address.
​
source_currency
string
Source currency to convert from. Defaults to the merchant’s baseline currency.
​
product_id
integer
Optional. When provided, Khaime looks up any active price discrimination rule for the product and applies it before converting. The customer’s country is derived from target_currency (e.g., NGN → NG) unless customer_country is explicitly set.
​
customer_country
string
Override for the customer’s country used in rule lookup. 2-letter ISO code (e.g., NG). Only needed when target_currency is ambiguous (e.g., USD is used in many countries) and you know the customer’s exact location.
​
sub_merchant_id
integer
For marketplace integrations. When provided, pricing uses the sub-merchant’s baseline currency instead of the marketplace’s.

​
Response

{
  "success": true,
  "data": {
    "pricing": {
      "base": {
        "amount": 10000,
        "currency": "USD",
        "formatted": "$100.00"
      },
      "local": {
        "amount": 16675000,
        "currency": "NGN",
        "formatted": "₦166,750.00"
      },
      "conversion": {
        "rate": 1450.1,
        "source": "wise_api",
        "applied": true
      }
    },
    "price_discrimination": {
      "original_base_price": 10000,
      "discrimination_amount": 1500,
      "discrimination_percentage": 0.15,
      "adjusted_base_price": 11500,
      "country_triggered": "NG"
    },
    "customer": {
      "location": {
        "country": "Nigeria",
        "country_code": "NG",
        "detected_from": "ip_address"
      },
      "currency": {
        "code": "NGN",
        "detected": false,
        "override": true
      }
    }
  },
  "meta": {
    "timestamp": "2026-03-28T14:00:00.000Z",
    "request_id": "req_1711630800000",
    "version": "v1",
    "mode": "sandbox"
  }
}

​
Response Fields

FieldTypeDescription
pricing.baseobjectOriginal amount in merchant’s baseline currency
pricing.localobjectConverted amount in the target currency (after any discrimination)
pricing.local.formattedstringHuman-readable formatted price (e.g., "₦166,750.00")
pricing.conversion.ratenumberExchange rate applied
pricing.conversion.sourcestringRate source: wise_api, custom, api, or none
pricing.conversion.appliedbooleantrue if conversion was applied
price_discriminationobject | nullDiscrimination breakdown if a rule matched; null otherwise
price_discrimination.original_base_priceintegerAmount before the adjustment
price_discrimination.discrimination_amountintegerAmount added or subtracted
price_discrimination.discrimination_percentagenumberDecimal percentage (e.g., 0.15 for +15%)
price_discrimination.adjusted_base_priceintegerAmount after discrimination, before conversion
price_discrimination.country_triggeredstringISO-2 country code that matched the rule
customer.locationobjectGeo-detected location (present when target_currency is omitted)
customer.currency.detectedbooleantrue if currency was auto-detected from IP

​
How country is determined

When product_id is provided, Khaime resolves the customer’s country in this order:
  1. Explicit customer_country query parameter
  2. Country mapped from target_currency (e.g., NGN → NG, GHS → GH)
  3. IP geolocation fallback
For unambiguous currencies (NGN, GHS, KES, etc.) you don’t need to pass customer_country — the currency alone is sufficient.
price_discrimination is only included in the response when product_id is provided. Without a product, Khaime has no rule context to evaluate.
When target_currency matches the merchant’s baseline currency, conversion.applied is false and pricing.base equals pricing.local.
# Basic conversion — no discrimination
curl "https://api.khaime.com/api/v1/partner/pricing/calculate?amount=10000&target_currency=NGN" \
  -H "X-API-Key: pk_sandbox_your_key"

# With product_id — discrimination applied if a rule exists for NG
curl "https://api.khaime.com/api/v1/partner/pricing/calculate?amount=10000&target_currency=NGN&product_id=3046" \
  -H "X-API-Key: pk_sandbox_your_key"

# USD is ambiguous — pass customer_country explicitly
curl "https://api.khaime.com/api/v1/partner/pricing/calculate?amount=10000&target_currency=USD&product_id=3046&customer_country=NG" \
  -H "X-API-Key: pk_sandbox_your_key"

# Auto-detect currency from customer IP
curl "https://api.khaime.com/api/v1/partner/pricing/calculate?amount=10000" \
  -H "X-API-Key: pk_sandbox_your_key"