Currency Conversion

What is currency conversion

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 and customer convenience: Accept and settle payments in multiple currencies so customers can pay in the currency they prefer.
Cost and revenue optimization: Reduce transaction costs and leverage favorable exchange rates.

Common use cases

Cross-border commerce: E-commerce, remittance, and travel/hospitality businesses that need to charge or pay out in a customer’s local currency.
Investment platforms: Fintechs trading foreign stocks, bonds, or cryptocurrencies across currencies.

Implementation

Yuno connects different currency conversion providers, so you don’t have to worry about the differences between each integration. The implementation of the service depends 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

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. To use this, contact your technical account manager to make sure that the information is set properly. Example:

 "amount": {
        "currency": "COP",
        "value": 5000, 
        "currency_conversion": {
            "provider_currency_conversion_id": "AAA01SADOIAJSDLAKSJM",
            "cardholder_currency": "ARS",
            "cardholder_amount": 1146.55    
        }
    }

Yuno’s rate service

Also, the merchant can use directly the currency conversion service of Yuno that gets the information from the provider of their choosing and send in the creation of the payment the id of the conversion rate query and the amount data accordingly. In case of using this service, you will also need to send the id obtained in the payment request so we can link the information. Example:

Rate service

{
  "account_id": "fe14c7c6-c75e-43b7-bdbe-4c87ad52c482",
  "amount": {
    "currency_conversion": {
      "cardholder_currency": "USD",
      "provider_data": {
        "id": "CIBC"
      }
    },
    "value": 10000,
    "currency": "COP"
  }
}

Payment

    "amount": {
        "currency": "COP",
        "value": 5000, 
        "currency_conversion": {
            "id": "62fdcd6c-50ea-4640-985b-5656010fe5fD",
            "cardholder_currency": "ARS",
            "cardholder_amount": 1146.55    
        }
    },

To use this, contact your technical account manager to make sure that the information is set properly.

Request parameters

The following fields are sent inside amount.currency_conversion on POST /v1/payments.

Field	Type	Required	Description
`cardholder_currency`	`string`	Yes	Currency the cardholder is charged in. ISO 4217 alpha-3 code. Must differ from `amount.currency`.
`cardholder_amount`	`decimal`	Yes	Total amount billed to the cardholder in `cardholder_currency`. Range: `0.0001` – `9,999,999,999`.
`cardholder_accepted`	`boolean`	Yes	Cardholder’s explicit consent to the DCC offer. `true` = accepted (charge in `cardholder_currency`). `false` = declined (payment proceeds in merchant currency).
`rate`	`decimal`	Yes	Applied FX rate (markup included). Must be `> 0`.
`rate_margin_percentage`	`decimal`	Yes	Markup added over the wholesale rate, expressed as a percentage. Range: `0` – `100`.
`rate_source`	`string`	Conditional	Wholesale benchmark used for the quote. Required when `rate_margin_percentage > 0`. Free text, max 50 chars. Examples: `ECB`, `REUTERS`, `BLOOMBERG`, `PROVIDER_INTERNAL`.
`provider`	`string` (enum)	Yes	DCC provider that issued the quote. See Provider values.
`description`	`string`	Optional	Verbatim disclosure text shown to the cardholder at the point of sale. Stored unchanged for audit. Max 4096 chars.
`created_at`	`string` (ISO 8601)	Yes	Timestamp when the DCC provider issued the quote. Must be `≤ now()`.
`expires_at`	`string` (ISO 8601)	Optional	Timestamp when the quote expires. Must be `> created_at`. The payment is rejected if `expires_at < now()` at validation time.

Provider values

provider accepts one of:

Value	DCC provider	Typical market
`FEXCO`	Fexco Merchant Services	Universal: largest DCC provider; supported natively by MPGS
`GLOBAL_BLUE`	Global Blue	Retail, tax-free shopping, tourism
`PLANET`	Planet Payment	Retail, hospitality, tourism
`EURONET`	Euronet / Pure Commerce	ATM DCC, LatAm, APAC
`CURRENCYFAIR`	Currencyfair	E-commerce, digital
`EUROPEAN_PAYMENT_SERVICES`	European Payment Services (EPS)	EU regional
`OTHER`	Any provider not listed above	Long-tail or emerging-market providers

Validation rules

All required fields must be present.
provider must match one of the allowed enum values exactly.
cardholder_currency must be a valid ISO 4217 alpha-3 code and must differ from amount.currency.
created_at and expires_at must be valid ISO 8601 timestamps.
expires_at, when provided, must be strictly greater than created_at.
rate_source is required whenever rate_margin_percentage > 0.

Request example

POST /v1/payments

{
  "account_id": "4b8f9c10-5c6a-4b2d-9b7e-2c8d3a1b4f55",
  "merchant_order_id": "order-2026-04-24-0001",
  "amount": {
    "value": 1000.00,
    "currency": "USD",
    "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"
    }
  }
}

Getting Started

Core Concepts

Using Yuno

Direct Integration Use Cases

Payment Features

Payouts and Disputes

Webhooks

Wallets

AI Capabilities

Security and Compliance

Plugins

Additional Services

What is currency conversion

Benefits

Common use cases

Implementation

Key Concepts

API implementation

Provider’s rate service

Yuno’s rate service

Request parameters

Provider values

Validation rules

Request example

​What is currency conversion

​Benefits

​Common use cases

​Implementation

​Key Concepts

​API implementation

​Provider’s rate service

​Yuno’s rate service

​Request parameters

​Provider values

​Validation rules

​Request example

What is currency conversion

Benefits

Common use cases

Implementation

Key Concepts

API implementation

Provider’s rate service

Yuno’s rate service

Request parameters

Provider values

Validation rules

Request example