Dynamic Currency Conversion

Dynamic Currency Conversion (DCC) is a real-time conversion service that allows your customers to pay in their local currency while you get settled in your preferred currency. This offers a seamless and familiar checkout experience for your customers.

Here's how Dynamic Currency Conversion works:

  • Kora converts transaction amount: Our system automatically converts the transaction amount to the customer's local currency using the real-time exchange rate.
  • Customer makes payment: The customer sees the total amount in their local currency and proceeds to make the payment.
  • Transaction processed: The payment is processed as usual, with the settlement amount converted back to your preferred settlement currency.

Getting Started with Dynamic Currency Conversions

To get started with DCC, follow these steps:

  1. First, you need access to the Currency Conversions service. See here.

  2. Once you have access to Currency Conversions,

    1. Go to Settings > Settlements
    2. Select the currency for which you want to set this conversions setting (Swap Settlements), and check the "Allow this merchant to settle payments in another currency" checkbox.
    3. Save changes to enable your preference to take effect.
  3. Initiate a DCC transaction and include the following additional parameters in your payment request:

    1. payment_currency: The currency that the customer pays in (their local currency).
    2. settlement_currency: The currency in which you want to receive settlement.

Here's an example of a request initiating a DCC transaction:

{
    "amount": 10000,
    "currency": "USD",
    "payment_currency": "NGN",
    "settlement_currency": "USD",
    "reference": "your-transaction-reference-001",
    "narration": "Payment for product Y",
    "channels": "card",
    "default_channel": "card",
    "customer": {
        "name": "John Doe",
        "email": "[email protected]"
    },
    "notification_url": "https://webhook.site/8d321d8d-397f-4bab-bf4d-7e9ae3afbd50",
    "metadata":{
        "key0": "test0"
    }
}

The responses to this request would look like this:

{
    "status": true,
    "message": "Charge created successfully",
    "customer": {
        "reference": "your-transaction-reference-001",
        "checkout_url": "https://checkout.korapay.com/KPY-PI-202501231hXn08399/pay"
    }
}

Some important things to note:

  • The currency field should indicate the currency of the amount sent for collection.
  • Both payment_currency and settlement_currency must be supported by Kora.
  • The exchange rate can be marked up in the settlement settings on the dashboard.

If you have any questions or feedback on currency conversions, kindly email our support team at [email protected].