Multi-Currency Accounts (MCAs) are specialized bank accounts that allow users to hold, manage, exchange, and transact in multiple currencies. Unlike a standard bank account—which is typically denominated in a single currency—a Multi-Currency Account offers the account holder the flexibility to work with different currencies without needing to convert funds.

What Can You Do with a Multi-Currency Account?

Deposit multiple currencies from around the world into your personal Multi-Currency Account.
Exchange any currency pairs within your Multi-Currency Account at competitive rates.
Transfer funds from your Multi-Currency Account to either an external recipient's bank account or another Multi-Currency Account within the same organization.

Supported Currencies & Payment Rails

View the full list of supported Pay-in/Collection currencies here.
View the full list of supported Payout currencies here.

Get Started

Prerequisites

To open a Multi-Currency Account, a HIFI user must first complete KYC verification for the MULTI_CURRENCY_ACCOUNT or MULTI_CURRENCY_ACCOUNT_EDD rail, depending on the nature of your business.

Learn more about KYC and unlocking rails here.
View the KYC requirements for the MULTI_CURRENCY_ACCOUNT and MULTI_CURRENCY_ACCOUNT_EDD rail here.

Multi-Currency Account Structure

The structure of a Multi-Currency Account is as follows:

Each HIFI User can open one Multi-Currency Account.
A Multi-Currency Account can have multiple Currency Accounts, each for a different currency.
Each Currency Account is associated with a specific currency and includes a set of Bank Account Details for deposit.
A Currency Account allows users to deposit a specific currency into their Multi-Currency Account. It functions as a virtual bank account designed solely to facilitate fund deposits into the Multi-Currency Account.

The diagram below illustrates the relationship between each of the components highlighted above.

Currency Account

A Currency Account allows users to deposit a specific currency into their Multi-Currency Account. It functions as a virtual bank account designed solely to facilitate fund deposits into the Multi-Currency Account and does not hold any funds itself, as all funds are held in the Multi-Currency Account.

To deposit fiat currency into a Multi-Currency Account, users must first apply for and open a Currency Account for the desired currency. This can be done via the Apply for a currency account endpoint.

Let's open a USD Currency Account with a bank located in the USA and an account purpose as "03" (Top-Up).

Learn more about the supported pay-in currencies and regions here.
Learn more about account purposes here.

Request:

curl --request POST \
     --url https://sandbox.hifibridge.com/v2/users/faf56e30-6806-46a9-ab46-f8413f191a01/multi-currency-account/currency-accounts \
     --header 'accept: application/json' \
     --header 'authorization: Bearer zpka_xxxxx' \
     --header 'content-type: application/json' \
     --data '
{
  "purpose": "03",
  "currency": "USD",
  "bankLocation": "USA"
}
'

Response:

{
    "id": "94420638-9445-4cc9-a40f-3d933380d8cf",
    "userId": "faf56e30-6806-46a9-ab46-f8413f191a01",
    "createdAt": "2025-02-17T21:32:56.668465+00:00",
    "updatedAt": "2025-02-17T21:33:07.197+00:00",
    "status": "CREATED",
    "accountHolderName": "",
    "accountType": "",
    "accountPurpose": "03",
    "currency": "USD",
    "bankName": "",
    "bankCode": "",
    "branchNumber": "",
    "accountNumber": "",
    "routingNumber": "",
    "swiftCode": "",
    "sortCode": "",
    "iban": "",
    "bankCountry": "USA",
    "bankCity": "",
    "bankAddress": "",
    "bankPostalCode": "",
  	"failedReason": ""
}

The Currency Account application will initially have a status of CREATED, indicating that it is waiting to be processed. You can either poll the Retrieve a Currency Account endpoint or wait for the Currency Account webhook event to receive the latest application status updates.

Once the application status changes to AVAILABLE, the Currency Account object will be populated with all the deposit information:

{
    "id": "80f08151-01ec-479b-9304-5d2820a21abd",
    "userId": "0e965562-047c-43ae-9481-fd894f7e6706",
    "createdAt": "2025-02-07T05:25:46.852516+00:00",
    "updatedAt": "2025-02-07T05:35:03.267+00:00",
    "status": "AVAILABLE",
    "accountHolderName": "Henry Wu",
    "accountType": "CHECKING",
    "accountPurpose": "03",
    "currency": "USD",
    "bankName": "Citibank",
    "bankCode": "",
    "branchNumber": "",
    "accountNumber": "73380000000363268",
    "routingNumber": "031100209",
    "swiftCode": "GEOORUMMXXX",
    "sortCode": "",
    "iban": "",
    "bankCountry": "United States",
    "bankCity": "New York",
    "bankAddress": "111 Wall Street, New York, New York 10043, United States",
    "bankPostalCode": "10043",
    "failedReason": ""
}

Deposit Funds

To deposit funds into your Multi-Currency Account, transfer fiat to the bank account information shown above. When making a deposit, ensure that you enter the provided deposit information accurately and ONLY deposit the same fiat currency that the Currency Account is designated for.

After transferring the funds, wait for the Deposit webhook event to track the deposit status.

Example Deposit:

{
    "createdAt": "2025-02-25T17:52:00.728965+00:00",
    "updatedAt": "2025-02-25T17:58:00.579+00:00",
    "id": "e37f0299-37b6-492b-8bee-263ee3f95979",
    "userId": "0e965562-047c-43ae-9481-fd894f7e6706",
    "type": "EXTERNAL",
    "currencyAccountId": "80f08151-01ec-479b-9304-5d2820a21abd",
    "sourceAmount": 10,
    "sourceCurrency": "USD",
    "receivedAmount": 10,
    "receivedCurrency": "USD",
    "feeAmount": 0,
    "feeCurrency": "USD",
    "feeRate": "",
    "debitedAmount": 10,
    "debitedCurrency": "USD",
    "rate": 1,
    "status": "COMPLETED",
    "swiftCode": "CITIUS22XXX",
    "payee": {
      "name": "Henry Wu",
      "address": "",
      "accountNumber": "71080000000444366"
    },
    "payer": {
      "name": "BANK OF AMERICA",
      "country": "",
      "address": "",
      "bankName": "",
      "accountNumber": "",
      "userId": null
    },
    "bankReference": "025056001474411",
    "rejectReason": "",
    "declareId": "",
    "remark": null,
    "reference": null
}

After the deposit status changes to COMPLETED, you can check your account balance to confirm that the deposit is successfully reflected in your Multi-Currency Account. To check the account balance, call the Retrieve account balance endpoint.

Response:

{
  "userId": "0e965562-047c-43ae-9481-fd894f7e6706",
  "balances": [
    {
      "currency": "USD",
      "amount": 10
    }
  ]
}

Currency Exchange

Once you have deposited funds into your Multi-Currency Account, you can exchange it to any supported currencies. Let's exchange USD for EUR as an example.

How to perform a currency exchange:

Get the FX Rate – Use the Get an FX rate endpoint to get the latest FX rate for your desired currency pair.
Create an FX Order – Execute the currency exchange with the FX rate using the Create an FX order endpoint.

Get an Exchange Rate

To retrieve an exchange rate, call the Get an FX rate endpoint, providing the currency pair and the amount you wish to exchange.

Request:

curl --request POST \
     --url https://sandbox.hifibridge.com/v2/multi-currency-account/exchanges/rate \
     --header 'accept: application/json' \
     --header 'authorization: Bearer zpka_xxxxx' \
     --header 'content-type: application/json' \
     --data '
{
  "source": {
    "currency": "USD",
    "amount": 10
  },
  "destination": {
    "currency": "EUR"
  },
  "userId": "faf56e30-6806-46a9-ab46-f8413f191a01"
}
'

Response:

{
    "id": "736c17bd-fcb1-4bb5-ad9b-76d74d7f8ca0",
    "createdAt": "2025-02-01T04:32:27.037269+00:00",
    "userId": "7a8ac012-f5e7-45e0-bda5-851f542b2e01",
    "source": {
        "amount": 10,
        "currency": "USD"
    },
    "destination": {
        "amount": 9.62,
        "currency": "EUR"
    },
    "rate": 0.96189,
    "expiresAt": "2025-02-01T04:33:26.557+00:00"
}

Exchange Currencies Using an Exchange Rate

Once you have obtained an exchange rate, you can proceed with the currency exchange by using the exchange rate id.

Request:

curl --request POST \
     --url https://sandbox.hifibridge.com/v2/multi-currency-account/exchanges \
     --header 'accept: application/json' \
     --header 'authorization: Bearer zpka_xxxxx' \
     --header 'content-type: application/json' \
     --data '
{
  "source": {
    "currency": "USD",
    "amount": 10
  },
  "destination": {
    "currency": "EUR"
  },
  "requestId": "79d661c4-f9d1-44a8-937a-0b3de6c6bf63",
  "userId": "7a8ac012-f5e7-45e0-bda5-851f542b2e01",
  "rateId": "736c17bd-fcb1-4bb5-ad9b-76d74d7f8ca0"
}
'

Response:

{
    "id": "dc93b3d3-ae96-4bd6-848f-7e96adb0082f",
    "createdAt": "2025-02-11T15:23:59.811266+00:00",
    "updatedAt": "2025-02-11T15:24:02.604+00:00",
    "requestId": "bf068b04-66cb-4658-b84d-7ecea493de85",
    "userId": "7a8ac012-f5e7-45e0-bda5-851f542b2e01",
    "rateId": "736c17bd-fcb1-4bb5-ad9b-76d74d7f8ca0",
    "source": {
        "amount": 10,
        "currency": "USD"
    },
    "destination": {
        "amount": 9.62,
        "currency": "EUR"
    },
    "reference": null,
    "status": "CREATED",
    "failedReason": ""
}

Transfer

You can transfer funds from your Multi-Currency Account to:

An external recipient (e.g., a bank account outside your organization).
Another internal Multi-Currency Account owned by a user within your organization.

The diagram below illustrates these two types of transfers:

Transfer to an External Recipient

Transferring funds to an external recipient involves two steps:

Create a recipient – The recipient must pass KYC before receiving funds.
Create a transfer – Initiate the transfer to the recipient.

Create a recipient

Use the Create a recipient endpoint to register a recipient. You will need to provide the recipient's bank details along with their personal or business information, depending on whether the recipient is an individual or a business entity.

Request:

curl --request POST \
     --url https://sandbox.hifibridge.com/v2/multi-currency-account/transfers/recipients \
     --header 'accept: application/json' \
     --header 'authorization: Bearer zpka_xxxxx' \
     --header 'content-type: application/json' \
     --data '
{
  "type": "individual",
  "bank": {
    "accountType": "CHECKING",
    "address": {
      "addressLine1": "Example St 1.",
      "city": "New York",
      "stateProvinceRegion": "NY",
      "postalCode": "10003",
      "country": "USA"
    },
    "currency": "USD",
    "accountName": "Henry Wu",
    "accountNumber": "123456788",
    "bankName": "Bank of America",
    "routingNumber": "026009593"
  },
  "recipient": {
    "address": {
      "addressLine1": "Example St 1.",
      "city": "New York City",
      "stateProvinceRegion": "NY",
      "postalCode": "10003",
      "country": "USA"
    },
    "type": "20",
    "phone": "+185743482934",
    "email": "[email protected]",
    "name": "Henry Wu",
    "nationality": "USA",
    "occupation": "40400"
  },
  "userId": "7a8ac012-f5e7-45e0-bda5-851f542b2e01"
}
'

Response:

{
    "id": "6e6316b0-630f-4775-9f6c-21bc4a0bd0fe",
    "createdAt": "2025-02-11T15:43:42.327349+00:00",
    "updatedAt": "2025-02-11T15:43:49.861+00:00",
    "status": "CREATED",
    "rejectionReasons": null,
    "userId": "7a8ac012-f5e7-45e0-bda5-851f542b2e01",
    "type": "individual",
    "recipient": {
        "type": "20",
        "name": "Henry Wu",
        "phone": "+185743482934",
        "email": "[email protected]",
        "address": {
            "city": "New York",
            "country": "USA",
            "postalCode": "10003",
            "addressLine1": "Example St 1.",
            "stateProvinceRegion": "NY"
        },
        "nationality": "USA",
        "occupation": "40400",
        "certificationType": null,
        "certificationNumber": null,
        "certificationFrontUrl": null,
        "certificationBackUrl": null,
        "certificationIssuanceAuth": null,
        "certificationIssuanceDate": null,
        "certificationExpirationDate": null
    },
    "bank": {
        "currency": "USD",
        "accountName": "Henry Wu",
        "accountType": "CHECKING",
        "accountNumber": "123456788",
        "accountPurpose": null,
        "accountHolder": {
            "address": null,
            "phone": null,
            "govIdType": null,
            "govIdNumber": null
        },
        "bankName": "Bank of America",
        "bankCode": null,
        "branchName": null,
        "branchCode": null,
        "ifscCode": null,
        "sortCode": null,
        "address": {
        		"addressLine1": "Example St 1.",
          	"city": "New York",
          	"stateProvinceRegion": "NY",
          	"postalCode": "10003",
          	"country": "USA"
        },
        "swiftCode": null,
        "routingNumber": "026009593",
        "iban": null
    }
}

The recipient will initially have a status of CREATED. You can either poll the Get a recipient endpoint or wait for the Recipient webhook event to receive the latest recipient KYC status updates.

Create a payout transfer

When initiating a payout transfer, you need to specify the transfer type, ensuring that it is not INTERNAL_TRANSFER, as that is used for transfers between internal Multi-Currency Accounts (which will be covered later).

Additionally, you must specify the paymentMethod to indicate whether the transfer is:

CROSS-BORDER – Uses SWIFT as the PaymentNetwork.
LOCAL – Uses the respective local payment network.

In the transfer request:

The source object represents the user sending the funds.
The destination object represents the recipient receiving the funds.

Request:

curl --request POST \
     --url https://sandbox.hifibridge.com/v2/multi-currency-account/transfers \
     --header 'accept: application/json' \
     --header 'authorization: Bearer zpka_xxxxx' \
     --header 'content-type: application/json' \
     --data '
{
	"requestId": "6d136d9a-a3cd-4f74-a7b0-a7dcbd028293",
  "type": "PAYOUT",
  "paymentMethod": "CROSS-BORDER",
  "paymentNetwork": "SWIFT",
  "feeBearer": "OUR",
  "purpose": "1001",
  "pobo": true,
  "source": {
    "userId": "7a8ac012-f5e7-45e0-bda5-851f542b2e01",
    "amount": "10",
    "currency": "USD"
  },
  "destination": {
    "currency": "USD",
    "recipientId": "6e6316b0-630f-4775-9f6c-21bc4a0bd0fe"
  }
}
'

Response:

{
    "id": "ba1ed885-30f3-427d-a5f1-0404db7fef89",
    "createdAt": "2025-02-14T22:21:02.280578+00:00",
    "updatedAt": "2025-02-14T22:21:06.024+00:00",
    "requestId": "ba1ed885-30f3-427d-a5f1-0404db7fef89",
    "type": "PAYOUT",
    "status": "CREATED",
    "description": null,
    "paymentMethod": "CROSS-BORDER",
    "paymentNetwork": "SWIFT",
    "source": {
        "userId": "0e965562-047c-43ae-9481-fd894f7e6706",
        "amount": 11,
        "currency": "USD"
    },
    "destination": {
        "amount": 10,
        "currency": "USD",
        "recipientId": "6e6316b0-630f-4775-9f6c-21bc4a0bd0fe",
        "userId": null
    },
    "rateId": null,
    "feeBearer": "OUR",
    "purpose": "1001",
    "gpi": null,
    "failedReason": null,
    "remark": null
}

The payout transfer will initially have a status of CREATED. You can either poll the Retrieve a transfer endpoint or wait for the Transfer webhook event to receive the latest payout transfer status updates.

Create an Internal Transfer

To create an internal transfer, set the transfer type to INTERNAL_TRANSFER and specify the destination user who will receive the funds.

Request:

curl --request POST \
     --url https://sandbox.hifibridge.com/v2/multi-currency-account/transfers \
     --header 'accept: application/json' \
     --header 'authorization: Bearer zpka_xxxxx' \
     --header 'content-type: application/json' \
     --data '
{
	"requestId": "6d136d9a-a3cd-4f74-a7b0-a7dcbd028293",
  "type": "INTERNAL_TRANSFER",
  "feeBearer": "OUR",
  "purpose": "1001",
  "source": {
    "userId": "7a8ac012-f5e7-45e0-bda5-851f542b2e01",
    "amount": "10",
    "currency": "USD"
  },
  "destination": {
    "currency": "USD",
		"userId": "7a8ac012-f5e7-45e0-bda5-851f542b2e01"
  }
}
'

Response:

{
    "id": "ba1ed885-30f3-427d-a5f1-0404db7fef89",
    "createdAt": "2025-02-14T22:21:02.280578+00:00",
    "updatedAt": "2025-02-14T22:21:06.024+00:00",
    "requestId": "ba1ed885-30f3-427d-a5f1-0404db7fef89",
    "type": "INTERNAL_TRANSFER",
    "status": "CREATED",
    "description": null,
    "paymentMethod": null,
    "paymentNetwork": null,
    "source": {
        "userId": "0e965562-047c-43ae-9481-fd894f7e6706",
        "amount": 11,
        "currency": "USD"
    },
    "destination": {
        "amount": 10,
        "currency": "USD",
      	"recipientId": null,
        "userId": "0e965562-047c-43ae-9481-fd894f7e6706"
    },
    "rateId": null,
    "feeBearer": "OUR",
    "purpose": "1001",
    "gpi": null,
    "failedReason": null,
    "remark": null
}