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. 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).

​

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

Between client wallets:

• POST Create an Instant Conversion between 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.

​

Webhooks

There are dedicated event types 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 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 client rate includes Mangopay’s markup: it is indicative of the rate invoiced during the billing cycle. ClientRate = MarketRate * (1 - markup).The ClientRate fluctuates in line with the MarketRate.

Mangopay’s markup is agreed during contracting. You can can calculate it using the formula:

• Markup = 1 - (ClientRate / MarketRate)

You can see Mangopay’s indicative rate for a currency pair at any time using the GET View an indicative Conversion Rate endpoint.

​

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.

​

Managing conversions

The GET View a 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
• GET List Transactions for a Wallet
• GET List Transactions for a Client Wallet
• POST Create a 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 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 endpoint
3. If they wish to proceed with the currency exchange, use the POST Create an Instant Conversion 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 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 endpoint.
3. Use the POST Create a 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 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 endpoint, refreshing every few minutes
2. When the buyer proceeds to checkout, use the POST Create a 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 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