> ## Documentation Index > Fetch the complete documentation index at: https://docs.mangopay.com/llms.txt > Use this file to discover all available pages before exploring further. # Conversions export const Conversion = ({content}) => {content} ; Mangopay provides foreign exchange (forex, FX) services within the Mangopay environment. Mangopay relies on a dedicated transaction type, , to convert funds between wallets of different currencies. Conversions allow you to provide FX services to your users by converting funds between their user Wallets. The same conversion transaction can be used by your platform to convert funds between your Fees Wallets and Repudiation Wallets (known in the API as Client Wallets). **Note – FX conversions available in the Dashboard** Convert funds at the click of a button thanks to the Mangopay Dashboard. Guaranteed-rate quoted conversions are available for both your platform's Fees and Repudiation Wallets, as well as user wallets. Get in touch with our teams via the Dashboard to activate the feature today. ## Types of conversions There are two types of conversion, corresponding to Mangopay’s two FX offerings. ### Instant conversion – Spot FX An instant conversion converts funds immediately at the current market rate. The rate used is returned in the conversion response. Spot FX is a one-step feature requiring one API call to execute the conversion. Between user wallets: * [POST Create an Instant Conversion between user Wallets](/api-reference/conversions/create-instant-conversion-user-wallets) Between client wallets: * [POST Create an Instant Conversion between Client Wallets](/api-reference/conversions/create-instant-conversion-client-wallets) ### Quoted conversion – Guaranteed FX A quoted conversion converts funds against a quote, which locks in the conversion rate for a pre-agreed duration. One quote defines the rate and currency pair for one conversion, which must be made before the duration expires. Guaranteed FX requires two API calls: one for the quote, one for the conversion. Use the [POST Create a Quote](/api-reference/quotes/create-quote) endpoint to create the quote, specifying the duration. You can get a quote for the sell currency by specifying the debited amount, or of the buy currency by specifying the credited amount. Once the quote is valid, you can execute a conversion by specifying the `QuoteId` in the conversion request. Between user wallets: * [POST Create a Quoted Conversion between user Wallets](/api-reference/conversions/create-quoted-conversion-user-wallets) Between client wallets: * [POST Create a Quoted Conversion between Client Wallets](/api-reference/conversions/create-quoted-conversion-client-wallets) ## Webhooks There are dedicated [event types](/webhooks/event-types#fx-conversions) for each type of conversion, which are triggered regardless of whether the conversion is between client wallets or a user's wallet: For both types of conversion, webhook notifications are sent regardless of whether funds are converted between client wallets or a user's wallets. For instant conversions: * `INSTANT_CONVERSION_CREATED` * `INSTANT_CONVERSION_SUCCEEDED` * `INSTANT_CONVERSION_FAILED` For quoted conversions: * `QUOTED_CONVERSION_CREATED` * `QUOTED_CONVERSION_SUCCEEDED` * `QUOTED_CONVERSION_FAILED` ## Constraints ### Conversions For conversions of both types – instant and quoted – the following constraints apply. **Wallets must have the same owner** User wallet conversions must take place between two wallets owned by the same user. You can’t create a conversion between a user wallet and a client wallet. [Client wallet](/api-reference/client-wallets/client-wallet-object) conversions can take place between any of the Fees Wallets or Repudiation Wallets, meaning all combinations of `FundsType` are possible: * `FEES` to `FEES` * `FEES` to `CREDIT` * `CREDIT` to `CREDIT` * `CREDIT` to `FEES` **Refunds are not available** Conversions can’t be refunded. To convert funds back, you must create another conversion with the reverse currency pair. ### Quotes The following constraints apply to quotes. Quotes: * Can only be made for a duration pre-agreed between Mangopay and the platform. * Can only be used once. * Can’t be used once they expire. * Don’t have to be used once created. * Can’t specify fees if they are to be used for client wallet conversions. ## Rates The conversion rate offered by Mangopay is expressed in two ways, both as decimal numbers: * `MarketRate` - The market rate is used to convert funds during a conversion using the formula: (`DebitedFunds.Amount` - `Fees`) \* `MarketRate` = `CreditedFunds.Amount`. The market rate fluctuates in line with FX market dynamics and is common to all platforms for the currency pair. * `ClientRate` - The indicative rate including Mangopay's markup, used during the billing cycle: `ClientRate` = `MarketRate` \* (1 - `MarginsResponse.Mangopay`). The `MarginsResponse.Mangopay.Amount` gives the amount of debited currency that will be billed by Mangopay to your platform for the transaction. Mangopay's markup is agreed during contracting and is returned as a percentage in the `MarginsResponse.Mangopay` object in the response. > Markup % = (1 - (`ClientRate` / `MarketRate`)) \* 100 ### User margin Your platform can define a `UserMargin` to be calculated for the transaction on the following endpoints: * [POST Create an Instant Conversion between user Wallets](/api-reference/conversions/create-instant-conversion-user-wallets) * [POST Create a Quote](/api-reference/quotes/create-quote) The allows you to calculate an indicative rate and amount to charge the user for the transaction, which is returned in the `MarginsResponse.User` object. The `FinalRate` your platform offered the user is returned in the `ConversionRateResponse.FinalRate`. You can define your `UserMargin` as a percentage or in pips (quantities of `0.0001`). ## Currencies Mangopay is able to offer a wide range of currencies for FX services (both Spot FX and Guaranteed FX) – see the currencies page for details. If Mangopay doesn't currently support a currency you are looking to use, contact us via the Dashboard or the Sales contact form to register your interest. **Note - Activation required for feature and currencies** In Production, foreign exchange services are subject to a contract amendment. In Sandbox, the features and their specificities (currencies and quote durations) require activation for your API credentials. For more information or to activate contact the Support team via the Dashboard. ## Managing conversions The [GET View a Conversion](/api-reference/conversions/view-conversion) endpoint returns both instant and quoted conversions between user and client wallets. * For an instant conversion, the `QuoteId` is `null`. * For a quoted conversion, the `QuoteId` contains the unique identifier of the quote against which the conversion was requested The conversion transaction behaves like other transactions, meaning it appears in the following endpoints: * [GET List Transactions for a User](/api-reference/transactions/list-transactions-user) * [GET List Transactions for a Wallet](/api-reference/transactions/list-transactions-wallet) * [GET List Transactions for a Client Wallet](/api-reference/transactions/list-transactions-client-wallet) * [POST Create a Transactions Report](/api-reference/reports/create-transactions-report) ## Use cases ### User store and convert You can offer FX services to your users from within your platform thanks to Mangopay’s wallet-based FX services. This enables your users to request payouts in a different currency, as well as re-use their funds on your platform for transactions in other currencies. The flow is as follows: 1. Use the [POST Create a Wallet](/api-reference/wallets/create-wallet) endpoint to create wallets in each currency owned by your user 2. Show the user an approximate conversion rate using the [GET View an indicative Conversion Rate](/api-reference/conversion-rates/view-conversion-rate) endpoint 3. If they wish to proceed with the currency exchange, use the [POST Create an Instant Conversion](/api-reference/conversions/create-instant-conversion-user-wallets) endpoint to convert the funds The indicative rate presented and the actual rate converted may differ slightly, so you need to communicate this to the user. A similar flow is possible using quoted conversions. The flow is as follow: 1. Use the [POST Create a Wallet](/api-reference/wallets/create-wallet) endpoint to create wallets in each currency owned by your user 2. Show the user an indicative conversion rate using the [GET View an indicative Conversion Rate](/api-reference/conversion-rates/view-conversion-rate) endpoint. 3. Use the [POST Create a Quote](/api-reference/quotes/create-quote) endpoint to freeze a conversion rate, for a given currency pair, for a duration of time. You need to communicate the duration to the user. 4. If they wish to proceed with the currency conversion, use the [POST Create a Quoted Conversion](/api-reference/conversions/create-quoted-conversion-user-wallets) endpoint to convert the funds using an active quote. If the quote has expired, create the quote again (Step 3). ### Multi-currency pricing You can list product prices in the user’s local currency before they pay. For example, a European platform can list EUR products in GBP for the UK market. The flow is as follows: 1. Display approximate GBP prices on product pages using the [GET View an indicative Conversion Rate](/api-reference/conversion-rates/view-conversion-rate) endpoint, refreshing every few minutes 2. When the buyer proceeds to checkout, use the [POST Create a Quote](/api-reference/quotes/create-quote) (GBPEUR) to guarantee their GBP price for the quote duration 3. Create a GBP pay-in to the buyer’s GBP wallet 4. Use the [POST Create a Quoted Conversion](/api-reference/conversions/create-quoted-conversion-user-wallets) to convert the funds to the buyer’s EUR wallet Both the pay-in and conversion needs to happen before the quote expires, so you should trigger the conversion on the successful pay-in. If the quote expires before the buyer completes their checkout, then you can refresh the quote and display a new guaranteed price. ## Related resources View an indicative Conversion Rate The Quote object The Conversion object