> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.mangopay.com/guides/fx/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mangopay.com/_mcp/server. # Conversions Mangopay provides foreign exchange (forex, FX) services within the Mangopay environment. Mangopay relies on a dedicated transaction type, conversion , 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](/api-reference/wallets/wallet-object). 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](/api-reference/client-wallets/client-wallet-object)). > **Note** > > **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](https://hub.mangopay.com/) 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. #### Create the quote 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. #### Execute the conversion against the quote 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](/guides/currencies) page for details. If Mangopay doesn't currently support a currency you are looking to use, contact us [via the Dashboard](https://hub.mangopay.com/) or the [Sales contact form](https://mangopay.com/contact) to register your interest. > **Note** > > **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](https://hub.mangopay.com/). ## 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 reuse 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 #### [Endpoint](/api-reference/conversion-rates/view-conversion-rate) View an indicative Conversion Rate #### [Endpoint](/api-reference/quotes/quote-object) The Quote object #### [Endpoint](/api-reference/conversions/conversion-object) The Conversion object