> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pesaswap.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Foreign exchange (FX)

Foreign exchange lets you convert a balance from one currency to another through an FX-capable connector. It is useful when you collect in one currency — for example KES — and need to hold or settle in another.

## How it works

<Steps>
  <Step title="Check which connectors support FX">
    Not every connector can convert currency. You first see which of your connectors support FX and which currencies they cover. Choice Bank is the FX-capable connector.
  </Step>

  <Step title="Get a quote">
    A quote tells you the exchange rate, the amount you will receive in the target currency, and the total amount that will be debited in the source currency. A quote is indicative — it is not saved and does not move any money.
  </Step>

  <Step title="Execute the conversion">
    Executing records an FX transaction and starts the conversion. The transaction is saved and awaits settlement.
  </Step>

  <Step title="Settlement and ledger">
    The conversion settles, and the movement is recorded in your ledger: a debit in the source currency and a credit in the target currency.
  </Step>
</Steps>

## Transaction lifecycle

Every FX transaction moves through these statuses:

| Status      | What it means                                                 |
| ----------- | ------------------------------------------------------------- |
| `pending`   | The transaction has been recorded and is awaiting processing. |
| `confirmed` | The conversion has been confirmed with the connector.         |
| `success`   | The conversion completed and the ledger has been updated.     |
| `failure`   | The conversion did not complete.                              |
| `cancelled` | The transaction was cancelled before completing.              |

Each transaction also carries a **notification status** — `pending`, `sent`, or `failed` — which tracks whether the settlement notification reached the connector.

## When to use it

* You collect payments in KES but settle with a supplier in USD. Convert a KES balance to USD before paying out.
* You want to hold funds in a target currency to reduce exposure to exchange-rate movement between collection and settlement.