How to add support for a new currency

Adding a currency touches two surfaces; both must be updated, or the currency appears in plan-creation UIs but no gateway is ever offered for it at checkout. Use this guide when onboarding a new currency end-to-end.

Overview

Adding a new currency touches two distinct surfaces:

• Static config in config/payments.php: lists of currencies, plus per-gateway mappings used by checkout logic.
• Runtime gateway data in the gateways table: each tenant's supported_currencies JSON array, read at checkout time. These are not the same source. Updating the config without also adding the currency code to at least one tenant's gateway row means the currency appears in plan-creation UIs but no gateway is ever selected at checkout.

The most common mistake is forgetting one of the auxiliary config arrays (zero_decimal_currencies, yuno_cross_border, gateway_no_recurring_currency_mapping). Each guards a specific behavior; missing one causes silent wrong amounts or unselectable gateways.

payment_type_gateway_mapping and gateway_no_recurring_currency_mapping are config arrays in config/payments.php, not database tables. Do not search for tables with those names.

Steps

1. Check what currencies each gateway supports:

   • MercadoPago documentation
   • Stripe
   • PayU
   • Yuno: confirm with the Yuno team; coverage varies by country and payment method.

2. Add the currency code (e.g. USD, CLP) to config/payments.php:

   • supported_currencies: the master list of currencies the platform accepts.
   • payment_type_gateway_mapping: maps which gateways support the currency for one_off and/or recurring payment types. Note that Yuno is not declared under payment_type_gateway_mapping.recurring (only mercadopago and stripe are). Adding Yuno there has no effect; Yuno recurring billing is handled separately by CheckYunoRecurringPayments. To add Yuno recurring coverage for a currency, the work lives in that job and the Yuno gateway settings, not in this array.
   • gateway_no_recurring_currency_mapping: if the currency cannot be used for recurring payments through a specific gateway, add it here for that gateway.
   • zero_decimal_currencies: required if the new currency has no minor unit (e.g. CLP, PYG). Skipping this sends amounts off by a factor of 100, since the platform's *_in_cents math assumes a two-decimal subunit by default.
   • yuno_cross_border: required if the currency must route through Yuno's cross-border product (currently includes CLP, MXN). Skipping this can prevent Yuno from accepting the payment for that currency.

3. Update each tenant that should accept the new currency:

   • On the relevant gateways row, add the currency code (uppercase) to supported_currencies. Routing reads this array at checkout. Without this step, the currency is configurable in plans but no gateway is ever selected for it at purchase time.

4. Update localization for the currency label:

   • resources/lang/en/dashboard.php (currencies key)
   • resources/lang/es/dashboard.php (currencies key)
   • resources/lang/pt/dashboard.php (currencies key)