EkonnectPay

# FX Quotes

FX quotes let you state a payment price in one currency while the customer is charged, and the merchant settles, in the currency of the merchant account. A quote locks the applicable rate and the resulting settlement amount for a short time.

For example, a KES merchant can price a collection at USD 10.00. After obtaining a quote, submit 10.00 as the request amount together with the quote details; the payment rail receives the locked KES amount.

# Before you start

  • The merchant account must be active and must have a local settlement currency.
  • An active rate for the pricing/settlement pair must exist in the rate book. The platform uses a corporate rate when available and otherwise uses the system rate. Both direct and inverse pairs are supported.
  • Obtain an access token as described in Authentication. Authenticated API requests use the normal developer API authentication and include the merchant code in the body.
  • Quotes are short-lived and single-use. Create a fresh quote if it has expired or has already been submitted.

The Amount in an FX-enabled payment request represents the pricing amount. Send it as a JSON number or decimal string. The API calculates and locks the local settlement amount in the quote response. Do not replace the request amount with PayableAmount.

# Create an authenticated quote

Use this endpoint before a receive-money/collection request or a send-money/disbursement request.

POST https://api.sandbox.ekonnectpay.com/api/fx/quote/

# Request fields

Field Required Description
MerchantCode Yes Active merchant account number.
Amount Yes Positive number or decimal string in PricingCurrency.
PricingCurrency Yes Active ISO currency code for the price, for example USD.
Flow No collection for receiving money or disbursement for sending money. Defaults to collection.
PayableCurrency No Normally omit this. The API derives it from the merchant account; when supplied, it must match that account currency.
PaymentCurrency No Currency the customer actually pays. Set this for a crypto collection, for example USDT.
curl --request POST 'https://api.sandbox.ekonnectpay.com/api/fx/quote/' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'X-API-Version: 2' \
  --header 'Content-Type: application/json' \
  --data '{
    "MerchantCode": "MERCHANT-001",
    "Amount": 10.00,
    "PricingCurrency": "USD",
    "Flow": "collection"
  }'

# Successful response

{
  "code": "200.001",
  "FxQuoteID": "c0da3f3a-7a8e-4b7a-9bbf-1e8b4b15c093",
  "PricingCurrency": "USD",
  "PricingAmount": "10.00",
  "PayableCurrency": "KES",
  "PayableAmount": "1305",
  "Rate": "130.50000",
  "Flow": "collection",
  "ExpiresAt": "2026-08-04T12:05:00+00:00",
  "status": "success"
}

PayableAmount is rounded for the settlement currency. For configured zero-decimal currencies it is a whole unit. Store the returned FxQuoteID, but do not attempt to calculate or alter the returned Rate or PayableAmount.

# Crypto collection quotes

Use a crypto collection quote when the merchant wallet is denominated in fiat but the customer will pay on-chain. PayableCurrency is derived from the merchant account; the other two currency fields describe the request:

Field Meaning Example for a KES merchant paid in USDT
PricingCurrency Currency in which the merchant prices the payment. The request Amount is expressed in this currency. KES
PayableCurrency Merchant wallet currency, derived from the merchant account. KES
PaymentCurrency Currency sent by the customer through the payment rail. USDT

For crypto collections, PricingCurrency must match the merchant account currency. The quote returns PaymentAmount: the exact on-chain amount the customer must send. Do not send the fiat Amount to the blockchain address.

{
  "MerchantCode": "PHY000000001ZC6",
  "PricingCurrency": "KES",
  "Amount": "1300.00",
  "Flow": "collection",
  "PaymentCurrency": "USDT"
}

The relevant response values are:

{
  "code": "200.001",
  "FxQuoteID": "<quote-id>",
  "PricingAmount": "1300.00",
  "PricingCurrency": "KES",
  "PayableAmount": "1300.00",
  "PayableCurrency": "KES",
  "PaymentAmount": "10.0000000000",
  "PaymentCurrency": "USDT",
  "status": "success"
}

# Use the quote in a payment request

Pass these fields into the existing receive-money, send-money, bank-payout, direct-collection, internal-transfer, or checkout initiation request:

Field Value
Amount The original pricing amount as a number or decimal string, exactly matching PricingAmount.
PricingCurrency The quote's PricingCurrency.
FxQuoteID The quote's FxQuoteID.

For a collection, create the quote with flow: "collection". For a payout or internal transfer, create it with flow: "disbursement". The quote must belong to the merchant account used by the payment and its flow, price, currency, and settlement currency must all match.

Example: extend an existing mobile-money collection request with:

{
  "Amount": 10.0,
  "PricingCurrency": "USD",
  "FxQuoteID": "c0da3f3a-7a8e-4b7a-9bbf-1e8b4b15c093"
}

The quote is consumed when the transaction is created. It cannot be reused by a retry; obtain another quote for a new payment attempt.

# Checkout quote endpoint

Checkout clients can obtain a collection quote without developer credentials. The checkout configuration response provides an fx_quote_token; submit it to the public checkout quote endpoint:

POST https://api.sandbox.ekonnectpay.com/api/checkout/fx/quote/
{
  "merchant_code": "MERCHANT-001",
  "amount": 10.0,
  "pricing_currency": "USD",
  "checkout_quote_token": "<token from checkout configuration>"
}

The public Checkout response retains its lower-case data object for browser compatibility; it does not use the Developer API response shape documented above. This endpoint always creates a collection quote: it cannot create disbursement quotes. The signed token is short-lived and requests are rate-limited. Never expose authenticated API credentials in a browser application.

The public Checkout endpoint retains its lower-case browser contract. Supply its returned quote_id and pricing_currency with the normal Checkout initiation request, while retaining the pricing amount as its amount.

# Foreign-priced checkout services

When creating or updating a fixed-price checkout service, use these fields to set a foreign price:

Field Required Description
fixed_amount Yes Set to true.
pricing_currency Yes Active price currency, different from the merchant settlement currency.
pricing_amount Yes Positive fixed price in pricing_currency.

Do not set the local amount at the same time. A service may have either a local fixed amount or a foreign fixed price, never both. A foreign-priced service requires a matching FX quote at checkout; the checkout response exposes its pricing and settlement currencies plus an fx_quote_token for this purpose.

# Limits and validation

  • Quotes expire at the timestamp returned in expires_at and can be consumed only once.
  • A quote is valid only for the merchant account, flow, pricing amount, pricing currency, and settlement currency for which it was created.
  • MerchantCode is mandatory when creating a Developer API FX quote.
  • Crypto collections support FX quotes when PaymentCurrency is supplied. Scheduled payouts do not support FX quotes.
  • Legacy snake_case Developer FX quote requests and the v1 {code, data} response remain supported for compatibility. New integrations should use the PascalCase fields and X-API-Version: 2 contract documented here.
  • Invalid, non-finite, zero, negative, or oversized prices are rejected. A request is also rejected if no active rate exists for the currency pair.

Under X-API-Version: 2, an invalid or unavailable quote returns a 400.020/400.016 response with status: "failed" and a PascalCase ResponseDescription. A missing merchant account returns 404.001 in the same shape. The legacy v1 response retains its message field. Treat these responses as non-retriable with the same quote; create a new quote only after correcting the request or refreshing an expired quote.

← Crypto Payments →