Cross Currency Funding Rules (New)

Where enabled in your contract, you can set up a cross-currency funding rule so that one of your accounts is automatically topped up from another account you hold in a different currency. Modulr handles the foreign exchange (FX) conversion as part of the transfer.

Overview

The primary use for this is card spend in a currency you do not hold a balance in. You can issue cards in one currency, for example EUR, while keeping your funds in another, for example GBP. Linking the card's payment account to a funding account in your holding currency means each authorisation is converted and funded at the point of spend, so you never pre-convert funds or leave a balance sitting idle in the card currency.

Account Roles

A rule pairs two accounts:

When the rule is triggered, Modulr converts the shortfall using the FX rate available to you for that currency pair and moves the funds from the source account to the destination account as an internal (account to account) payment.

Rule IDs are returned with a CCF prefix, for example CCF0000001.

Rates and supported currency pairs follow the same model as internal transfers with currency conversion. See Internal account to account transfers for the currencies available and how rates are applied (https://modulr.readme.io/update/docs/internal-account-to-account-transfers).

📘 Not the same as a same-currency funding rule

If both accounts are in the same currency, use the existing same-currency FUNDING rule type on the generic rules endpoints instead. Cross-currency funding rules require the two accounts to be in different currencies.

Eligibility Conditions

• Rule name - Every rule needs a name. It must not be blank and must be 18 characters or fewer. Names do not need to be unique, so two rules can share a name.

• Destination account uniqueness - The destination account must not already have an active rule. An account can only be topped up by one funding source at a time.

• Supported currencies - Either the source or destination account must in GBP, EUR, or USD.

• Different currencies - The two accounts must be in different currencies. This feature exists specifically to bridge two currencies. If both accounts share a currency, a same-currency funding rule covers that instead.

• Source account not a destination — The source account must not already be a destination in another active funding rule. This prevents rules being chained together, for example A tops up B, which tops up C.

• Destination account not a source - The destination account must not already be a source in another active funding rule. This prevents circular set-ups where the same account both receives funding and passes money onward.

Create a Rule

Pick the account to be topped up, the account that funds it, and give the rule a name.

Endpoint: POST /rules/cross-currency-funding

Request

Example:

{
  "destinationAccountId": "A1000003",
  "sourceAccountId": "A1000004",
  "name": "FX Top-up"
}

Response: 201 Created

{
  "id": "CCF0000001",
  "name": "FX Top-up",
  "status": "ACTIVE",
  "destinationAccountId": "A1000003",
  "destinationCurrency": "GBP",
  "sourceAccountId": "A1000004",
  "sourceCurrency": "EUR"
}

Edit a Rule

Use this to change which account funds an existing rule, or to rename it.

Endpoint: PUT /rules/cross-currency-funding/{ruleId}

The destination account cannot be changed. To move funding to a different destination account, delete the rule and create a new one.

Editing re-runs all of the eligibility conditions (except condition 1) against the new source account, so swapping the source re-validates FX status, currency eligibility, and the no-chaining rules from scratch.

🚧 The rule ID changes on every successful edit

Editing replaces the rule rather than amending it in place, so the response returns a new id. There is no stable ID carried across edits. If you store rule IDs on your side, update them from the edit response.

Returns the same response body as create with 200 OK, or 404 if the rule ID does not exist.

Retrieve Rules

Lists your existing cross-currency funding rules. Filter to specific accounts, or omit the filter to see all of them.

Endpoint: GET /rules/cross-currency-funding

Query Parameters

Response: 200 OK

{
  "content": [
    {
      "id": "CCF0000001",
      "name": "FX Top-up",
      "status": "ACTIVE",
      "destinationAccountId": "A1000003",
      "destinationCurrency": "GBP",
      "sourceAccountId": "A1000004",
      "sourceCurrency": "EUR"
    }
  ],
  "size": 20,
  "totalSize": 1,
  "page": 0,
  "totalPages": 1
}

There is no single-rule GET by ID. To look up one rule, call this endpoint filtered by accountIds.

Delete a Rule

Deleting switches a rule off. There is no cross-currency-specific delete route: deletion uses the same generic rule delete endpoint as all other rule types.

Endpoint: DELETE /rules?rIds={ruleId}

You can pass multiple rule IDs as a comma-separated list.

Requires DELETE permission for the RULE action on the destination account.

Deleted rules no longer appear in the retrieve endpoint.