Create an Instant Conversion between user Wallets

This call triggers an immediate conversion at the market rate, of the debited funds to the credited wallet at the market rate. A quote is not required for an instant conversion.

Body parameters

AuthorId · string · required

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.

DebitedWalletId · string · required

The unique identifier of the debited wallet (in the sell currency).

CreditedWalletId · string · required

The unique identifier of the credited wallet (in the buy currency).

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

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

Fees · object

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

Note: The fees currency must match the debited funds currency.

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.

Responses

200 - Succeeded

Id · string

Max length: 128 characters (see data formats for details)

The unique identifier of the object.

Type · string

The type of transaction.

Nature · 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.

CreationDate · Unix timestamp

The date and time at which the object was created.

Status · string

Returned values: CREATED, SUCCEEDED, FAILED

The status of the transaction.

AuthorId · 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.

DebitedWalletId · string

The unique identifier of the debited wallet (in the sell currency).

CreditedWalletId · string

The unique identifier of the credited wallet (in the buy currency).

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. 

Fees · object

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

Note: The fees currency must match the debited funds currency.

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

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

ResultCode · string

The code indicating the result of the operation. This information is mostly used to handle errors or for filtering purposes.

ResultMessage · string

The explanation of the result code.

ExecutionDate · 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.

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.

Functional errors (ResultCode) are possible on a 200 response. Read more →

---

400 - Author not debited wallet owner

{
    "Message": "Author 45671234 is not debited wallet 204089031 owner.",
    "Type": "author_is_not_debited_wallet_owner",
    "Id": "5251717e-0965-4e33-a85a-a1042775913f",
    "Date": 1699532783,
    "errors": null
}  

400 - Author not credited wallet owner

{
    "Message": "Author 204068024 is not credited wallet 208282959 owner.",
    "Type": "author_is_not_credited_wallet_owner",
    "Id": "f072dcfd-d02c-4489-835f-7abe0b11fa66",
    "Date": 1699532982,
    "errors": null
}  

400 - Debited funds currency doesn’t match debited wallet currency

{
    "Message": "Debited currency incompatibility.",
    "Type": "currency_incompatibility",
    "Id": "af071186-b891-4e0d-baeb-736c15a757e8",
    "Date": 1699532861,
    "errors": null
}  

400 - Credited funds currency doesn’t match credited wallet currency

{
    "Message": "Credited currency incompatibility.",
    "Type": "currency_incompatibility",
    "Id": "2466e688-5f4f-4dfa-8ebe-97b5608c3dd5",
    "Date": 1699532915,
    "errors": null
}  

400 - Fees currency doesn't match debited funds currency

{
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Id": "f19eafbd-0310-4814-8f6b-691910b7b4a2",
    "Date": 1707323047,
    "errors": {
        "Fees.Currency": "Provided currency USD does not match debit currency of GBP"
    }
}  

403 - Currency not activated

{
    "Message": "The currency JPY is not enabled for Forex. Contact your support to activate this feature.",
    "Type": "forex_not_available",
    "Id": "f8701d45-2540-4497-a7ce-4a3bc3181d68",
    "Date": 1699533051,
    "errors": null
}  

403 - FX feature not activated

{
    "Message": "Forex module is not enabled. Contact your support to activate this feature.",
    "Type": "forbidden_ressource",
    "Id": "812b8909-9fb1-45b5-9000-06e8c8d73687",
    "Date": 1699533020,
    "errors": null
}  

200 - Succeeded

{
    "Id": "cvr_01J3G21RF2R88PCA34P287ZQPQ",
    "Type": "CONVERSION",
    "Nature": "REGULAR",
    "CreationDate": 1721747169,
    "Status": "SUCCEEDED",
    "AuthorId": "user_m_01HSB23417BFG7YXR7E371JSEA",
    "DebitedWalletId": "wlt_m_01HSJTVB0JKMMHXBEJBV6TMF96",
    "CreditedWalletId": "wlt_m_01J3G1CY4VH5FNMSAM8M0S5A64",
    "DebitedFunds": {
        "Currency": "GBP",
        "Amount": 1000
    },
    "CreditedFunds": {
        "Currency": "USD",
        "Amount": 1161
    },
    "Fees": {
        "Currency": "GBP",
        "Amount": 100
    },
    "ResultCode": "000000",
    "ResultMessage": "Success",
    "ExecutionDate": 1721747170,
    "ConversionRateResponse": {
        "ClientRate": 1.277585,
        "MarketRate": 1.2904899
    },
    "Tag": "Created using the Mangopay API Postman collection"
}

REST

{
    "AuthorId": "user_m_01HSB23417BFG7YXR7E371JSEA",
    "DebitedWalletId": "wlt_m_01HSJTVB0JKMMHXBEJBV6TMF96",
    "CreditedWalletId": "wlt_m_01J3G1CY4VH5FNMSAM8M0S5A64",
    "DebitedFunds": {
        "Currency": "GBP",
        "Amount": 1000
    },
    "CreditedFunds": {
        "Currency": "USD"
    },
    "Fees": {
        "Currency": "GBP",
        "Amount": 100
    },
    "Tag": "Created using the Mangopay API Postman collection"
}