Create Exchange from Payment Link

When a payer opens a payment link, they need to calculate how much they will send in their own currency, then create an exchange. This is a two-step process: fetch the rate first, then create the exchange.

Step 1: Fetch the Payment Link Rate

Endpoint: GET /utility/payment-link-rate This endpoint calculates the equivalent amount in the payer’s currency for a given payment link. The amount parameter should be set to the payment link’s original amount.

toCurrency and toCurrencyIso2 represent the currency and ISO2 code of the payment link (the receiver’s currency).
fromCurrency and fromCurrencyIso2 represent the payer’s currency and ISO2 code.

Example: A payment link is created for 200 GHS by a receiver in Ghana. The payer is in Nigeria using NGN. The request parameters would be:

Parameter	Value
`fromCurrency`	`NGN`
`fromCurrencyIso2`	`NG`
`toCurrency`	`GHS`
`toCurrencyIso2`	`GH`
`amount`	`200`

Response

{
  "success": true,
  "data": {
    "displayAmount": "123.84",
    "orderAmount": 123.83216789,
    "offerId": "67d830049d46873b7891dd0f"
  },
  "message": "payment link rate fetched successfully"
}

Field	Description
`displayAmount`	Formatted amount for UI display only. Do not use this for the exchange request.
`orderAmount`	The exact amount to pass as `amount` when creating the exchange. Use the full value.
`offerId`	Required when creating the exchange. Pass this as the `offerId` path parameter.

Step 2: Create the Exchange

Endpoint: POST /offer/{offerId}/payment-request/order Use the offerId from the rate response as the path parameter and the full orderAmount as the amount field in the request body. The buyerCreditPaymentDetails should be automatically mapped from the receiver’s payout configuration returned when the payment link was retrieved via /payment-link/pay — including currency, currencyIso2, and payment details. This ensures the receiver’s payout method stays consistent with the original payment link setup. The buyerDebitPaymentDetails must be provided by the payer and should include all required fields for their chosen payment method. Refer to the Supported Payment Methods guide for the required fields per payment method.

Request Body

{
  "amount": 123.83216789,
  "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"
  }
}

Fields

Field	Required	Description
`amount`	Yes	The full `orderAmount` from the rate response.
`buyerDebitPaymentMethod`	Yes	How the payer will send funds.
`buyerCreditPaymentMethod`	Yes	How the receiver will receive funds.
`buyerDebitPaymentDetails`	Yes	Payment details for the payer. Must match the selected debit payment method.
`buyerCreditPaymentDetails`	Yes	Payment details for the receiver. Mapped from the payment link’s payout configuration.

Step 3: Confirm Payment

Once the exchange is successfully created, call the buyer paid endpoint to notify the system that payment has been made. Endpoint: POST /order/{orderId}/payment-request/buyer-paid The orderId is the _id from the exchange creation response. See the Payment Made guide for how to structure the request body based on the debit payment method used.

Exchange

Wallet

Payment links

Quick Reference

Create Exchange from Payment Link

Step 1: Fetch the Payment Link Rate

Response

Step 2: Create the Exchange

Request Body

Fields

Step 3: Confirm Payment

​Step 1: Fetch the Payment Link Rate

​Response

​Step 2: Create the Exchange

​Request Body

​Fields

​Step 3: Confirm Payment

Step 1: Fetch the Payment Link Rate

Response

Step 2: Create the Exchange

Request Body

Fields

Step 3: Confirm Payment