Currency converter

The Currency converter lets the merchant define the transaction amount equivalent in the required currency based on the currency exchange rate provided by the exchange rate source available in the converter settings.

The currency being converted is called base currency and the currency into which the amount is converted is called quote currency.

The converter lets the merchant set a price in a currency that is different from the ones supported by their acquirer. Also, the converter lets the merchant calculate the transaction amount into another currency supported by the gateway but not use it in the transaction request to the acquirer.

The converted amount will be available to the customer in the webhook notification, in the response to the transaction, in the report and on the Transaction details page.

The converter can be used for the transactions of payment, authorization, payout, refund, capture and void types.

The conversion rate in the parent transactions is used in the corresponding child transactions.

Please contact your manager of the Tech Support Team to set up the converter.

`conversion` object

conversion object will be sent in the synchronous response to the transaction, in the response to the transaction status query and in the webhook notification if the currency converter is set up for the gateway used for the transaction processing.

Parameter	Type	Description
transaction	object
conversion	object	Object with conversion information.
converted_amount	bigInteger	Transaction amount in the quote currency in minimal currency units.
converted_currency	string	Quote currency in ISO-4217 alpha-3 code format.
exchange_rate	object
`:{base currency}_TO_{quote-currency}`	float	Exchange rate used for the calculation = base currency unit ÷ quote currency unit.
exchange_rate_date	string	The date and time when the exchange rate was imported from the exchange rate source in the following format: `YYYY-MM-DDThh:mm:ss[.SSSSSS]Z`.

Example of the response to the payment request with the conversion object

{
    "transaction": {
        "uid": "263586a3-50f6-4ff3-b9a0-ba5bd8f71b9d",
        "status": "successful",
        "amount": 700,
        "currency": "GBP",
        "description": "Test transaction",
        "type": "payment",
        "payment_method_type": "credit_card",
        "tracking_id": "tracking_id_000",
        "message": "Successfully processed",
        "test": true,
        "created_at": "2025-03-11T09:13:07.536Z",
        "updated_at": "2025-03-11T09:13:12.880Z",
        "paid_at": "2025-03-11T09:13:12.848Z",
        "expired_at": null,
        "recurring_type": null,
        "closed_at": null,
        "settled_at": null,
        "manually_corrected_at": null,
        "language": "en",
        "credit_card": {
            "holder": "John Doe",
            "stamp": "a282993adc1299dacc79248e77e04c2995f79fcc9f82f408bec59ba20ff55739",
            "brand": "master",
            "last_4": "5003",
            "first_1": "5",
            "bin": "520424",
            "bin_8": "52042400",
            "issuer_country": null,
            "issuer_name": null,
            "product": null,
            "exp_month": 10,
            "exp_year": 2027,
            "token_provider": null,
            "token": null
        },
        "receipt_url": "https://bo.horizonpay.kz/customer/transactions/263586a3-50f6-4ff3-b9a0-ba5bd8f71b9d/c40a0033665f6fb8e7608c8a285644215802fb461288ec2e324bf507e045a9cd?language=en",
        "status_code": null,
        "gateway": {
            "iframe": true
        },
        "mute_notifications": null,
        "version": 5,
        "psp_settled_at": null,
        "registry_id": null,
        "id": "263586a3-50f6-4ff3-b9a0-ba5bd8f71b9d",
        "additional_data": {},
        "redirect_url": "https://gw.horizonpay.kz/process/263586a3-50f6-4ff3-b9a0-ba5bd8f71b9d",
        "code": "S.0000",
        "friendly_message": "The transaction is successfully processed.",
        "smart_routing_verification": {
            "status": "successful"
        },
        "conversion": {
            "converted_amount": 829,
            "converted_currency": "EUR",
            "exchange_rate": {
                "GBP_TO_EUR": 1.1843844993153705
            },
            "exchange_rate_date": "2025-03-11T09:03:07.978633Z"
        },
        "payment": {
            "auth_code": "654321",
            "bank_code": "05",
            "rrn": "999",
            "ref_id": "777888",
            "message": "Payment was approved",
            "amount": 700,
            "currency": "GBP",
            "billing_descriptor": "test descriptor",
            "gateway_id": 71839,
            "status": "successful"
        },       
        "customer": {
            "ip": null,
            "email": null,
            "device_id": "",
            "birth_date": "",
            "external_id": null
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "address": "",
            "country": "GB",
            "city": "London",
            "zip": "",
            "state": "",
            "phone": ""
        }
    }
}

Currency converter

conversion object

`conversion` object