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

​
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:

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.

1

Create the quote

Use the POST Create a 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.

2

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:

Between client wallets:

​
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 * 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 Hub 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 Hub.

​
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:

​
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 marketplace 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.

Endpoint

View an indicative Conversion Rate

Endpoint

The Quote object

Endpoint

The Conversion object

Was this page helpful?

How toOverview