---
title: "Create a conversion"
method: POST
path: "/conversions"
tags: ["Conversions"]
---

# Create a conversion

`POST /conversions`

Creates an FX conversion, selling funds in one currency to buy funds in another.

## Headers

- `Account` string

## Request body

- object — The request body for creating an FX conversion
  - `sell` object, required — The funds being sold
    - `currency` string, required — The three-letter ISO-4217 currency code to sell
    - `amount` integer, required — The amount to convert in minor units. Minimum and maximum amounts [vary by currency](https://developer.ryftpay.com/documentation/overview/core_concepts/currencies).
  - `buy` object, required — The funds being bought
    - `currency` string, required — The three-letter ISO-4217 currency code to buy
  - `reason` string, nullable — An optional reason for the conversion
  - `termAgreement` boolean, required — Confirms the account the conversion is created for (your own or a sub account) has agreed to our [conversion terms](https://dash.ryftpay.com/about/conversion-terms). The request is rejected if this is `false`, so capture the user's agreement before creating a conversion (e.g. via a tickbox).

## Response `200`

Conversion created successfully

- Conversion
  - `id` string — The unique ID of the conversion
  - `sell` ConversionSell — The sell side of the conversion
    - `amount` integer — The gross amount being sold in minor units, before fees. When `fees` is present the fee is charged on this amount and only the remainder is converted.
    - `currency` string — The three-letter ISO-4217 currency code being sold
    - `fees` object, nullable — The FX fees charged on the conversion, in minor units of the currency. Returned once the conversion has been priced. The fee is charged on exactly one side of the conversion, so `sell.fees` and `buy.fees` are mutually exclusive. Exactly one is ever present, depending on which side the fee was charged.
      - `ryft` object, nullable — Ryft's FX fee, charged on the gross amount of whichever side carries the fee. Only present when the conversion is performed under your account.
        - `amount` integer — The fee amount in minor units of the currency
      - `platform` object, nullable — The platform's FX fee, including Ryft's FX fee. Only present when the conversion is performed on behalf of a Sub-Account.
        - `amount` integer — The platform's gross FX fee in minor units, charged on the gross amount of whichever side carries the fee. This is the full fee before Ryft's fee is taken out of it; the platform retains `amount` minus `ryftFee.amount`.
        - `ryftFee` ConversionFee
          - `amount` integer — The fee amount in minor units of the currency
  - `buy` ConversionBuy — The buy side of the conversion
    - `amount` integer, nullable — The gross amount being bought in minor units, before fees. This is the sell amount converted at `rate`, after any sell-side fee has been deducted from it. When `fees` is present, the net amount credited to the balance is this amount minus that fee. This is not returned until the conversion has been priced.
    - `currency` string — The three-letter ISO-4217 currency code being bought
    - `fees` object, nullable — The FX fees charged on the conversion, in minor units of the currency. Returned once the conversion has been priced. The fee is charged on exactly one side of the conversion, so `sell.fees` and `buy.fees` are mutually exclusive. Exactly one is ever present, depending on which side the fee was charged.
      - `ryft` object, nullable — Ryft's FX fee, charged on the gross amount of whichever side carries the fee. Only present when the conversion is performed under your account.
        - `amount` integer — The fee amount in minor units of the currency
      - `platform` object, nullable — The platform's FX fee, including Ryft's FX fee. Only present when the conversion is performed on behalf of a Sub-Account.
        - `amount` integer — The platform's gross FX fee in minor units, charged on the gross amount of whichever side carries the fee. This is the full fee before Ryft's fee is taken out of it; the platform retains `amount` minus `ryftFee.amount`.
        - `ryftFee` ConversionFee
          - `amount` integer — The fee amount in minor units of the currency
  - `rate` number, nullable — The gross exchange rate applied, before fees. `buy.amount` is the converted sell amount at this rate, net of any sell-side fee. Null until the conversion has been priced.
  - `status` 'InProgress' | 'Settled' — The status of the conversion: - `InProgress` - the conversion has been created and is being processed - `Settled` - the conversion has settled and the bought funds are available
  - `reason` string, nullable — An optional reason supplied when the conversion was created
  - `estimatedSettlementDate` string, nullable — The estimated date the conversion will settle (ISO date format). This is an estimate and may not exactly match the final settlement date. Null until the conversion has been priced — populated from the first `Conversion.updated` event onward.
  - `settledTimestamp` integer, nullable — The epoch timestamp (seconds) when the conversion settled. Null until the conversion reaches the `Settled` status.
  - `createdBy` object, nullable — The user who created the conversion. Null when the conversion was created via the API directly rather than the portal.
    - `id` string — The ID of the user who created the conversion
    - `name` string, nullable — The name of the user who created the conversion.
  - `createdTimestamp` integer — The epoch timestamp (seconds) when the conversion was created

## Other responses

- `400` — One or more inputs are invalid
- `403` — You do not have access to this resource
- `500` — An unexpected error occurred when executing this request

---

[API](https://skmtc.net/ryftpay/apis/ryft-payment-api.md) · [All operations](https://skmtc.net/ryftpay/apis/ryft-payment-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ryftpay/ryft-payment-api/revisions/778890ee7e72/schema)