Skip to main content

​
Initiate Exchange

Before creating an exchange, you must first fetch a rate from the utility endpoint /utility/exchange-rate. The _id from that response is required as the offerId parameter when creating the exchange. See the Get Rate guide for more details. When making an exchange, the initiating currency — the one the user is giving or has — is represented by buyerDebit, while the target currency — the one the user is receiving or wants — is represented by buyerCredit. The request body requires the following fields:
FieldRequiredDescription
amountYesThe amount in the initiating (debit) currency. Conversion into the credit currency is calculated based on current exchange rates and applicable fees.
buyerDebitPaymentMethodYesHow the user will send funds.
buyerCreditPaymentMethodYesHow the user will receive funds.
buyerDebitPaymentDetailsConditionalRequired unless buyerDebitPaymentMethod is WALLET.
buyerCreditPaymentDetailsConditionalRequired unless buyerCreditPaymentMethod is WALLET.
narrationNoA custom note or description attached to the transaction.
The shape of buyerDebitPaymentDetails and buyerCreditPaymentDetails depends on the payment method specified in their corresponding buyerCredit or buyerDebit PaymentMethod fields.

​
Supported Payment Methods

​
1. BANK_TRANSFER

Typically used for currencies such as NGN, USD, GBP, EUR, CAD, etc. Required fields: accountName, accountNumber, bankCode, providerName, currency, iso2, paymentMethod Additional required fields (GBP & EUR only): holderPostalCode, holderCity, holderStreet Notes:
  • The bankCode field is required. The network field must be omitted.
  • For NGN, providerName should be the name of the bank (e.g., Access Bank, GTBank).
  • For currencies that use routing or sort codes (e.g., USD, GBP, EUR), bankCode should contain the appropriate routing/sort code, and providerName should be the same as bankCode.
  • For GBP and EUR, the additional address fields (holderPostalCode, holderCity, holderStreet) are mandatory.
  • For NGN and CNY, fetch supported banks and their bankCode values from the utility endpoint: /transaction/{method}/providers (replace {method} with BANK_TRANSFER).
  • To perform account name verification for NGN bank transfers, call: /transaction/verify-bank-account.

​
2. MOBILE_MONEY

Typically used for currencies such as GHS, MWK, KES, XOF, UGX, etc. Required fields: accountName, accountNumber, network, providerName, currency, iso2, paymentMethod Notes:
  • The bankCode field must be omitted. The network field is required and must match providerName (e.g., MTN, Airtel, Vodafone).
  • To fetch supported mobile money providers for a specific country, call: /transaction/{method}/providers (replace {method} with MOBILE_MONEY).
  • The response lists all supported provider networks that can be used for both buyerDebitPaymentDetails and buyerCreditPaymentDetails.

​
3. ZELLE

Used for U.S.-based bank transfers via Zelle. Required fields: accountName, email, currency, iso2, paymentMethod Notes:
  • This is an email-based payment method. The email address must belong to a valid Zelle-enabled U.S. bank account.
  • bankCode and network fields should be omitted.

​
4. INTERAC

Used for Canadian email-based transfers via Interac e-Transfer. Required fields: accountName, email, currency, iso2, paymentMethod Notes:
  • This is also an email-based payment method. Only supported for CAD currency.
  • bankCode and network fields should be omitted.

​
5. STABLE_CURRENCY

Used for blockchain-based stablecoin transfers such as USDT, USDC, or BUSD. Required fields: walletAddress, network, currency, iso2, paymentMethod Notes:
  • Valid networks are: TRC20, ERC20, BEP20, SOL, and TON.
  • The currency field must be one of: USDT, USDC, or BUSD. The iso2 field should match the currency field.
  • bankCode, accountName, and email should not be included.
  • For buyerDebitPaymentDetails, the walletAddress is the wallet address you are sending funds from.
  • For the network field: when you initiate the exchange by calling /utility/exchange-rate, the response body contains a paymentDetails object — the network value in that object is the network you should send from.

​
6. ALIPAY

Used for Chinese Yuan (CNY) payments via Alipay. Required fields: accountName, phoneNumber, currency, iso2, paymentMethod Notes:
  • Supported only for CNY currency.
  • phoneNumber represents the user’s Alipay account identifier.
  • bankCode, network, and email fields must be omitted.

​
7. WECHAT_PAY

Used for Chinese Yuan (CNY) payments via WeChat Pay. Required fields: accountName, phoneNumber, currency, iso2, paymentMethod Notes:
  • Supported only for CNY currency.
  • phoneNumber represents the user’s WeChat Pay account identifier.
  • bankCode, network, and email fields must be omitted.

​
Additional Notes

  • These field requirements apply to both buyerDebitPaymentDetails and buyerCreditPaymentDetails.
  • Ensure that payment details align with the selected payment method and currency to enable accurate routing and settlement.
  • Some payment methods and required fields are currency-dependent. Always verify that the selected payment method is valid for the chosen currency.
  • For BANK_TRANSFER and MOBILE_MONEY, always fetch provider data from /transaction/{method}/providers to ensure valid and up-to-date options.
  • Invalid or mismatched field combinations (e.g., providing bankCode for MOBILE_MONEY) will result in validation errors.

​
Request Body

{
  "amount": 500,
  "buyerDebitPaymentMethod": "MOBILE_MONEY",
  "buyerCreditPaymentMethod": "BANK_TRANSFER",
  "buyerCreditPaymentDetails": {
    "accountName": "MONIRATES LIMITED",
    "accountNumber": "0115847370",
    "providerName": "SAFE HAVEN SANDBOX BANK",
    "paymentMethod": "BANK_TRANSFER",
    "iso2": "NG",
    "currency": "NGN",
    "bankCode": "999240"
  },
  "buyerDebitPaymentDetails": {
    "accountName": "MONIRATES LIMITED",
    "accountNumber": "0115847370",
    "providerName": "MTN",
    "paymentMethod": "MOBILE_MONEY",
    "iso2": "GH",
    "currency": "GHS",
    "network": "MTN"
  }
}

​
Response

A successful request returns a PENDING exchange order. The sellerCreditPaymentDetails object contains Monirates’ receiving account — this is where the buyer should send funds. 
{
  "success": true,
  "message": "Processing order",
  "data": {
    "_id": "6a1d57c328131baac7e08d35",
    "globalId": "6f7dec30-5da0-11f1-87a3-c535699deb59",
    "offerId": "68f76957fba0bdb680779e54",
    "buyerGlobalId": "9f39f210-ba45-11f0-b11b-e53d26da86ed",
    "fromCurrency": "NGN",
    "toCurrency": "KES",
    "rate": 0.0870385650474012,
    "fee": 0,
    "amount": 1220,
    "status": "PENDING",
    "buyerDebitPaymentMethod": "BANK_TRANSFER",
    "buyerCreditPaymentMethod": "MOBILE_MONEY",
    "buyerCreditPaymentDetails": {
      "accountName": "Kwame Asamoah",
      "accountNumber": "024555555555555",
      "providerName": "MPESA",
      "network": "MPESA",
      "paymentMethod": "MOBILE_MONEY",
      "iso2": "KE",
      "currency": "KES",
      "isUssdCode": false,
      "_id": "6a1d57c328131baac7e08d36"
    },
    "buyerDebitPaymentDetails": {
      "accountName": "Kwame Asamoah",
      "accountNumber": "024555555555",
      "providerName": "FIRST BANK",
      "bankCode": "999024",
      "paymentMethod": "BANK_TRANSFER",
      "iso2": "NG",
      "currency": "NGN",
      "_id": "6a1d57c328131baac7e08d37"
    },
    "sellerCreditPaymentDetails": {
      "accountName": "MONIRATESLIMITE / JOHN DOE",
      "accountNumber": "8029869754",
      "providerName": "SAFE HAVEN SANDBOX BANK",
      "bankCode": "999240",
      "paymentMethod": "BANK_TRANSFER",
      "iso2": "NG",
      "currency": "NGN",
      "_id": "6a01913a7a6ab126310a083b"
    },
    "source": "BUSINESS",
    "buyerMadePayment": false,
    "hasBuyerPaymentProof": false,
    "buyerPaymentProofUrl": null,
    "paymentReferenceCode": 139683,
    "createdAt": "2026-06-01T09:58:27.249Z",
    "updatedAt": "2026-06-01T09:58:27.249Z"
  }
}

​
Key Response Fields

FieldDescription
_idThe unique ID of the created exchange order.
statusWill be PENDING on creation.
sellerCreditPaymentDetailsMonirates’ receiving account. The buyer must send funds to this account to proceed.
paymentReferenceCodeA reference code for this transaction.
buyerMadePaymentIndicates whether the buyer has confirmed payment. Starts as false.
proceed to the Payment Made guide.