Skip to main content
Aikeedo prices plans in one currency. When a payment gateway bills in a different one, it converts the amount through the configured rate provider. Without a provider, only currencies with a custom rate are converted, and any other currency is treated as equal to USD.

The interface

getRate() returns the multiplier that converts an amount in $from into $to. It’s called during checkout, so it must be fast and must not throw for a currency pair you support. Those two methods are the whole contract. canConvert() and getProviderRates(), which the admin panel and the MRR calculation use, belong to the core wrapper described below, not to your provider.

Custom rates override yours

Aikeedo never hands your provider to the rest of the application directly. It wraps the selected provider in Billing\Infrastructure\Currency\CustomRateProvider, and that wrapper is what’s bound to RateProviderInterface. Administrators set custom rates under Settings → Exchange → Custom rates, stored in option.currency.rates as units of each currency per 1 USD. For each conversion, the wrapper:
  1. Passes the pair to your provider unchanged when neither currency has a custom rate.
  2. Otherwise uses the custom rate for each side that has one, and asks your provider for the other side against USD, as getRate(USD, $currency).
So support USD as the $from currency for every currency you cover, even if your API quotes against another base. The custom rates page also shows your provider’s rate next to each custom one, fetched the same way.

Implementation

Rates change slowly, so fetch them in bulk and cache them. Storing them in an option makes them survive cache clears and keeps the checkout path free of network calls.
src/AcmeRates.php
A conversion failure is swallowed by the billing helper, which then charges the original amount in the original currency. That’s safer than blocking checkout, but it means a broken provider is invisible to the customer. Log failures so administrators can see them.

Register it

src/Plugin.php
The provider appears in the Currency rate provider select under Settings → Billing, and the choice is stored in option.currency.provider.

Settings page

The billing page links to /admin/settings/rate-providers/{key}, so declare that route and point extra.default_url at it:
Show the API key field, and the timestamp of the last successful refresh, so administrators can tell whether rates are current.

Testing

Set a gateway to a currency other than the platform default and confirm the charge is converted.
The converted amount is plausible, and rounding lands on whole minor units.
Rates are fetched once and reused until they expire.
The custom rates page shows your rate next to each currency, and a custom rate overrides yours.
With an invalid API key, checkout still completes in the default currency.

A public reference implementation

The Currency Beacon plugin is a small, complete rate-provider plugin you can read end to end.