Money and fees

How amounts are written, and how fees are quoted and charged.

Amounts

Money is a decimal string in major units. Write "120.00" for one hundred and twenty cedis. Do not send numbers, and do not send pesewas.

{ "amount": "120.00", "currency": "GHS" }

Keep amounts as strings or as a decimal type in your code. Binary floating point can turn 0.10 into 0.1000000000000000055.

Fee quotes

Ask for the fee before you create a payment:

• GET /v1/fee-quotes/collections
• GET /v1/fee-quotes/payouts

Send the same provider you will use on the payment, plus amount, currency and partyType (msisdn, account or card). A quote holds nothing. The real request prices again when it runs.

{
  "amount": "120.00",
  "currency": "GHS",
  "fee": "1.20",
  "feeBearer": "initiator",
  "payerAmount": "121.20",
  "recipientAmount": "120.00"
}

The values above only show the shape.

Who pays the fee

feeBearer says who carries the fee.

• When the initiator bears the fee, the payer pays the amount plus the fee. The recipient gets the amount.
• When the other side bears the fee, the payer pays the amount. The recipient gets the amount minus the fee.

Your business has one configured fee bearer. You cannot set it per request.

Collection and payout responses carry the same fields, so you can record what was charged.

When fees change

A fee increase takes effect at least 30 days after it’s approved, as the iSmartPay merchant terms require. Your business’s owner is told by SMS and email when it’s approved, with the current rate, the new rate and the date. Until that date you keep paying the current rate.

A fee that goes down can take effect at once.

A quote always prices with the fee in force when you ask, so a quote taken before the change shows the old fee.