Create a Quote

This call guarantees a conversion rate for a quoted conversion. If the quote is for a client wallet conversion then the quote:

Can’t include Fees – the conversion attempt will return a 400 error if its QuoteId includes fees
Shouldn’t include UserMargin – the conversion attempt will not be blocked but UserMargin is disregarded – in the ConversionRateResponse (the user’s FinalRate is the same as the platform’s ClientRate)

Body parameters

Quote for User Wallets
Quote for Client Wallets

DebitedFunds

object

required

Information about the debited funds.

Show properties

Currency

string

required

Allowed values: The three-letter ISO 4217 code (EUR, GBP, etc.) of a supported currency (depends on feature, contract, and activation settings).The currency of the debited funds (the sell currency).

Amount

integer

Required if CreditedFunds.Amount is nullAn amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as 1260 whereas JPY 12 would be represented as just 12).During a conversion, (DebitedFunds.Amount - Fees) * MarketRate = CreditedFunds.Amount.

CreditedFunds

object

required

Information about the credited funds.

Show properties

Currency

string

required

Allowed values: The three-letter ISO 4217 code (EUR, GBP, etc.) of a supported currency (depends on feature, contract, and activation settings).The currency of the credited funds (the buy currency).

Amount

integer

Required if DebitedFunds.Amount is nullAn amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as 1260 whereas JPY 12 would be represented as just 12).During a conversion, (DebitedFunds.Amount - Fees) * MarketRate = CreditedFunds.Amount.

Fees

object

Information about the fees taken by the platform for this transaction (and hence transferred to the Fees Wallet).

Show properties

Type

string | null

Allowed values: PERCENTAGE, FIXEDDefault value: FIXEDThe type of the Value.

Value

integer

required

The value to be used for the Type:

PERCENTAGE – In quantities of 0.1% (e.g. 150 equals 1.5%), the percentage of DebitedFunds.Amount deducted as fees.
FIXED – The amount deducted from DebitedFunds.Amount as fees, as an amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as 1260 whereas JPY 12 would be represented as just 12).

Currency

string

required

Allowed values: The three-letter ISO 4217 code (EUR, GBP, etc.) of a supported currency (depends on feature, contract, and activation settings).The currency of the fees, which must match the debited currency.

Amount

integer

deprecated

For backwards compatibility, the Amount is accepted if sent instead of the Value.

UserMargin

object

Information about an indicative margin your platform can calculate and charge to the user after conversion. These values are used to calculate the ConversionRateResponse.FinalRate and the MarginsResponse.User in the API response.

Show properties

Type

string

required

Allowed values: PERCENTAGE, PIPThe type of the Value.

Value

float

required

The value of the Type:

PERCENTAGE
PIP

Max. value: 10.0 (10%); max. 16 decimal placesThe quantities of 1% used to calculate the user margin.

Max value: 1000.0The quantities of 0.0001 (one pip) used to calculate the user margin.

Currency

string

required

Tag

string

Max. length: 255 charactersCustom data that you can add to this object.
For transactions (pay-in, transfer, payout), you can use this parameter to identify corresponding information regarding the user, transaction, or payment methods on your platform.

Duration

integer

required

Allowed values: 300, 3600The time in seconds during which the quote is active and can be used for conversions.By default, quotes are available for a duration of 5 or 60 minutes, as agreed between Mangopay and the platform.

DebitedFunds

object

required

Information about the debited funds.

Show properties

Currency

string

required

Amount

integer

CreditedFunds

object

required

Information about the credited funds.

Show properties

Currency

string

required

Amount

integer

UserMargin

object

Show properties

Type

string

required

Allowed values: PERCENTAGE, PIPThe type of the Value.

Value

float

required

The value of the Type:

PERCENTAGE
PIP

Max. value: 10.0 (10%); max. 16 decimal placesThe quantities of 1% used to calculate the user margin.

Max value: 1000.0The quantities of 0.0001 (one pip) used to calculate the user margin.

Currency

string

required

Tag

string

Duration

integer

required

Responses

200 - Active

string

Max length: 128 characters (see data formats for details)The unique identifier of the object.

CreationDate

Unix timestamp

The date and time at which the object was created.

ExpirationDate

Unix timestamp

The date and time at which the quote expires and can no longer be used.

Status

string

Returned values: ACTIVE, EXPIREDThe status of the quote:

ACTIVE – The quote can be used to execute a quoted conversion.
EXPIRED – The quote can’t be used because the ExpirationDate is passed.

DebitedFunds

object

Information about the debited funds.

Show properties

Currency

string

Returned values: The three-letter ISO 4217 code (EUR, GBP, etc.) of a supported currency (depends on feature, contract, and activation settings).The currency of the debited funds (the sell currency).

Amount

integer

An amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as 1260 whereas JPY 12 would be represented as just 12).During a conversion, (DebitedFunds.Amount - Fees) * MarketRate = CreditedFunds.Amount.

CreditedFunds

object

Information about the credited funds.

Show properties

Currency

string

Returned values: The three-letter ISO 4217 code (EUR, GBP, etc.) of a supported currency (depends on feature, contract, and activation settings).The currency of the credited funds (the buy currency).

Amount

integer

An amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as 1260 whereas JPY 12 would be represented as just 12).During a conversion, CreditedFunds.Amount = (DebitedFunds.Amount - Fees) * MarketRate.

RequestedFees

object

Information about the Fees sent in the request.

Show properties

Type

string

Allowed values: PERCENTAGE, FIXEDDefault value: FIXEDThe type of the Value.

Value

integer

The value to be used for the Type:

PERCENTAGE – In quantities of 0.1% (e.g. 150 equals 1.5%), the percentage of DebitedFunds.Amount deducted as fees.
FIXED – The amount deducted from DebitedFunds.Amount as fees, as an amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as 1260 whereas JPY 12 would be represented as just 12).

Currency

string

ConversionRateResponse

object

Information about the MarketRate used to convert funds and other indicative rates.

Show properties

ClientRate

float

Max. 7 decimal placesThe 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.The ClientRate fluctuates in line with the MarketRate.

MarketRate

float

Max. 7 decimal placesThe rate used to convert funds during the conversion: (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.

FinalRate

float

Max. 7 decimal placesThe indicative rate including the UserMargin, if your platform defined it in the request or the quote: FinalRate = ClientRate * (1 - MarginsResponse.User). The MarginsResponse.User.Amount gives the amount of debited currency that your platform could bill to the user for the transaction.If no UserMargin was included, the FinalRate is the same as the ClientRate.

MarginsResponse

object

Information about the margins calculated for the transaction.

Show properties

Mangopay

object

The margin used by Mangopay to bill your platform (which is defined during contracting).

Show properties

Type

string

Response value: PERCENTAGEThe type of the Value, which for Mangopay is always PERCENTAGE.

Value

float

The value to be used for the Type.Mangopay’s markup is expressed as a percentage (to convert to decimal, divide by 100).

Amount

integer

The amount of debited currency that Mangopay will charge your platform for the transaction during the billing cycle.

User

object | null

The margin your platform could use to bill the user, as calculated by UserMargin in the request or quote (otherwise null if not set).

Show properties

Type

string

Response values: PERCENTAGE, PIPThe type of the Value.

Value

float

The value to be used for the Type:

PERCENTAGE - The quantities of 1% used to calculate the user margin.
PIP - The quantities of 0.0001 (one pip) used to calculate the user margin.

Amount

integer

The amount of debited currency that your platform could bill to the user for the transaction.

Tag

string

403 - Duration not allowed

{
    "Message": "Duration 90 is not in the allowed list: 300, 3600",
    "Type": "forbidden_ressource",
    "Id": "3af49cbd-d68c-403c-8a37-b1ef40c224a6",
    "Date": 1707299786,
    "errors": null
}  

403 - Currency not activated

{
    "Message": "The currency JPY is not enabled for Forex. Contact your support to activate this feature.",
    "Type": "forbidden_ressource",
    "Id": "0dbb7cbc-da22-4b67-8685-b1aea8c4551e",
    "Date": 1707315388,
    "errors": null
}  

403 - Quoted conversion feature not activated

{
    "Message": "Quoted conversion is not enabled. Contact your support to activate this feature.",
    "Type": "forbidden_ressource",
    "Id": "cb1a7c79-4ece-4930-9996-9c43b35df3b7",
    "Date": 1707315678,
    "errors": null
}  

400 - Amount not sent in either DebitedFunds or CreditedFunds

{
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Id": "c1407e47-9146-486d-81b0-54cf9142f2c3",
    "Date": 1720793416.0,
    "errors": {
        "Quote.Amount": "Debited amount or credited amount is required"
    }
}

400 - Amount sent in both DebitedFunds CreditedFunds

{
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Id": "bd657a7e-7250-4d35-a49b-eddd24126e7b",
    "Date": 1720793433.0,
    "errors": {
        "Quote.Amount": "Only one of these fields is required: debited amount or credited amount"
    }
}

{
    "Id": "cvrquote_01KH3J69K96FXNMQ875PTDJ13A",
    "CreationDate": 1770720011,
    "ExpirationDate": 1770720311,
    "Status": "ACTIVE",
    "DebitedFunds": {
        "Currency": "GBP",
        "Amount": 1000
    },
    "CreditedFunds": {
        "Currency": "EUR",
        "Amount": 1067
    },
    "Fees": {
        "Currency": "GBP",
        "Amount": 70
    },
    "RequestedFees": {
        "Type": "PERCENTAGE",
        "Value": 700,
        "Currency": "GBP"
    },
    "ConversionRateResponse": {
        "ClientRate": 1.1360925,
        "MarketRate": 1.1471047,
        "FinalRate": 1.1190511
    },
    "MarginsResponse": {
        "Mangopay": {
            "Type": "PERCENTAGE",
            "Value": 0.96,
            "Amount": 10
        },
        "User": {
            "Type": "PERCENTAGE",
            "Value": 1.5,
            "Amount": 16
        }
    },
    "Tag": "Created using the Mangopay API Postman collection"
}

{
    "DebitedFunds": {
        "Currency": "GBP",
        "Amount": 1000
    },
    "CreditedFunds": {
        "Currency": "EUR"
    },
    "Duration": 300,
    "Fees": {
        "Type": "PERCENTAGE",
        "Value": 700,
        "Currency": "GBP"
    },
    "UserMargin":{
        "Type": "PERCENTAGE",
        "Value": 1.5,
        "Currency": "GBP"
    },
    "Tag": "Created using the Mangopay API Postman collection"
}

Overview

User management

User verification

Wallets

Cards

Card pay-ins

Banking pay-ins

APM pay-ins

Transfers

Refunds

Disputes

Payouts

FX conversions

Transactions

Echo

Helpers

Platform account

Body parameters

Responses

Overview

User management

User verification

Wallets

Cards

Card pay-ins

Banking pay-ins

APM pay-ins

Transfers

Refunds

Disputes

Payouts

FX conversions

Transactions

Echo

Helpers

Platform account

​Body parameters

​Responses

Body parameters

Responses