Create an exchange

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.

POST /v1/offer/{offerId}/order

Headers

Header	Required	Description
`idempotencykey`	Yes	A unique value for each exchange you create.

The idempotencykey header is required. Generate a new key for every new exchange. Only reuse a key when retrying the same request after a timeout or network error.

Request Body

The request body requires the following fields:

Field	Required	Description
`amount`	Yes	The amount in the initiating (debit) currency. Conversion into the credit currency is calculated based on current exchange rates and applicable fees.
`buyerDebitPaymentMethod`	Yes	How the user will send funds.
`buyerCreditPaymentMethod`	Yes	How the user will receive funds.
`buyerDebitPaymentDetails`	Conditional	Required unless `buyerDebitPaymentMethod` is `WALLET`.
`buyerCreditPaymentDetails`	Conditional	Required unless `buyerCreditPaymentMethod` is `WALLET`.
`narration`	No	A 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

Each payment method (BANK_TRANSFER, ACH, WIRE, MOBILE_MONEY, ZELLE, INTERAC, STABLE_CURRENCY, ALIPAY and WECHAT_PAY) has its own required fields and rules, and some are limited to specific currencies. See the Supported Payment Methods guide for the full list before building your request.

Request Examples

Every example below needs the idempotencykey header. Replace {offerId} with the _id from your rate response. The payment methods and currencies in the body should match the currency pair of the rate you fetched.

curl --request POST \
  --url https://dev.interface.monirates.com/v1/offer/{offerId}/order \
  --header "Content-Type: application/json" \
  --header "idempotencykey: 7c9e6679-7425-40de-944b-e07fc1f90a02" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --data '{
    "amount": 500,
    "buyerDebitPaymentMethod": "WALLET",
    "buyerCreditPaymentMethod": "BANK_TRANSFER",
    "buyerCreditPaymentDetails": {
      "accountName": "MONIRATES LIMITED",
      "accountNumber": "0115847370",
      "providerName": "SAFE HAVEN SANDBOX BANK",
      "bankCode": "999240",
      "paymentMethod": "BANK_TRANSFER",
      "iso2": "NG",
      "currency": "NGN"
    }
  }'

curl --request POST \
  --url https://dev.interface.monirates.com/v1/offer/{offerId}/order \
  --header "Content-Type: application/json" \
  --header "idempotencykey: 7c9e6679-7425-40de-944b-e07fc1f90a03" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --data '{
    "amount": 500,
    "buyerDebitPaymentMethod": "WALLET",
    "buyerCreditPaymentMethod": "MOBILE_MONEY",
    "buyerCreditPaymentDetails": {
      "accountName": "JOHN DOE",
      "accountNumber": "0541234567",
      "providerName": "MTN",
      "network": "MTN",
      "paymentMethod": "MOBILE_MONEY",
      "iso2": "GH",
      "currency": "GHS"
    }
  }'

curl --request POST \
  --url https://dev.interface.monirates.com/v1/offer/{offerId}/order \
  --header "Content-Type: application/json" \
  --header "idempotencykey: 7c9e6679-7425-40de-944b-e07fc1f90a04" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --data '{
    "amount": 50000,
    "buyerDebitPaymentMethod": "BANK_TRANSFER",
    "buyerCreditPaymentMethod": "MOBILE_MONEY",
    "buyerDebitPaymentDetails": {
      "accountName": "MONIRATES LIMITED",
      "accountNumber": "0115847370",
      "providerName": "SAFE HAVEN SANDBOX BANK",
      "bankCode": "999240",
      "paymentMethod": "BANK_TRANSFER",
      "iso2": "NG",
      "currency": "NGN"
    },
    "buyerCreditPaymentDetails": {
      "accountName": "JOHN DOE",
      "accountNumber": "0541234567",
      "providerName": "MTN",
      "network": "MTN",
      "paymentMethod": "MOBILE_MONEY",
      "iso2": "GH",
      "currency": "GHS"
    }
  }'

curl --request POST \
  --url https://dev.interface.monirates.com/v1/offer/{offerId}/order \
  --header "Content-Type: application/json" \
  --header "idempotencykey: 7c9e6679-7425-40de-944b-e07fc1f90a01" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --data '{
    "amount": 500,
    "buyerDebitPaymentMethod": "WALLET",
    "buyerCreditPaymentMethod": "WALLET",
    "narration": "Wallet to wallet exchange"
  }'

curl --request POST \
  --url https://dev.interface.monirates.com/v1/offer/{offerId}/order \
  --header "Content-Type: application/json" \
  --header "idempotencykey: 7c9e6679-7425-40de-944b-e07fc1f90a05" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --data '{
    "amount": 500,
    "buyerDebitPaymentMethod": "MOBILE_MONEY",
    "buyerCreditPaymentMethod": "BANK_TRANSFER",
    "buyerDebitPaymentDetails": {
      "accountName": "JOHN DOE",
      "accountNumber": "0541234567",
      "providerName": "MTN",
      "network": "MTN",
      "paymentMethod": "MOBILE_MONEY",
      "iso2": "GH",
      "currency": "GHS"
    },
    "buyerCreditPaymentDetails": {
      "accountName": "MONIRATES LIMITED",
      "accountNumber": "0115847370",
      "providerName": "SAFE HAVEN SANDBOX BANK",
      "bankCode": "999240",
      "paymentMethod": "BANK_TRANSFER",
      "iso2": "NG",
      "currency": "NGN"
    }
  }'

curl --request POST \
  --url https://dev.interface.monirates.com/v1/offer/{offerId}/order \
  --header "Content-Type: application/json" \
  --header "idempotencykey: 7c9e6679-7425-40de-944b-e07fc1f90a06" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --data '{
    "amount": 500,
    "buyerDebitPaymentMethod": "WALLET",
    "buyerCreditPaymentMethod": "BANK_TRANSFER",
    "buyerCreditPaymentDetails": {
      "accountName": "JOHN DOE",
      "accountNumber": "12345678",
      "providerName": "040004",
      "bankCode": "040004",
      "paymentMethod": "BANK_TRANSFER",
      "iso2": "GB",
      "currency": "GBP",
      "holderPostalCode": "SW1A 1AA",
      "holderCity": "London",
      "holderStreet": "10 Downing Street"
    }
  }'

curl --request POST \
  --url https://dev.interface.monirates.com/v1/offer/{offerId}/order \
  --header "Content-Type: application/json" \
  --header "idempotencykey: 7c9e6679-7425-40de-944b-e07fc1f90a07" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --data '{
    "amount": 500,
    "buyerDebitPaymentMethod": "WALLET",
    "buyerCreditPaymentMethod": "ACH",
    "buyerCreditPaymentDetails": {
      "accountName": "JOHN DOE",
      "accountNumber": "123456789012",
      "providerName": "123456789",
      "bankCode": "123456789",
      "paymentMethod": "ACH",
      "iso2": "US",
      "currency": "USD"
    }
  }'

curl --request POST \
  --url https://dev.interface.monirates.com/v1/offer/{offerId}/order \
  --header "Content-Type: application/json" \
  --header "idempotencykey: 7c9e6679-7425-40de-944b-e07fc1f90a08" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --data '{
    "amount": 500,
    "buyerDebitPaymentMethod": "WALLET",
    "buyerCreditPaymentMethod": "WIRE",
    "buyerCreditPaymentDetails": {
      "accountName": "JOHN DOE",
      "accountNumber": "123456789012",
      "providerName": "123456789",
      "bankCode": "123456789",
      "paymentMethod": "WIRE",
      "iso2": "US",
      "currency": "USD"
    }
  }'

curl --request POST \
  --url https://dev.interface.monirates.com/v1/offer/{offerId}/order \
  --header "Content-Type: application/json" \
  --header "idempotencykey: 7c9e6679-7425-40de-944b-e07fc1f90a09" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --data '{
    "amount": 500,
    "buyerDebitPaymentMethod": "WALLET",
    "buyerCreditPaymentMethod": "ZELLE",
    "buyerCreditPaymentDetails": {
      "accountName": "JOHN DOE",
      "email": "john.doe@example.com",
      "paymentMethod": "ZELLE",
      "iso2": "US",
      "currency": "USD"
    }
  }'

curl --request POST \
  --url https://dev.interface.monirates.com/v1/offer/{offerId}/order \
  --header "Content-Type: application/json" \
  --header "idempotencykey: 7c9e6679-7425-40de-944b-e07fc1f90a10" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --data '{
    "amount": 500,
    "buyerDebitPaymentMethod": "WALLET",
    "buyerCreditPaymentMethod": "INTERAC",
    "buyerCreditPaymentDetails": {
      "accountName": "JOHN DOE",
      "email": "john.doe@example.com",
      "paymentMethod": "INTERAC",
      "iso2": "CA",
      "currency": "CAD"
    }
  }'

curl --request POST \
  --url https://dev.interface.monirates.com/v1/offer/{offerId}/order \
  --header "Content-Type: application/json" \
  --header "idempotencykey: 7c9e6679-7425-40de-944b-e07fc1f90a11" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --data '{
    "amount": 500,
    "buyerDebitPaymentMethod": "WALLET",
    "buyerCreditPaymentMethod": "STABLE_CURRENCY",
    "buyerCreditPaymentDetails": {
      "walletAddress": "<YOUR_TRC20_WALLET_ADDRESS>",
      "network": "TRC20",
      "paymentMethod": "STABLE_CURRENCY",
      "iso2": "USDT",
      "currency": "USDT"
    }
  }'

curl --request POST \
  --url https://dev.interface.monirates.com/v1/offer/{offerId}/order \
  --header "Content-Type: application/json" \
  --header "idempotencykey: 7c9e6679-7425-40de-944b-e07fc1f90a12" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --data '{
    "amount": 500,
    "buyerDebitPaymentMethod": "BANK_TRANSFER",
    "buyerCreditPaymentMethod": "STABLE_CURRENCY",
    "buyerDebitPaymentDetails": {
      "accountName": "MONIRATES LIMITED",
      "accountNumber": "0115847370",
      "providerName": "SAFE HAVEN SANDBOX BANK",
      "bankCode": "999240",
      "paymentMethod": "BANK_TRANSFER",
      "iso2": "NG",
      "currency": "NGN"
    },
    "buyerCreditPaymentDetails": {
      "walletAddress": "<YOUR_SENDING_WALLET_ADDRESS>",
      "network": "TRC20",
      "paymentMethod": "STABLE_CURRENCY",
      "iso2": "USDT",
      "currency": "USDT"
    }
  }'

curl --request POST \
  --url https://dev.interface.monirates.com/v1/offer/{offerId}/order \
  --header "Content-Type: application/json" \
  --header "idempotencykey: 7c9e6679-7425-40de-944b-e07fc1f90a13" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --data '{
    "amount": 500,
    "buyerDebitPaymentMethod": "WALLET",
    "buyerCreditPaymentMethod": "ALIPAY",
    "buyerCreditPaymentDetails": {
      "accountName": "ZHANG WEI",
      "phoneNumber": "8613800138000",
      "paymentMethod": "ALIPAY",
      "iso2": "CN",
      "currency": "CNY"
    }
  }'

curl --request POST \
  --url https://dev.interface.monirates.com/v1/offer/{offerId}/order \
  --header "Content-Type: application/json" \
  --header "idempotencykey: 7c9e6679-7425-40de-944b-e07fc1f90a14" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --data '{
    "amount": 500,
    "buyerDebitPaymentMethod": "WALLET",
    "buyerCreditPaymentMethod": "WECHAT_PAY",
    "buyerCreditPaymentDetails": {
      "accountName": "ZHANG WEI",
      "phoneNumber": "8613800138000",
      "paymentMethod": "WECHAT_PAY",
      "iso2": "CN",
      "currency": "CNY"
    }
  }'

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

Field	Description
`_id`	The unique ID of the created exchange order.
`status`	Will be `PENDING` on creation.
`sellerCreditPaymentDetails`	Monirates’ receiving account. The buyer must send funds to this account to proceed.
`paymentReferenceCode`	A reference code for this transaction.
`buyerMadePayment`	Indicates whether the buyer has confirmed payment. Starts as `false`.

proceed to the Payment Made guide.

Exchange

Payment links

Wallet

Stable Wallet

Quick Reference

Create an exchange

Initiate Exchange

Headers

Request Body

Supported Payment Methods

Request Examples

Response

Key Response Fields

​Initiate Exchange

​Headers

​Request Body

​Supported Payment Methods

​Request Examples

​Response

​Key Response Fields

Initiate Exchange

Headers

Request Body

Supported Payment Methods

Request Examples

Response

Key Response Fields