Multi-currency

Charge credit and debit cards in a currency other than your account currency using multi-currency. Cardholders can make purchases in their preferred currency (presentment currency) while Omise transparently handles exchange into your account funding currency (settlement currency).

Read on to learn how to use this feature.

Note: In certain circumstances, the cardholder may be charged a foreign transaction fee by their issuing bank even if they pay in their native currency.

How To Enable

By default, you are able to credit and debit card charges in your account funding currency only. You account funding currency is the currency in which your account is funded and is defined by your registered country (for example, THB for Thailand).

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

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

Note: Multi-currency only supports credit and debit card charges. Alternative payment methods are not supported.

Supported Currencies

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

Currency Name Thailand Singapore Japan*
AUD Australian Dollar
CAD Canadian Dollar
CHF Swiss Franc
CNY Yuan Renminbi (Chinese Yuan)
DKK Danish Krone
EUR Euro
GBP Pound Sterling (British Pound)
HKD Hong Kong Dollar
JPY Japanese Yen ✓†
MYR Malaysian Ringgit
SGD Singapore Dollar ✓†
THB Thai Baht ✓†
USD United States Dollar

* 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 new token.
  2. Create a new 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 new token. For testing, you can also 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 new 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_5h23i6pw9x1v0vifno6",
  "livemode": false,
  "location": "/charges/chrg_test_5h23i6pw9x1v0vifno6",
  "created_at": "2019-08-29T08:13:08Z",
  "amount": 100000,
  "currency": "USD",
  "funding_amount": 2946081,
  "funding_currency": "THB",
  "fee": 107532,
  "fee_vat": 7527,
  "interest": 0,
  "interest_vat": 0,
  "net": 2831022,
  "description": null,
  "metadata": {},
  "status": "successful",
  "capture": true,
  "authorized": true,
  "schedule": null,
  "reversed": false,
  "reversed_at": null,
  "expires_at": "2019-09-05T08:13:08Z",
  "expired": false,
  "expired_at": null,
  "voided": false,
  "paid": true,
  "paid_at": "2019-08-29T08:13:08Z",
  "transaction": "trxn_test_5h23i6rm47210ca26tg",
  "refunded_amount": 0,
  "refunds": {
    "object": "list",
    "from": "1970-01-01T00:00:00Z",
    "to": "2019-08-29T08:13:08Z",
    "offset": 0,
    "limit": 20,
    "total": 0,
    "order": "chronological",
    "location": "/charges/chrg_test_5h23i6pw9x1v0vifno6/refunds",
    "data": []
  },
  "link": null,
  "return_uri": null,
  "failure_code": null,
  "failure_message": null,
  "card": {
    "object": "card",
    "id": "card_test_5h23i6l9tllf4zdruc2",
    "livemode": false,
    "location": null,
    "created_at": "2019-08-29T08:13:07Z",
    "deleted": false,
    "street1": null,
    "street2": null,
    "city": "Bangkok",
    "state": null,
    "postal_code": "10320",
    "country": "gb",
    "phone_number": null,
    "financing": "credit",
    "bank": "Bank of the Unbanked",
    "first_digits": null,
    "last_digits": "4242",
    "brand": "Visa",
    "expiration_month": 9,
    "expiration_year": 2020,
    "fingerprint": "XjOdjaoHRvUGRfmZacMPcJtm0U3SEIIfkA7534dQeVw=",
    "name": "Somchai Prasert",
    "security_code_check": true
  },
  "customer": null,
  "ip": null,
  "dispute": null,
  "source": null,
  "platform_fee": {
    "percentage": null,
    "fixed": null,
    "amount": null
  },
  "disputable": true,
  "capturable": false,
  "reversible": false,
  "refundable": true,
  "authorize_uri": null
}

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.

curl https://api.omise.co/forex/usd \
  -u $OMISE_SECRET_KEY:
{
  "object": "forex",
  "location": "/forex/usd",
  "livemode": false,
  "base": "USD",
  "quote": "THB",
  "rate": 29.4608145
}

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.

Refunds

Create a full or partial refund for a multi-currency charge using the Refund API or from 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_5h23i71ml8s6bwxvguc",
  "livemode": false,
  "location": "/charges/chrg_test_5h23i6cjcc60lx7uiyc/refunds/rfnd_test_5h23i71ml8s6bwxvguc",
  "created_at": "2019-08-29T08:13:09Z",
  "status": "closed",
  "amount": 100000,
  "currency": "USD",
  "funding_amount": 2946081,
  "funding_currency": "THB",
  "voided": true,
  "charge": "chrg_test_5h23i6cjcc60lx7uiyc",
  "transaction": "trxn_test_5h23i71x9sdb0zvz807",
  "metadata": {}
}

Disputes and Chargebacks

The exchange rate used is the rate at the time we are notified of the dispute or chargeback by our partnering banks.

Dashboard

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

Multi-currency charge

Errors

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

Next Steps