Exchange Rates and Fees - PCX Developer Docs

PCX applies exchange rates to all cross-currency flows. Rates are fetched per-transaction, locked at initiation, and validated at submission. Organizations can have custom rate configurations that control the spread applied on top of the underlying market rate.

Fetching a rate

Before initiating any cross-border payment or ramp, fetch the rate for the corridor:

GET /organizations/admin/exchange-rate
  ?orgId=org_xxxx
  &fromCurrency=NGN
  &toCurrency=KES

Response:

{
  "org_rate_id": "258b95aa-a76f-4144-ade1-23814a32900d",
  "from_currency": "NGN",
  "to_currency": "KES",
  "rate": 0.09127444176,
  "expires_at": "2026-06-04T12:00:00.000Z"
}

Store both org_rate_id and rate. Both are required when initiating a cross-border payment or ramp. For ramp flows, the corridor direction must match the ramp direction:

Ramp direction	`fromCurrency`	`toCurrency`
`on_ramp` (fiat → crypto)	Fiat currency (e.g. `NGN`)	Crypto’s fiat equivalent (e.g. `USD` for USDC)
`off_ramp` (crypto → fiat)	Crypto’s fiat equivalent (e.g. `USD`)	Fiat currency (e.g. `NGN`)

Fetching the rate in the wrong direction for a ramp request will cause a RATE_STALE error. Always align the rate fetch direction with the ramp direction.

Rate locking

When org_rate_id is included in a payment or ramp initiation, PCX locks that rate for the transaction. The payer sees the rate you fetched, and PCX guarantees the conversion at that rate regardless of market movement between fetch and settlement. Rates expire at expires_at. Initiating a payment after expiry will fail — re-fetch the rate and retry promptly.

Spread validation (ramp flows)

For on-ramp and off-ramp flows, you also submit client_rate — the rate you displayed to the user. PCX validates it against the current live rate within a 0.5% tolerance:

{
  "statusCode": 422,
  "error": "RATE_STALE",
  "message": "Rate has drifted. Please re-fetch the exchange rate."
}

When you receive RATE_STALE:

Re-fetch the rate from GET /organizations/admin/exchange-rate
Present the updated rate to the user for re-confirmation
Resubmit the ramp with the new client_rate and org_rate_id

Never cache org_rate_id values across sessions or reuse them after the user has been shown the rate.

Org rate configurations

Organizations can have custom spreads applied on top of market rates. These are managed by platform administrators:

Operation	Endpoint
Add a rate config	`POST /organizations/admin/add-rate-config`
Get rate configs for an org	`GET /organizations/admin/rate-configs/{org_id}`
Update a rate config	`PUT /organizations/admin/rate-configs/{org_id}`
Get active rate configs	`GET /organizations/admin/active-rate-configs`

A rate config defines the spread percentage for a given currency pair. When a rate is fetched for an org, the active rate config for that pair is applied to produce the org_rate_id rate.

Manual rate management

Administrators can manually set or override rates for specific organizations and corridors:

Operation	Endpoint
Add a manual rate	`POST /organizations/admin/add-rate`
Add an active rate with config	`POST /organizations/admin/add-active-rate`
List all org rates	`GET /organizations/admin/rates`
Get active rates	`GET /organizations/admin/active-rates`
Deactivate a rate	`PUT /organizations/admin/rates/{org_rate_id}/deactivate`
Delete a rate	`DELETE /organizations/admin/rates/{org_rate_id}`

Fees

PCX does not charge fees as a separate line item on payments. Fees are embedded in the spread applied via the org’s rate configuration — the rate the user sees already includes PCX’s margin. The rate returned by GET /organizations/admin/exchange-rate is the spread-adjusted rate. For a breakdown of fees collected across virtual account operations:

GET /virtual-accounts/admin/analytics/fee-analysis

This endpoint is available to internal admins and provides aggregate fee data across all accounts.

​Fetching a rate

​Rate locking

​Spread validation (ramp flows)

​Org rate configurations

​Manual rate management

​Fees

Fetching a rate

Rate locking

Spread validation (ramp flows)

Org rate configurations

Manual rate management

Fees