Amounts and pricing#

A session can carry a deposit, a rent payment, and a CasaPay fee. Understanding which of them the tenant actually pays now is the most common source of integration bugs.

The fields#

Field	What it is
`cover_amount`	The deposit. Either paid in cash by the tenant or guaranteed by CasaPay.
`first_payment_amount`	Rent charged at checkout.
`subscription_fee`	Monthly CasaPay fee, charged only when the deposit is guaranteed.
`total_amount`	What the tenant is charged now.
`amount`	Legacy single amount. Prefer `first_payment_amount`.

How total_amount is derived#

total_amount is not the sum of every field. It is the cash due at checkout:

Deposit mode	total_amount
`deposit_upfront`	`cover_amount` + `first_payment_amount`
`deposit_guaranteed`	`first_payment_amount` + `subscription_fee`
`choice`	`first_payment_amount` only, until the tenant decides
No deposit	`first_payment_amount` (or `amount`)

A guaranteed deposit is never charged at checkout

Under deposit_guaranteed CasaPay covers the deposit and the tenant pays a recurring fee instead. Adding cover_amount into your own total will overstate the charge.

Validation rules#

Rule	Consequence if broken
One of `amount`, `cover_amount`, `first_payment_amount` required	422, session charges nothing
`deposit_mode` required when `cover_amount` is above 0	422
`payment_link` cannot carry `cover_amount`	422
`cover_amount` max 15000 on sessions and pricing preview	422
`first_payment_amount` min 0.01	422

A cover_amount of exactly 0 is valid - it means a guarantee agreement with no deposit required.

Payment method fees#

Your entity can be configured with per-payment-method fees, applied automatically when a tenant pays through a payment link:

A CasaPay transaction fee is added on top of the invoice as its own line. The tenant pays it; it is not passed to you.
An operator take rate is deducted from your payout and billed back on your operator billing period.

When configured, the fee for each method is returned alongside the available payment methods so the checkout can show the surcharge before the tenant commits.

Preview pricing

POST/api/v1/gateway/pricing-preview

Returns the exact fee breakdown for a prospective session, so you can show the tenant both deposit options before creating anything. Creates no records.

Body

cover_amountnumberREQUIRED

Deposit or guarantee amount. 0 to 15000.

first_payment_amountnumber

Rent charged now. 0 to 999999.99.

currencyenum

EUR, GBP, USD or CAD.

curl -X POST https://manage.casapay.com/api/v1/gateway/pricing-preview \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{ "cover_amount": 800, "first_payment_amount": 650, "currency": "EUR" }'

{
  "cover_amount": 800.0,
  "currency": "EUR",
  "deposit_options": [
    {
      "mode": "deposit_upfront",
      "deposit_amount": 800.0,
      "first_payment_amount": 650.0,
      "due_today": 1450.0,
      "subscription_fee": 0.0,
      "subscription": null
    },
    {
      "mode": "deposit_guaranteed",
      "deposit_amount": 0.0,
      "first_payment_amount": 650.0,
      "subscription_fee": 16.0,
      "subscription_fee_rate": 2.0,
      "due_today": 666.0,
      "subscription": {
        "monthly_amount": 16.0,
        "annual_amount": 192.0,
        "coverage_amount": 800.0
      }
    }
  ]
}