> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Quoted Conversion between Client Wallets

This call triggers a conversion at the rate defined in its quote. The debited funds (buy currency), credited funds (sell currency) and currencies are defined in the quote. The <a href="/api-reference/client-wallets/client-wallet-object">Client Wallets</a> to debit and credit are defined in the conversion.

Each quoted conversion requires a dedicated [Quote](/api-reference/quotes/quote-object) object, linked in the `QuoteId`.

Quoted conversions between client wallets:

* 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

<ParamField body="QuoteId" type="string" required>
  The unique identifier of the active quote which guaranteed the rate for the conversion.
</ParamField>

<ParamField body="DebitedWalletType" type="string" required>
  **Allowed values:** `FEES`, `CREDIT`

  The type of the client wallet to be debited:

  * `FEES` – Fees Wallet, for fees collected by the platform.
  * `CREDIT` – Repudiation Wallet, for funds related to dispute management.

  The amount and currency of the debited funds are defined by the quote.
</ParamField>

<ParamField body="CreditedWalletType" type="string" required>
  **Allowed values:** `FEES`, `CREDIT`

  The type of the client wallet to be credited:

  * `FEES` – Fees Wallet, for fees collected by the platform.
  * `CREDIT` – Repudiation Wallet, for funds related to dispute management.

  The amount and currency of the credited funds are defined by the quote.
</ParamField>

<ParamField body="Tag" type="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.
</ParamField>

### Responses

<AccordionGroup>
  <Accordion title="200 - Succeeded">
    <ResponseField name="Id" type="string">
      Max length: 128 characters (see [data formats](/api-reference/overview/data-formats) for details)

      The unique identifier of the object.
    </ResponseField>

    <ResponseField name="QuoteId" type="string">
      The unique identifier of the active quote which guaranteed the rate for the conversion.

      Returned `null` in the case of an instant conversion.
    </ResponseField>

    <ResponseField name="Type" type="string">
      The type of transaction.
    </ResponseField>

    <ResponseField name="Nature" type="string">
      **Returned values:** `REGULAR`, `REPUDIATION`, `REFUND`, `SETTLEMENT`

      The nature of the transaction, providing more information about the context in which the transaction occurred:

      * `REGULAR` – Relative to most of the transactions (pay-ins, payouts, and transfers) in a usual workflow.
      * `REPUDIATION` – Automatic withdrawal of funds from the platform’s repudiation wallet as part of the dispute process (when the user has requested a chargeback).
      * `REFUND` – Reimbursement of a transaction to the user (pay-in refund), to a wallet (transfer refund), or of a payout (payout refund, only initiated by Mangopay).
      * `SETTLEMENT` – Transfer made to the repudiation wallet by the platform to settle a lost dispute.
    </ResponseField>

    <ResponseField name="CreationDate" type="Unix timestamp">
      The date and time at which the object was created.
    </ResponseField>

    <ResponseField name="Status" type="string">
      **Returned values:** `CREATED`, `SUCCEEDED`, `FAILED`

      The status of the transaction.
    </ResponseField>

    <ResponseField name="AuthorId" type="string">
      The unique identifier of the user at the source of the transaction. In a conversion, both the debited and credited wallets are owned by the author.
    </ResponseField>

    <ResponseField name="DebitedWalletId" type="string">
      The unique identifier of the debited wallet (in the sell currency).
    </ResponseField>

    <ResponseField name="CreditedWalletId" type="string">
      The unique identifier of the credited wallet (in the buy currency).
    </ResponseField>

    <ResponseField name="DebitedFunds" type="object">
      Information about the debited funds.

      <Expandable title="properties">
        <ResponseField name="Currency" type="string">
          **Returned values:** The three-letter <a href="/api-reference/overview/data-formats" target="_blank">ISO 4217 code</a> (EUR, GBP, etc.) of a <a href="/guides/currencies" target="_blank">supported currency</a> (depends on feature, contract, and activation settings).

          The currency of the debited funds (the sell currency).
        </ResponseField>

        <ResponseField name="Amount" type="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`. 
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="CreditedFunds" type="object">
      Information about the credited funds.

      <Expandable title="properties">
        <ResponseField name="Currency" type="string">
          **Returned values:** The three-letter <a href="/api-reference/overview/data-formats" target="_blank">ISO 4217 code</a> (EUR, GBP, etc.) of a <a href="/guides/currencies" target="_blank">supported currency</a> (depends on feature, contract, and activation settings).

          The currency of the credited funds (the buy currency).
        </ResponseField>

        <ResponseField name="Amount" type="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`. 
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ResultCode" type="string">
      The code indicating the result of the operation. This information is mostly used to <a href="/errors/codes">handle errors</a> or for filtering purposes.
    </ResponseField>

    <ResponseField name="ResultMessage" type="string">
      The explanation of the result code.
    </ResponseField>

    <ResponseField name="ExecutionDate" type="Unix timestamp">
      The date and time at which the status changed to `SUCCEEDED`, indicating that the transaction occurred. The statuses `CREATED` and `FAILED` return an `ExecutionDate` of `null`.
    </ResponseField>

    <ResponseField name="ConversionRateResponse" type="object">
      Information about the `MarketRate` used to convert funds and other indicative rates.

      <Expandable title="properties">
        <ResponseField name="ClientRate" type="float">
          Max. 7 decimal places

          The 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`.
        </ResponseField>

        <ResponseField name="MarketRate" type="float">
          Max. 7 decimal places

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

        <ResponseField name="FinalRate" type="float">
          Max. 7 decimal places

          The 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`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="Tag" type="string">
      Max. length: 255 characters

      Custom data that you can add to this object.
    </ResponseField>
  </Accordion>
</AccordionGroup>

Functional errors (`ResultCode`) are possible on a 200 response. <a href="/errors/codes#fx-conversions">Read more</a> **→**

***

<AccordionGroup>
  <Accordion title="400 - No fees allowed on client quoted conversion">
    ```json theme={null}
    {
        "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
        "Type": "param_error",
        "Id": "b4372752-a7dd-4751-b894-d2c960df3e5c",
        "Date": 1721729683.0,
        "errors": {
            "QuoteId": "No fees allowed on client quoted conversion"
        }
    }
    ```
  </Accordion>
</AccordionGroup>

<ResponseExample>
  ```json 200 theme={null}
  {
      "Id": "cvr_01J475ZYZ6WBZK3JK3HSZFXHVN",
      "QuoteId": "cvrquote_01J475ZRENK67V9A62JCQ6PYVW",
      "Type": "CONVERSION",
      "Nature": "REGULAR",
      "CreationDate": 1722523057,
      "Status": "SUCCEEDED",
      "AuthorId": "your-client-id",
      "DebitedWalletId": "FEES_EUR",
      "CreditedWalletId": "CREDIT_GBP",
      "DebitedFunds": {
          "Currency": "EUR",
          "Amount": 10
      },
      "CreditedFunds": {
          "Currency": "GBP",
          "Amount": 8
      },
      "ResultCode": "000000",
      "ResultMessage": "Success",
      "ExecutionDate": 1722523057,
      "ConversionRateResponse": {
          "ClientRate": 0.8352637,
          "MarketRate": 0.84336
      },
      "Tag": "Created using Mangopay API Collection Postman"
  }
  ```
</ResponseExample>

<RequestExample>
  ```json REST  theme={null}
  {
    "QuoteId" : "cvrquote_01J475ZRENK67V9A62JCQ6PYVW",
    "DebitedWalletType" : "FEES",
    "CreditedWalletType" : "CREDIT",  
    "Tag": "Created using Mangopay API Collection Postman"
  }
  ```
</RequestExample>