# Get Conversion Details source: https://developer.mastercard.com/payment-currency-conversion/documentation/use-cases/conv-details/index.md This example flow demonstrates the use of **Conversion Rate Details** API calls to get the latest currency conversion rate information. In this flow, Ali chooses Martha's receiving currency, GBP, and enters a sending amount in USD. She sees the calculated conversion rate and receiving amount. The receiving amount is recalculated when Ali chooses the transfer to debit card method, for which you charge a fee of $1.35 USD (subtracted from the sending amount). **NOTE:** * The GBP receiving amount will be the transaction amount and currency for the Payment Transaction. The OI settlement amount is in USD. * This example includes the use of simple [reverse calculation](https://developer.mastercard.com/payment-currency-conversion/documentation/use-cases/conv-details/index.md#reverse-calculation) (division) to derive the 'sending currency to receiving currency conversion rate' from the API response's `conversionRate` value. This allows the app user (Ali) to enter the sending amount in their sending currency, which matches the OI settlement currency.
This example does not prescribe the design and interactions of your funds transfer solution; those aspects are for you to define. For details of using the API and sample requests and responses, see [API Reference](https://developer.mastercard.com/payment-currency-conversion/documentation/api-reference/index.md). If an API request fails validation, Mastercard returns an error response, see [Error Codes (Reason Codes)](https://developer.mastercard.com/payment-currency-conversion/documentation/codes-and-formats/index.md#error-codes-reason-codes). For details of using other Mastercard Send APIs, refer to those API documentation sets. ### Example screens {#example-screens} Some example mobile app screens are shown below --- the numbers relate to the steps in the sequence diagram. ![](https://static.developer.mastercard.com/content/payment-currency-conversion/documentation/images/mastercard-send-ccc-screens-conv-rate-details.png) ### Example sequence {#example-sequence} Diagram mastercard-send-sequence-conv-rate-details The example sequence shows: 1. In the app, Ali chooses the 'International' panel to start the cross-border transfer flow. The panel shows the previous transfer's receiving currency, Chilean Peso (CLP). 2. You send a [Conversion Rate Details API](https://developer.mastercard.com/payment-currency-conversion/documentation/api-reference/index.md) GET request to get the current CLP to USD conversion rate. Example query parameters: * `transaction_date` = '0000-00-00' or today's date * `transaction_amount` = '1' * `transaction_currency` = 'CLP' (receiving currency) * `oi_settlement_currency` = 'USD' (also the sending currency) 3. Mastercard returns a Conversion Rate Details API response (200) with the current `conversionRate` value, such as '0.001230738'. The `conversionRateDate` indicates when the rate was issued. Example response: ```json { "requestInformation": { "name": "oi-settlement-currency-conversion-rate", "description": "Provides Originating Institution payment transaction currency conversion rates and Originating Institution's settlement amount", "requestDate": "2024-06-12 17:29:43 GMT" }, "data": { "transactionDate": "2024-06-12", "transactionCurrency": "CLP", "transactionAmount": 1, "oiSettlementCurrency": "USD", "oiSettlementAmount": 0.001230738, "conversionRate": 0.001230738, "conversionRateDate": "2024-06-11" } } ``` 4. The app uses [reverse calculation](https://developer.mastercard.com/payment-currency-conversion/documentation/use-cases/conv-details/index.md#reverse-calculation) (division) to calculate and show the USD to CLP conversion rate ('812.52'): 1 ÷ `conversionRate` = 812.520617711 5. Ali selects Martha's country and currency, GBP. 6. You send a [Conversion Rate Details API](https://developer.mastercard.com/payment-currency-conversion/documentation/api-reference/index.md) GET request to get the current GBP to USD conversion rate. Example query parameters: * `transaction_date` = '0000-00-00' or today's date * `transaction_amount` = '1' * `transaction_currency` = 'GBP' * `oi_settlement_currency` = 'USD' 7. Mastercard returns a Conversion Rate Details API response (200) with the current `conversionRate` value, such as '1.25'. Example response: ```json { "requestInformation": { "name": "oi-settlement-currency-conversion-rate", "description": "Provides Originating Institution payment transaction currency conversion rates and Originating Institution's settlement amount", "requestDate": "2024-06-12 17:30:29 GMT" }, "data": { "transactionDate": "2024-06-12", "transactionCurrency": "GBP", "transactionAmount": 1, "oiSettlementCurrency": "USD", "oiSettlementAmount": 1.25, "conversionRate": 1.25, "conversionRateDate": "2024-06-11" } } ``` 8. The app uses [reverse calculation](https://developer.mastercard.com/payment-currency-conversion/documentation/use-cases/conv-details/index.md#reverse-calculation) (division) to calculate and show the USD to GBP conversion rate ('0.80'): 1 ÷ `conversionRate` = 0.80 9. Ali enters a sending amount of $200 USD, which converts to £160 GBP at the current rate (200 × 0.80). 10. Your app supports fast\* transfers to debit cards, using Mastercard Send, for which you charge a fee of $1.35 USD (subtracted from the sending amount). Ali chooses that delivery method, and the 'International' panel changes to show the transfer fee and the recalculated GBP receiving amount of £158.92 ((200 - 1.35) × 0.80). 11. Tapping **Continue**, Ali then enters Martha's card details and address, and reviews those transfer details. We recommend using the Mastercard Send APIs to validate that receiving card account. 12. If the card account is valid, Ali reviews the transfer details and selects her stored sending card account (re-entering the CVC), then taps **Confirm transfer**. Mastercard rates are published daily and are effective for a 24-hour period, see the [Currency Conversion Rates guide](https://developer.mastercard.com/payment-currency-conversion/documentation/tutorials-and-guides/index.md#currency-conversion-rates-guide). 13. OPTIONAL: If the rate may have changed since Ali started this cross-border transfer flow, you could send a [Conversion Rate Details API](https://developer.mastercard.com/payment-currency-conversion/documentation/api-reference/index.md) GET request to confirm the current conversion rate prior to initiating the Payment Transaction. 14. Mastercard returns a Conversion Rate Details API response (200) with the current rate (`conversionRate`). 15. The app shows the payment details and prompts Ali to confirm the transfer. If the conversion rate and receiving amount has changed, the app panel should indicate that change. 16. Ali taps **Confirm transfer**. 17-23. You use the Mastercard Send Payment Transfer API to request the funds transfer (Payment Transaction) to the Receiving Institution of transaction amount £158.92 GBP. If the Receiving Institution approves the transfer, it credits £158.92 GBP\*\* to Martha's account, and you debit $200 USD from Ali's account. The app shows a success screen with a confirmation number and receipt. \* We recommend that you explain transfer times carefully in your app screens to increase clarity and avoid confusion. For example, if you use "instant" or "fast" to describe your most rapid transfer time, consider including asterisk disclaimer text such as: *\*Transfer times can vary. Most "instant" or "fast" transfers will take place in near real time but can take longer.* \*\* The transaction amount is the *intended* amount for the receiving account. The receiving issuer (the Receiving Institution) might not credit that actual amount to the receiving account, for example, it might impose fees for receiving such transfers. See the Legal disclaimer FAQ on the [Support](https://developer.mastercard.com/payment-currency-conversion/documentation/support/index.md) page. ### Reconciliation {#reconciliation} When you reconcile the Payment Transaction with the Receiving Institution, the OI settlement amount for this transaction should be the USD amount that converted to the transaction amount (step 10), in this case: $200 sending amount - $1.35 fee = $198.65 USD ## Reverse Calculation {#reverse-calculation} To allow the app user (Ali) to enter the **sending amount** in their sending currency (which matches the OI settlement currency), this example uses simple division to derive the 'sending currency to receiving currency conversion rate' from the API response's `conversionRate` value, for example: 1 ÷ GBP to USD `conversionRate` = USD to GBP conversion rate However, if you want the app user to enter the intended **receiving amount** (transaction amount), you can use the API response's `conversionRate` value to calculate the sending amount, for example: Receiving amount × `conversionRate` = sending amount, excluding any in-app fees ## 3-Place Exponent Currencies {#3-place-exponent-currencies} The [Conversion Rate Details API](https://developer.mastercard.com/payment-currency-conversion/documentation/api-reference/index.md) GET request `transaction_amount` query parameter allows up to two precision digits to the right of the decimal point: * 134.87 = allowed * 134.874 = not allowed Some currencies have 3-digit exponents, such as the Iraq Dinar (IQD). To convert such currencies, for example convert 134.874 IQD to USD settlement amount, you could make a GET call with `transaction_amount` as '1' to get the current IQD to USD rate (`conversionRate` = 0.0007634), then multiply the IQD amount by that rate: 134.874 IQD × 0.0007634 = 0.102962812 USD. There are other methods, such as making the GET call with a `transaction_amount` that's been increased by a factor of 10, then decreasing the returned `oiSettlementAmount` by a factor of 10. ## Mastercard Merchant Presented QR (MPQR) {#mastercard-merchant-presented-qr-mpqr} For MPQR implementations, the main example sequence can be adapted for MPQR person-to-merchant (P2M) cross-border payment. For example: * Martha (the Recipient) is a merchant. * Ali (the consumer) initiates payment by scanning Martha's Mastercard QR code and, if the code is static, enters the transaction amount. * You send a single [Conversion Rate Details API](https://developer.mastercard.com/payment-currency-conversion/documentation/api-reference/index.md) GET request to get the current conversion rate (`conversionRate`) and sending amount (`oiSettlementAmount`). * You use the MPQR APIs to request the payment (Payment Transaction) to the Receiving Institution (merchant bank).