---
title: "New FX-Conversion"
method: POST
path: "/fx-conversion"
tags: ["FX-Conversion"]
---

# New FX-Conversion

`POST /fx-conversion`

## Request

- Base URL: `https://api.finmo.net/v1`
- URL: `https://api.finmo.net/v1/fx-conversion`
- Auth: HTTP basic

Convert money from one currency to another using spot FX rates and, upon success the API will return the details of the completed conversion.

If you have an FX rate (```fx_rate_id```) obtained previously from the [Get FX Rate](/reference/newfx-rate-1) API, you can use it for the conversion. If no ```fx_rate_id``` is provided, the platform will use the live rate for the conversion.

Most conversions are completed within 2 minutes or less. However, since Finmo uses live rates, conversions may not occur instantly on non-trading days. In such cases, Finmo will send an ```FX_CONVERSION_COMPLETE``` webhook notification once the conversion is completed.

Currently, Finmo does not support the cancellation of FX-Conversions. The platform operates on a good funds model, always checking the balance in the source currency before proceeding. Cancellation could result in a loss due to fluctuating spot rates.

## Headers

- `x-env` string, required

## Request body

- object
  - `source_currency` string, required: Source (sending) currency code. It has to be a valid ISO 4217 currency code.
  - `target_currency` string, required: Target (receiving) currency code. It has to be a valid ISO 4217 currency code.
  - `source_amount` number, nullable, required: **Conditionally required:** Either source_amount or target_amount is required, never both. Amount in source currency.
  - `target_amount` number, nullable, required: **Conditionally required:** Either source_amount or target_amount is required, never both. Amount in target currency.
  - `fx_rate_id` string: FX Rate ID received in Get FX Rates API response.
  - `organization_reference_id` string: A reference you can later use to identify this payment, such as an order number. Can only be alphanumeric and must be unique for Benefit.
  - `webhook_url` string: Custom webhook url. If it is not provided, webhook will be triggered to the endpoint configured in the Dashboard.
  - `metadata` object: Custom Data

## Response `201`

Created

- object
  - `data` object
    - `completed_at` string, date-time, nullable
    - `convert_at` string, date-time
    - `created_at` string, date-time
    - `credit_transaction_id` string, nullable
    - `credit_wallet_id` string
    - `credit_wallet_transaction_id` string, nullable
    - `customer_id` string
    - `debit_transaction_id` string, nullable
    - `debit_wallet_id` string
    - `debit_wallet_transaction_id` string
    - `fixed_side` string
    - `fx_conversion_id` string
    - `fx_rate` number
    - `fx_rate_id` string
    - `invoice_id` string
    - `metadata` string, nullable
    - `org_id` string
    - `organization_reference_id` string
    - `scope` string
    - `settle_by` string
    - `source_amount` number
    - `source_currency` string
    - `status` string
    - `target_amount` integer
    - `target_currency` string
    - `updated_at` string, date-time
    - `webhook_url` string, uri, nullable
  - `request_id` string
  - `request_time` string, date-time
  - `status_code` integer
  - `status_text` string
  - `success` boolean

## Other responses

- `400`: Bad Request
- `404`: Not Found
- `406`: Not Acceptable

## Changes

- **2026-11-03** `39e5e5ab5c3a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/finmo/apis/finmo-api/changes/fx-conversion/post.md)

---

[API](https://skmtc.dev/finmo/apis/finmo-api.md) - [All operations](https://skmtc.dev/finmo/apis/finmo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/finmo/apis/finmo-api/revisions/39e5e5ab5c3a?raw)