Skip to main content

​
Overview

The Conversions API allows you to convert funds between wallets of different currencies. You can perform instant conversions at the current market rate or create quoted conversions with a guaranteed rate. Mangopay supports conversions between user wallets as well as client wallets (fees and credit wallets).

​
Methods

​
GetConversionRate

Get a real-time indicative market rate for a specific currency pair. 
public function GetConversionRate($debitedCurrency, $creditedCurrency)
​
debitedCurrency
string
required
The sell currency – the currency of the wallet to be debited (e.g., “EUR”, “USD”)
​
creditedCurrency
string
required
The buy currency – the currency of the wallet to be credited (e.g., “GBP”, “USD”)
Returns: ConversionRate - The conversion rate object with real-time market rate Example: 
$api = new MangoPay\MangoPayApi();
$rate = $api->Conversions->GetConversionRate('EUR', 'GBP');
echo "Rate: " . $rate->ClientRate;

​
CreateInstantConversion

Create an instant conversion at the current market rate between user wallets. 
public function CreateInstantConversion($instantConversion)
​
instantConversion
CreateInstantConversion
required
The instant conversion object containing conversion details
Returns: Conversion - The created conversion object Example: 
$conversion = new MangoPay\CreateInstantConversion();
$conversion->AuthorId = 'user_123456';
$conversion->DebitedWalletId = 'wallet_eur_123';
$conversion->CreditedWalletId = 'wallet_gbp_456';
$conversion->DebitedFunds = new MangoPay\Money();
$conversion->DebitedFunds->Currency = 'EUR';
$conversion->DebitedFunds->Amount = 10000; // 100.00 EUR
$conversion->Tag = 'EUR to GBP conversion';

$result = $api->Conversions->CreateInstantConversion($conversion);

​
CreateClientWalletsInstantConversion

Create an instant conversion at the market rate between client wallets (fees/credit). 
public function CreateClientWalletsInstantConversion($instantConversion)
​
instantConversion
CreateClientWalletsInstantConversion
required
The instant conversion object for client wallets
Returns: Conversion - The created conversion object Example: 
$conversion = new MangoPay\CreateClientWalletsInstantConversion();
$conversion->DebitedWalletId = 'client_wallet_eur';
$conversion->CreditedWalletId = 'client_wallet_usd';
$conversion->DebitedFunds = new MangoPay\Money();
$conversion->DebitedFunds->Currency = 'EUR';
$conversion->DebitedFunds->Amount = 50000; // 500.00 EUR

$result = $api->Conversions->CreateClientWalletsInstantConversion($conversion);

​
CreateQuotedConversion

Create a conversion at a rate guaranteed by a quote. 
public function CreateQuotedConversion($quotedConversion)
​
quotedConversion
CreateQuotedConversion
required
The quoted conversion object linked to a ConversionQuote
Returns: Conversion - The created conversion object Example: 
// First, create a quote
$quote = new MangoPay\ConversionQuote();
$quote->DebitedFunds = new MangoPay\Money();
$quote->DebitedFunds->Currency = 'EUR';
$quote->DebitedFunds->Amount = 10000;
$quote->CreditedFunds = new MangoPay\Money();
$quote->CreditedFunds->Currency = 'GBP';
$createdQuote = $api->Conversions->CreateConversionQuote($quote);

// Then create the conversion using the quote
$conversion = new MangoPay\CreateQuotedConversion();
$conversion->QuoteId = $createdQuote->Id;
$conversion->AuthorId = 'user_123456';
$conversion->DebitedWalletId = 'wallet_eur_123';
$conversion->CreditedWalletId = 'wallet_gbp_456';
$conversion->Tag = 'Quoted conversion';

$result = $api->Conversions->CreateQuotedConversion($conversion);

​
CreateClientWalletsQuotedConversion

Create a quoted conversion between client wallets. 
public function CreateClientWalletsQuotedConversion($quotedConversion)
​
quotedConversion
CreateClientWalletsQuotedConversion
required
The quoted conversion object for client wallets. Must be linked to a quote.
Returns: Conversion - The created conversion object

​
GetConversion

Retrieve details of a specific conversion. 
public function GetConversion($id)
​
id
string
required
The unique identifier of the conversion
Returns: Conversion - The conversion object Example: 
$conversion = $api->Conversions->GetConversion('cvr_123456');
echo "Status: " . $conversion->Status;

​
CreateConversionQuote

Create a quote to guarantee a conversion rate. 
public function CreateConversionQuote($quote)
​
quote
ConversionQuote
required
The quote object specifying debited and credited funds
Returns: ConversionQuote - The created quote with guaranteed rate Example: 
$quote = new MangoPay\ConversionQuote();
$quote->DebitedFunds = new MangoPay\Money();
$quote->DebitedFunds->Currency = 'EUR';
$quote->DebitedFunds->Amount = 10000;
$quote->CreditedFunds = new MangoPay\Money();
$quote->CreditedFunds->Currency = 'GBP';
$quote->Tag = 'Conversion quote';

$createdQuote = $api->Conversions->CreateConversionQuote($quote);
echo "Guaranteed rate valid until: " . date('Y-m-d H:i:s', $createdQuote->ExpirationDate);

​
GetConversionQuote

Retrieve details of a specific conversion quote. 
public function GetConversionQuote($quoteId)
​
quoteId
string
required
The unique identifier of the quote
Returns: ConversionQuote - The quote object Example: 
$quote = $api->Conversions->GetConversionQuote('quote_123456');

​
Conversion Entity

The Conversion entity represents a currency conversion:
​
Id
string
The unique identifier of the conversion
​
CreationDate
int
Unix timestamp of when the conversion was created
​
Tag
string
Custom data that you can add to this item
​
QuoteId
string
The unique identifier of the quote that guaranteed the rate. Null for instant conversions.
​
Type
string
The type of transaction. See TransactionType.
​
Nature
string
The nature of the transaction. See TransactionNature.
​
Status
string
The status of the transaction: CREATED, SUCCEEDED, FAILED. See TransactionStatus.
​
AuthorId
string
The unique identifier of the user at the source of the transaction
​
DebitedWalletId
string
The unique identifier of the debited wallet
​
CreditedWalletId
string
The unique identifier of the credited wallet
​
DebitedFunds
Money
The sell funds (amount and currency)
​
CreditedFunds
Money
The buy funds (amount and currency)
​
Fees
Money
Platform fees for this transaction. Null for instant conversions between client wallets.
​
RequestedFees
CustomFees
The requested fees
​
ResultCode
string
The code indicating the result of the operation
​
ResultMessage
string
The explanation of the result code
​
ExecutionDate
int
Unix timestamp when the status changed to SUCCEEDED. Null for CREATED and FAILED statuses.
​
ConversionRateResponse
ConversionRate
Real time market rate information
​
MarginsResponse
MarginsResponse
Information about margins applied

​
ConversionRate Entity

​
ClientRate
float
The rate applied to the conversion
​
MarketRate
float
The current market rate

​
ConversionQuote Entity

​
Id
string
The unique identifier of the quote
​
CreationDate
int
Unix timestamp of when the quote was created
​
ExpirationDate
int
Unix timestamp when the quote expires
​
Status
string
The status of the quote: ACTIVE, EXPIRED, CONSUMED
​
DebitedFunds
Money
The sell funds
​
CreditedFunds
Money
The buy funds
​
ConversionRateResponse
ConversionRate
The guaranteed conversion rate

Build docs developers (and LLMs) love

Get started for freeTalk to us