Multi-currency

Charge credit and debit cards in a currency other than your account funding currency using Multi-currency. We transparently handle the exchange into your account funding currency (settlement currency) allowing cardholders to make purchases in their preferred currency (presentment currency).

Read on to learn how to use this feature.

How to enable

• Supported Countries: Thailand, Singapore, Japan
• Minimum API version: 2014-07-27

To enable Multi-currency, send an email requesting this feature to support@opn.ooo. You will need to review and accept new terms and conditions.

Note:

• This feature only supports credit and debit card charges; alternative payment methods (e.g. Internet Banking) are not supported
• For Thailand, this feature only supports Visa and Mastercard brand cards
• In certain circumstances, the cardholder may be charged a foreign transaction fee by their issuing bank even if they pay in their native currency

Supported currencies

Currencies supported depend on the country in which your account is registered.

* Multi-currency is not supported for accounts registered in Japan.
† Account funding currency

Implementation

Let's walk through the steps to create a charge for $1,000 USD using an account registered in Thailand.

Creating a multi-currency charge is similar to creating a normal charge.

1. Create a token.
2. Create a charge using the identifier of the token created in Step 1 specifying a currency other than your account funding currency.

Creating a token

Follow the instructions on the Omise.js guide to learn how to create a token. For testing, you can follow the examples listed here. For a simple payment form, insert the following into your checkout page.

<form id="checkout-form" method="POST" action="/checkout">
  <script type="text/javascript" src="https://cdn.omise.co/omise.js"
          data-key="OMISE_PUBLIC_KEY"
          data-amount="100000"
          data-currency="USD">
  </script>
</form>

Creating a multi-currency charge

Using the token created in the previous step, create a charge API request. Check the resulting charge object for the following attributes:

• currency: the currency in which the charge was created (USD).
• funding_currency: account funding currency (THB).
• funding_amount: charge amount after exchange into your account funding currency.

Except for amount and refunded_amount, all amounts are specified in the account funding currency.

curl https://api.omise.co/charges \
  -X POST \
  -u $OMISE_SECRET_KEY: \
  -d "amount=100000" \
  -d "currency=USD" \
  -d "card=$TOKEN_ID"

{
  "object": "charge",
  "id": "chrg_test_5xmy72tvpo3rwx7gq67",
  "location": "/charges/chrg_test_5xmy72tvpo3rwx7gq67",
  "amount": 100000,
  "net": 3331926,
  "fee": 126558,
  "fee_vat": 8859,
  "interest": 0,
  "interest_vat": 0,
  "funding_amount": 3467343,
  "refunded_amount": 0,
  "transaction_fees": {
    "fee_flat": "0.0",
    "fee_rate": "3.65",
    "vat_rate": "7.0"
  },
  "platform_fee": {
    "fixed": null,
    "amount": null,
    "percentage": null
  },
  "currency": "USD",
  "funding_currency": "THB",
  "ip": null,
  "refunds": {
    "object": "list",
    "data": [],
    "limit": 20,
    "offset": 0,
    "total": 0,
    "location": "/charges/chrg_test_5xmy72tvpo3rwx7gq67/refunds",
    "order": "chronological",
    "from": "1970-01-01T00:00:00Z",
    "to": "2023-11-02T07:17:35Z"
  },
  "link": null,
  "description": null,
  "metadata": {},
  "card": {
    "object": "card",
    "id": "card_test_5xmy72opa2bvi6r1xlw",
    "livemode": false,
    "location": null,
    "deleted": false,
    "street1": null,
    "street2": null,
    "city": "Bangkok",
    "state": null,
    "phone_number": null,
    "postal_code": "10320",
    "country": "us",
    "financing": "credit",
    "bank": "JPMORGAN CHASE BANK N.A.",
    "brand": "Visa",
    "fingerprint": "oWOKTxZALCVYePaebQLM0gaZIrPlXZ7JRtR0i0CDQyY=",
    "first_digits": null,
    "last_digits": "4242",
    "name": "Somchai Prasert",
    "expiration_month": 9,
    "expiration_year": 2024,
    "security_code_check": true,
    "tokenization_method": null,
    "created_at": "2023-11-02T07:17:34Z"
  },
  "source": null,
  "schedule": null,
  "customer": null,
  "dispute": null,
  "transaction": "trxn_test_5xmy72xrjn0292b8ge3",
  "failure_code": null,
  "failure_message": null,
  "status": "successful",
  "authorize_uri": null,
  "return_uri": null,
  "created_at": "2023-11-02T07:17:35Z",
  "paid_at": "2023-11-02T07:17:35Z",
  "expires_at": "2023-11-09T07:17:35Z",
  "expired_at": null,
  "reversed_at": null,
  "zero_interest_installments": false,
  "branch": null,
  "terminal": null,
  "device": null,
  "authorized": true,
  "capturable": false,
  "capture": true,
  "disputable": true,
  "livemode": false,
  "refundable": true,
  "partially_refundable": true,
  "reversed": false,
  "reversible": false,
  "voided": false,
  "paid": true,
  "expired": false
}

Exchange rates

For multi-currency charges, the amount specified in the original charge is transparently exchanged into your account funding currency at a rate approximately 2-4% above the daily mid-market rate. To see the exchange rate used, send a request to the Forex API.

Since minimum and maximum amounts for a charge are set in your account funding currency, the effective minimum and maximum amounts for a multi-currency charge will vary depending on the current exchange rate.

curl https://api.omise.co/forex/usd \
  -u $OMISE_SECRET_KEY:

{
  "object": "forex",
  "rate": 34.6734328959,
  "location": "/forex/usd",
  "livemode": false,
  "base": "USD",
  "quote": "THB"
}

Refunds

Create a full or partial refund for a multi-currency charge using the Refund API or the dashboard. The exchange rate used is the rate at the time you create the refund. The refund will be processed in the original charge currency, so you only need to supply the amount.

curl https://api.omise.co/charges/$CHARGE_ID/refunds \
  -X POST \
  -u $OMISE_SECRET_KEY: \
  -d "amount=100000"

{
  "object": "refund",
  "id": "rfnd_test_5xmy73639uxyxnjc8i6",
  "location": "/charges/chrg_test_5xmy72beskbrpn2gwiu/refunds/rfnd_test_5xmy73639uxyxnjc8i6",
  "livemode": false,
  "voided": true,
  "currency": "USD",
  "amount": 100000,
  "metadata": {},
  "charge": "chrg_test_5xmy72beskbrpn2gwiu",
  "terminal": null,
  "transaction": "trxn_test_5xmy736d5fp7vo2n95k",
  "status": "closed",
  "funding_amount": 3467343,
  "funding_currency": "THB",
  "created_at": "2023-11-02T07:17:36Z"
}

Dashboard

See the multi-currency charge details on your account dashboard:

Errors

If multi-currency is not enabled, a multi-currency charge will fail with the error failed_multi_currency. Contact support@opn.ooo if you encounter this error.

If the charge currency is not supported for your account, a multi-currency charge will fail with the error invalid_charge.

Next steps

• Charge API
• Currency and Amount