Define Fees

Fee Matrix Definition

This is how you will define fees for your merchants.

• _rate: variable fee as a percentage of the amount
• _fixed: flat fee added per transaction
• _cap: upper limit on the rated (percentage) portion per transaction

Field	Required?	Example	Description
tax_inclusive	Optional	false	Whether the fee values already include the 15% VAT. Default: false.
mada_charge_rate	✅	1.70	Charge rate (%) for mada.
mada_charge_fixed	✅	1.00	Fixed charge fee for mada.
mada_charge_cap	Optional	200.00	Charge cap for mada. Should always be 200.00 SAR.
mada_refund_rate	Optional	0.00	Refund rate (%) for mada.
mada_refund_fixed	✅	1.00	Fixed refund fee for mada.
mada_refund_cap	Optional	0.00	Refund cap for mada.
cc_charge_rate	✅	2.70	Charge rate (%) for local Credit Card transactions.
cc_charge_fixed	✅	1.00	Fixed charge fee for local Credit Card transactions.
cc_charge_cap	Optional	0.00	Charge cap for local Credit Card transactions.
cc_refund_rate	Optional	0.00	Refund rate (%) for local Credit Card transactions.
cc_refund_fixed	✅	1.00	Fixed refund fee for local Credit Card transactions.
cc_refund_cap	Optional	0.00	Refund cap for local Credit Card transactions.
cc_int_charge_rate	Optional	2.90	Charge rate (%) for international Credit Card transactions (non-SA cards).
cc_int_charge_fixed	Optional	1.00	Fixed charge fee for international Credit Card transactions.
cc_int_charge_cap	Optional	0.00	Charge cap for international Credit Card transactions.
cc_int_refund_rate	Optional	0.00	Refund rate (%) for international Credit Card transactions.
cc_int_refund_fixed	Optional	1.00	Fixed refund fee for international Credit Card transactions.
cc_int_refund_cap	Optional	0.00	Refund cap for international Credit Card transactions.
stcpay_charge_rate	✅ when stcpay is enabled	1.00	Charge rate (%) for STC Pay.
stcpay_charge_fixed	✅ when stcpay is enabled	0.00	Fixed charge fee for STC Pay.
stcpay_charge_cap	Optional	0.00	Charge cap for STC Pay.
stcpay_refund_rate	Optional	0.00	Refund rate (%) for STC Pay.
stcpay_refund_fixed	✅ when stcpay is enabled	0.00	Fixed refund fee for STC Pay.
stcpay_refund_cap	Optional	0.00	Refund cap for STC Pay.
amex_charge_rate	Optional	2.75	Charge rate (%) for local American Express.
amex_charge_fixed	Optional	1.00	Fixed charge fee for local American Express.
amex_charge_cap	Optional	0.00	Charge cap for local American Express.
amex_refund_rate	Optional	0.00	Refund rate (%) for local American Express.
amex_refund_fixed	Optional	1.00	Fixed refund fee for local American Express.
amex_refund_cap	Optional	0.00	Refund cap for local American Express.
amex_int_charge_rate	Optional	2.90	Charge rate (%) for international American Express (non-SA cards).
amex_int_charge_fixed	Optional	1.00	Fixed charge fee for international American Express.
amex_int_charge_cap	Optional	0.00	Charge cap for international American Express.
amex_int_refund_rate	Optional	0.00	Refund rate (%) for international American Express.
amex_int_refund_fixed	Optional	1.00	Fixed refund fee for international American Express.
amex_int_refund_cap	Optional	0.00	Refund cap for international American Express.
settle_transfer_rate	Optional	0.00	Variable rate (%) applied on settlement transfers. Default: 0.
settle_transfer_fixed	Optional	0.00	Fixed fee applied on settlement transfers. Default: 0.

Fee Calculation

Let us take an example of SAR148.00 and see how fees are calculated for credit card according to the table above:

• Calculate: 148.00 * (2.7 / 100) = 3.996
• We will do a Half-Up Rounding and get 4.00
• If a cap is defined for this fee, the rated portion is limited to that cap (i.e. we take the smaller of the rated fee and the cap)
• Now we add the fixed fee of SAR1.00 and get 5.00
• If tax_inclusive is true, then we are done and our final fee is SAR5.00
• If tax_inclusive is false, then we need to get our tax by 5.00 * (15 / 100) = 0.75 and a final fee of 5.75

Update Merchant Fees

Fees can be updated using the same merchant update endpoint:

PUT /v1/merchants/88df1418-0290-4563-95c9-4a48eb03987a HTTP/1.1
Host: apimig.moyasar.com
Authorization: Basic <your_api_key_as_basic_base64>
Content-Type: application/json

{
    "fees": {
        "tax_inclusive": true,
        "mada_charge_rate": 1.7,
        "mada_charge_fixed": 1.0,
        "mada_refund_rate": 0.0,
        "mada_refund_fixed": 1.0,
        "cc_charge_rate": 2.7,
        "cc_charge_fixed": 1.0,
        "cc_refund_rate": 0.0,
        "cc_refund_fixed": 1.0
    }
}