Multi-currency

Summary: Accept payments in multiple currencies with Omise multi-currency charging. Charge credit and debit cards in USD, EUR, GBP, and other supported currencies while receiving settlements in your local currency (THB, SGD, or JPY). This guide covers setup, implementation, exchange rates, international card processing with AVS, refunds, troubleshooting, and frequently asked questions.

Key Features: - Charge in 12+ currencies including USD, EUR, GBP, JPY, AUD, and more - Automatic currency conversion with transparent exchange rates - Support for Visa and Mastercard credit and debit cards - Available for Thailand and Singapore merchants - Integration with Address Verification Service (AVS) for international cards

Important: When charging in a non-native currency, cardholders are subject to their card issuer's foreign exchange rate, which may differ from the Omise rate. For high-value transactions, this can result in differences of 2,000–3,000 THB or more. We recommend charging in the customer's local currency whenever possible.

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 purchase 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.

Important Notes

• This feature only supports credit and debit card charges; alternative payment methods (e.g., Internet Banking) are not supported
• 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

Foreign Exchange Rate Considerations

When charging in a non-native currency (a currency different from your settlement currency), cardholders will be subject to the foreign exchange rate determined by their card issuer. This issuer FX rate is often higher than the rate applied by Omise at the time of the charge and is not controlled by Omise.

Important: In high-value transactions, FX discrepancies between the Omise rate and the card issuer rate can result in differences of 2,000–3,000 THB or more. To avoid customer confusion and potential disputes, we recommend charging in the local currency whenever possible.

Supported Currencies

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

† Account funding currency

Implementation

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

Creating a multi-currency charge is similar to creating a standard charge:

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

Creating a Token

To create a token, follow the instructions in the Omise.js guide. Follow the examples listed here for testing. 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"

Response:

{
  "object": "charge",
  "id": "chrg_test_5vkl514m8b2vdc6a4a0",
  "location": "/charges/chrg_test_5vkl514m8b2vdc6a4a0",
  "amount": 100000,
  "net": 3174670,
  "fee": 120585,
  "fee_vat": 8441,
  "interest": 0,
  "interest_vat": 0,
  "funding_amount": 3303696,
  "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_5vkl514m8b2vdc6a4a0/refunds",
    "order": "chronological",
    "from": "1970-01-01T00:00:00Z",
    "to": "2023-04-26T04:22:24Z"
  },
  "link": null,
  "description": null,
  "metadata": {},
  "card": {
    "object": "card",
    "id": "card_test_5vkl50xxlu3b5hu2qwx",
    "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": "XjOdjaoHRvUGRfmZacMPcJtm0U3SEIIfkA7534dQeVw=",
    "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-04-26T04:22:22Z"
  },
  "source": null,
  "schedule": null,
  "customer": null,
  "dispute": null,
  "transaction": "trxn_test_5vkl518v7tgkff10rxo",
  "failure_code": null,
  "failure_message": null,
  "status": "successful",
  "authorize_uri": null,
  "return_uri": null,
  "created_at": "2023-04-26T04:22:23Z",
  "paid_at": "2023-04-26T04:22:23Z",
  "expires_at": "2023-05-03T04:22:23Z",
  "expired_at": null,
  "reversed_at": null,
  "zero_interest_installments": true,
  "branch": null,
  "terminal": null,
  "device": null,
  "authorized": true,
  "capturable": false,
  "capture": true,
  "disputable": true,
  "livemode": false,
  "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 approximately 2-4% above the daily mid-market rate. Request the Forex API to see the exchange rate used by Omise.

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:

Response:

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

Processing International Cards

Although multi-currency transactions and international cards are technically different concepts, they often occur together in practice. Most merchants who accept multi-currency payments are also processing international cards.

Improving Authorization Rates with AVS

When planning to accept multi-currency payments, you should also consider implementing Address Verification Service (AVS) on your credit card form. AVS significantly improves authorization success rates for international cardholders, especially from the United States, United Kingdom, and Canada.

For detailed guidance on AVS implementation, see: How can I improve my authorization rate for US, UK, and Canadian cardholders?

Implementing AVS will help reduce failed transactions related to international card validation and improve the overall payment experience for your customers.

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"

Response:

{
  "object": "refund",
  "id": "rfnd_test_5vkl51js322cag57de2",
  "location": "/charges/chrg_test_5vkl50ovmiye8iui9ch/refunds/rfnd_test_5vkl51js322cag57de2",
  "livemode": false,
  "voided": true,
  "currency": "USD",
  "amount": 100000,
  "metadata": {},
  "charge": "chrg_test_5vkl50ovmiye8iui9ch",
  "terminal": null,
  "transaction": "trxn_test_5vkl51k12dp76doxgvk",
  "status": "closed",
  "funding_amount": 3303696,
  "funding_currency": "THB",
  "created_at": "2023-04-26T04:22:25Z"
}

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. If you encounter this error, contact support@omise.co.

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

Troubleshooting

Common Issues and Solutions

Charge Fails with failed_multi_currency Error

Problem: Your multi-currency charge request returns a failed_multi_currency error.

Solution: This error indicates that multi-currency is not enabled on your account. Contact support@omise.co to enable this feature. You will need to review and accept the multi-currency terms and conditions.

Charge Fails with invalid_charge Error

Problem: Your charge request fails with an invalid_charge error when specifying a currency.

Solution: The currency you specified is not supported for your account's registered country. Check the Supported Currencies table to verify which currencies are available for your account location.

Customer Reports Higher Charge Amount Than Expected

Problem: A customer reports being charged more than the amount shown on your checkout page.

Root Cause: When charging in a currency different from the cardholder's native currency, their card issuer applies its own foreign exchange rate. This issuer FX rate is typically higher than the Omise exchange rate and can result in the cardholder seeing a different amount on their statement.

Solution: - Inform customers upfront that the final amount may vary slightly due to their bank's exchange rate - Whenever possible, charge in the customer's local currency to avoid FX discrepancies - For high-value transactions, consider displaying a disclaimer about potential currency conversion differences

International Card Authorization Failures

Problem: High failure rate for international cards, especially from US, UK, or Canadian cardholders.

Solution: Implement Address Verification Service (AVS) on your payment form. AVS significantly improves authorization success rates for international transactions. See How can I improve my authorization rate for US, UK, and Canadian cardholders? for implementation details.

Refund Amount Differs from Original Charge

Problem: The refund amount in your settlement currency differs from the original charge funding amount.

Explanation: Refunds use the exchange rate at the time the refund is created, not the original charge rate. If exchange rates have fluctuated between the charge and refund, the funding amounts will differ.

Note: The customer receives the refund in the original charge currency (the amount they paid), so they are not affected by this exchange rate difference.

Frequently Asked Questions

General Questions

Q: What is multi-currency charging?

A: Multi-currency charging allows you to charge customers in a currency different from your account's settlement currency. For example, a Thailand-based merchant (settled in THB) can charge customers in USD, EUR, GBP, or other supported currencies. Omise handles the currency conversion automatically.

Q: Which countries support multi-currency?

A: Multi-currency is currently available for accounts registered in Thailand and Singapore. Support varies by account location.

Q: Do I need special approval to use multi-currency?

A: Yes. You must contact support@omise.co to enable multi-currency on your account and accept the updated terms and conditions.

Q: Can I use multi-currency with any payment method?

A: No. Multi-currency only supports Visa and Mastercard credit and debit cards. Alternative payment methods like Internet Banking are not supported.

Currency and Exchange Rates

Q: How is the exchange rate determined?

A: Omise applies an exchange rate of approximately 2-4% above the daily mid-market rate when converting the charge currency to your settlement currency. You can check the current rate using the Forex API.

Q: Why does my customer see a different amount on their card statement?

A: When you charge in a currency different from your customer's native currency, their card issuer applies its own exchange rate to convert the charge. The issuer's rate is typically different (and often higher) than the Omise rate. This can result in a discrepancy between the amount shown at checkout and the amount on their statement. This FX rate is set by the card issuer, not by Omise.

Q: How much can exchange rate differences vary?

A: For high-value transactions, FX discrepancies between the Omise rate and the card issuer rate can result in differences of 2,000–3,000 THB or more. To minimize confusion, we recommend charging in the customer's local currency whenever possible.

Q: Can I lock in an exchange rate for a specific time period?

A: No. Exchange rates are dynamic and determined at the time of the transaction. Rates may change between authorization and settlement.

Q: What exchange rate is used for refunds?

A: Refunds use the exchange rate at the time the refund is created, not the original charge rate. The customer receives the refund in the original charge currency.

Fees and Settlements

Q: Are there additional fees for multi-currency charges?

A: The standard transaction fees apply. The exchange rate includes Omise's currency conversion margin (approximately 2-4% above mid-market rate). Check your transaction fees in the charge object's transaction_fees field.

Q: What currency will I receive in my settlement?

A: You always receive settlements in your account's funding currency (settlement currency). For example, if your account is registered in Thailand, you receive THB regardless of the charge currency.

Q: How do I know the converted amount before creating a charge?

A: Use the Forex API to check the current exchange rate. Multiply your charge amount by this rate to estimate the funding amount. Note that rates may change slightly between your check and the actual charge.

Q: What are the minimum and maximum charge amounts for multi-currency?

A: Minimum and maximum amounts are set in your account funding currency. The effective limits for a multi-currency charge vary depending on the current exchange rate. For example, if your minimum is 20 THB and you're charging in USD, the minimum USD amount will fluctuate based on the THB/USD exchange rate.

Technical Implementation

Q: How do I create a multi-currency charge?

A: Create a charge exactly as you would normally, but specify a currency parameter different from your settlement currency. See the Implementation section for step-by-step instructions.

Q: Can I test multi-currency in test mode?

A: Yes. Multi-currency works in test mode. Use test card numbers and API keys as documented in Tokens API.

Q: Which fields in the charge object show currency information?

A: Key fields include: - currency: The currency in which the charge was created (presentment currency) - funding_currency: Your account's settlement currency - amount: Charge amount in the presentment currency - funding_amount: Converted amount in your settlement currency

Q: Do I need to modify my checkout form for multi-currency?

A: You only need to specify the data-currency parameter in your Omise.js script. The rest of the implementation remains the same.

International Cards

Q: What's the difference between multi-currency and international cards?

A: Multi-currency refers to charging in different currencies (e.g., charging USD on a Thailand account). International cards refer to cards issued in a different country than your merchant account. While they're different concepts, they often occur together in practice.

Q: Why do international card authorizations fail more often?

A: International transactions face additional verification requirements from card issuers. Many failures occur because billing address information is missing or incorrect.

Q: What is AVS and why is it important for multi-currency?

A: Address Verification Service (AVS) verifies the cardholder's billing address with their issuing bank. For international cards (especially US, UK, and Canadian cards), AVS significantly improves authorization success rates. If you're accepting multi-currency payments, you're likely processing international cards and should implement AVS.

Q: Will customers be charged foreign transaction fees?

A: Possibly. Even when charging in the customer's native currency, their card issuer may apply foreign transaction fees if the merchant account is in a different country. This is determined by the card issuer's policies, not by Omise.

Refunds and Disputes

Q: How do I refund a multi-currency charge?

A: Create a refund using the Refund API or dashboard. Specify the amount in the original charge currency. The refund will be processed in the same currency the customer was originally charged.

Q: Can I do partial refunds on multi-currency charges?

A: Yes. Partial refunds work the same as with standard charges. Specify the amount you want to refund in the original charge currency.

Q: What happens if exchange rates change between charge and refund?

A: The customer receives their refund in the original charge currency, so they're unaffected by exchange rate changes. However, the converted amount in your settlement currency may differ from the original funding amount due to exchange rate fluctuations.

Q: How do disputes work with multi-currency charges?

A: Disputes are handled in the original charge currency. If you lose a dispute, the debited amount is converted to your settlement currency using the exchange rate at the time of the dispute resolution.

Next Steps

• Charge API
• Currency and Amount
• Forex API
• Refunds API