Documentation Index
Fetch the complete documentation index at: https://docs.y.uno/llms.txt
Use this file to discover all available pages before exploring further.
Yuno’s currency conversion service allows you to settle payments in both your currency and your customer’s. Currency conversion is the process of converting one currency into another. It involves using exchange rates to determine the equivalent amount in the target currency.
Benefits
- Global Reach: Allows businesses to operate internationally by accepting and making payments in multiple currencies.
- Customer Convenience: Customers can pay in their preferred currency, enhancing their buying experiences.
- Cost Efficiency: Optimizing conversion rates can reduce transaction costs.
- Revenue Optimization: Businesses can leverage favorable exchange rates to maximize profits.
Some use Cases
- E-commerce Platforms: Online stores that sell products internationally use currency conversion to display prices in local currencies and process payments accordingly.
- Remittance Services: Companies that facilitate money transfers across borders rely on currency conversion to ensure recipients receive funds in their local currency.
- Travel and Hospitality: Businesses in this sector use currency conversion to handle payments from international travelers.
- Investment Platforms: Fintech platforms that offer trading in foreign stocks, bonds, or cryptocurrencies use currency conversion to manage investments across different currencies.
Implementation
In Yuno, we connect different currency conversion providers, so you dont have to worry about the differences between each integration. The implementation of the service is going to depend on the currency conversion provider you choose to work with.
Key Concepts
- Exchange Rate: The rate at which one currency can be exchanged for another. This can be a fixed rate or a floating rate that fluctuates based on market conditions.
- Base Currency: The currency you are converting from.
- Cardholder Currency: The currency you are converting to.
- Conversion Spread: The difference between the buy and sell rates, representing the profit margin for the entity providing the conversion service.
- Real-Time Conversion: Using up-to-date exchange rates to perform conversions at the exact time of the transaction.
API implementation
In order to be able to use the currency conversion service you have two API implementations available.
Provider’s rate service
The merchant can use the currency conversion service of an external provider and send the corresponding information directly in the payment in Yuno.
Example:
"amount": {
"currency": "USD",
"value": 1000.00,
"currency_conversion": {
"cardholder_currency": "QAR",
"cardholder_amount": 3640.00,
"cardholder_accepted": true,
"rate": 3.6400,
"rate_margin_percentage": 3.75,
"rate_source": "ECB",
"provider": "FEXCO",
"description": "You have chosen to pay in QAR. Amount: 3640.00 QAR. Rate: 3.6400.",
"created_at": "2026-04-24T14:30:00Z",
"expires_at": "2026-04-24T15:30:00Z"
}
}
Parameter Reference
The following table describes the parameters for the amount.currency_conversion object:
Request Fields
| Field | Type | Required | Description |
|---|
cardholder_currency | string | ✅ | Currency the cardholder is charged in. ISO 4217 alpha-3 code. |
cardholder_amount | number | ✅ | Total amount billed to the cardholder in cardholder_currency. |
cardholder_accepted | boolean | ✅ | Cardholder’s explicit consent to the DCC offer. |
rate | number | ✅ | Applied FX rate (markup included). |
rate_margin_percentage | number | ✅ | Markup added over the wholesale rate, expressed as a percentage. |
rate_source | string | Conditional | Wholesale benchmark used for the quote. Required when rate_margin_percentage > 0. |
provider | string | ✅ | DCC provider that issued the quote (e.g., FEXCO, PLANET). |
description | string | Optional | Verbatim disclosure text shown to the cardholder. |
created_at | string | ✅ | Timestamp when the DCC provider issued the quote (ISO 8601). |
expires_at | string | Optional | Timestamp when the quote expires (ISO 8601). |
Webhook / Response Additions
| Field | Type | Description |
|---|
code | string | Yuno’s internal identifier for this DCC record. |
status | string | Lifecycle state of the conversion (e.g., APPLIED, DECLINED). |
error_reason | string | Populated only when DCC could not be applied. |
provider_data | object | Acquirer round-trip data returned by the underlying provider adapter. |
Lifecycle Status
| Value | Meaning |
|---|
QUOTED | Quote received and validated; not yet applied to an authorization. |
APPLIED | Quote was applied to the authorization successfully. |
EXPIRED | Quote expired before it could be applied. |
DECLINED | Cardholder declined the DCC offer. |
REVERSED | Conversion was reversed as part of a cancellation or refund. |
