Multi-currency

Charge credit and debit cards in a currency other than your account funding currency using Multi-currency. Omise transparently handles 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
  • Minimum API version: 2014-07-27

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.

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.

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_5il9svaq5r9ygttr2dz",
  "livemode": false,
  "location": "/charges/chrg_test_5il9svaq5r9ygttr2dz",
  "created_at": "2020-01-17T09:46:12Z",
  "amount": 100000,
  "currency": "USD",
  "funding_amount": 2925392,
  "funding_currency": "THB",
  "fee": 106777,
  "fee_vat": 7474,
  "interest": 0,
  "interest_vat": 0,
  "net": 2811141,
  "description": null,
  "metadata": {},
  "status": "successful",
  "capture": true,
  "authorized": true,
  "schedule": null,
  "reversed": false,
  "reversed_at": null,
  "expires_at": "2020-01-24T09:46:12Z",
  "expired": false,
  "expired_at": null,
  "voided": false,
  "paid": true,
  "paid_at": "2020-01-17T09:46:12Z",
  "transaction": "trxn_test_5il9svcybr6eevu1uf1",
  "refunded_amount": 0,
  "refunds": {
    "object": "list",
    "from": "1970-01-01T00:00:00Z",
    "to": "2020-01-17T09:46:12Z",
    "offset": 0,
    "limit": 20,
    "total": 0,
    "order": "chronological",
    "location": "/charges/chrg_test_5il9svaq5r9ygttr2dz/refunds",
    "data": []
  },
  "link": null,
  "return_uri": null,
  "failure_code": null,
  "failure_message": null,
  "card": {
    "object": "card",
    "id": "card_test_5il9sv6orjdegckzy18",
    "livemode": false,
    "location": null,
    "created_at": "2020-01-17T09:46:11Z",
    "deleted": false,
    "street1": null,
    "street2": null,
    "city": "Bangkok",
    "state": null,
    "postal_code": "10320",
    "country": "gb",
    "phone_number": null,
    "financing": "credit",
    "bank": "SAMPLE BANK",
    "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,
  "zero_interest_installments": 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.

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",
  "location": "/forex/usd",
  "livemode": false,
  "base": "USD",
  "quote": "THB",
  "rate": 29.25392
}

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_5il9svkbk6ajv76mr3q",
  "livemode": false,
  "location": "/charges/chrg_test_5il9suwztcpi3k6fr62/refunds/rfnd_test_5il9svkbk6ajv76mr3q",
  "created_at": "2020-01-17T09:46:13Z",
  "status": "closed",
  "amount": 100000,
  "currency": "USD",
  "funding_amount": 2925392,
  "funding_currency": "THB",
  "voided": true,
  "charge": "chrg_test_5il9suwztcpi3k6fr62",
  "transaction": "trxn_test_5il9svkozuetlnn4e4u",
  "metadata": {}
}

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.

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

Next steps