Buyer-paid payment fee

Project setting

In Settings → Project → Payment fee, the project owner can include the BramaPay service fee in the buyer's payment. It is OFF by default, independently for Live and Test. API keys cannot change this setting. No setting in the shop is required.

The setting applies only when a new invoice or session is created. Its policy version, weekly rate, amount and expiry are fixed at issuance. Existing invoices, retries and additional routes keep their original terms. Changing the setting does not reprice historical payments.

For an order worth $20 at a quoted rate of 1%, the payable basis is 20.202021, before the separate unique routing adjustment. The fee is charged on this increased basis; simply adding 1% would not fully cover it. Checkout shows order value and the exact amount to transfer, without a separate fee line. Always send the exact displayed amount. The address-only QR does not encode an amount.

Existing shop integrations

Normal requests keep their existing body and idempotency key. When the project setting is ON, BramaPay pins PROJECT_BUYER_FEE_V1. Existing session/invoice amountUsd, attempt/invoice requestedAmount, and session paid webhook amountUsd retain the original order value. Additive payableAmountUsd and pricing describe the increased basis. Transfer amounts, receipts, amountExpected and amountPaid remain the actual exact amount. Fulfill or credit the original order value once; verify the signed event against an authenticated GET. A return URL does not prove payment.

The unique routing adjustment is separate from the service fee. It never increases the store balance credit. Server accounting and service fee calculation use the increased basis. Buyer payment does not top up the merchant's service balance or bypass suspension.

Explicit API opt-in compatibility

The previously introduced BUYER_FEE_V1 remains supported: send feePayer: "BUYER", pricingVersion: "BUYER_FEE_V1" and baseAmountUsd, omitting the normal amount field. In that explicit contract, amountUsd remains the increased payable basis. Its existing immutable quotes are unchanged. Do not confuse the two versioned contracts.

An explicit MERCHANT request does not override an enabled project policy. A replay uses its original decision even after the setting changes. On an uncertain response, reuse the original body and idempotency key.

Test uses simulated 1% pricing and cannot create Live fees, quotes or volume. Errors, late payments, duplicates and overpayments retain the existing support policy; no automatic refunds or extra store credits are introduced.