Skip to main content
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.
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:
ParameterValue
fromCurrencyNGN
fromCurrencyIso2NG
toCurrencyGHS
toCurrencyIso2GH
amount200

​
Response

{
  "success": true,
  "data": {
    "displayAmount": "123.84",
    "orderAmount": 123.83216789,
    "offerId": "67d830049d46873b7891dd0f"
  },
  "message": "payment link rate fetched successfully"
}
FieldDescription
displayAmountFormatted amount for UI display only. Do not use this for the exchange request.
orderAmountThe exact amount to pass as amount when creating the exchange. Use the full value.
offerIdRequired 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

FieldRequiredDescription
amountYesThe full orderAmount from the rate response.
buyerDebitPaymentMethodYesHow the payer will send funds.
buyerCreditPaymentMethodYesHow the receiver will receive funds.
buyerDebitPaymentDetailsYesPayment details for the payer. Must match the selected debit payment method.
buyerCreditPaymentDetailsYesPayment 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.