Create a Quote

This call guarantees a conversion rate to let you Create a Quoted Conversion.

Body parameters

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 null

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 · 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 null

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. 

Fees · object

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

Note: For conversions between client wallets, the quote cannot have Fees specified.

Show properties

Currency · string

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

Required if Fees is sent.

The currency of the fees.

Amount · integer

Required if Fees is sent.

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

Tag · string

Max. length: 255 characters

Custom 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, 3600

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

Responses

200 - Active

Id · 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, EXPIRED

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

ConversionRateResponse · object

Information about the conversion rate used during the transaction.

Show properties

ClientRate · float

Max. 7 decimal places

The rate including Mangopay’s markup, indicative of the rate invoiced during the billing cycle: ClientRate = MarketRate * (1 - markup). 

The ClientRate fluctuates in line with the MarketRate.

MarketRate · float

Max. 7 decimal places

The rate used to convert funds during a 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.

Tag · string

Max. length: 255 characters

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

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"
    }
}

200 - Active

{
    "Id": "cvrquote_01J3G082JEQRQ4WGJPSVF5GPS7",
    "CreationDate": 1721745279,
    "ExpirationDate": 1721745579,
    "Status": "ACTIVE",
    "DebitedFunds": {
        "Currency": "GBP",
        "Amount": 1000
    },
    "CreditedFunds": {
        "Currency": "USD",
        "Amount": 1163
    },
    "Fees": {
        "Currency": "GBP",
        "Amount": 100
    },
    "ConversionRateResponse": {
        "ClientRate": 1.2793195,
        "MarketRate": 1.29172
    },
    "Tag": "Created using the Mangopay API Postman collection"
}

REST

{
    "DebitedFunds": {
        "Currency": "GBP",
        "Amount": 1000
    },
    "CreditedFunds": {
        "Currency": "USD"
    },
    "Fees": {
        "Currency": "GBP",
        "Amount": 100
    },
    "Duration": 300,
    "Tag": "Created using the Mangopay API Postman collection"
}