Agreements#

A payment agreement links a tenant to your entity. Every gateway payment belongs to one. You can let the first session create it implicitly, or create it up front with the endpoints below.

The agreement object#

Attribute	Type	Description
`id`	integer	Numeric ID. Use this in URLs.
`agreement_id`	string	UUID, stable across systems.
`agreement_type`	enum	`payment_link`, `ontime` or `cover`.
`status`	enum	`active`, `paused`, `completed`, `cancelled`, `draft`.
`email_alias`	string	Forward invoice PDFs here to bill the tenant automatically.
`cover_amount`	number	Guarantee amount. `null` for payment links.
`currency`	enum	`EUR`, `GBP`, `USD`, `CAD`.
`tenant`	object	`id` and `email` of the tenant.

Agreement types#

Type	Guarantee	Operator payout
`payment_link`	None	On settlement of the tenant payment.
`ontime`	Yes	On the invoice due date.
`cover`	Yes	Due date plus 30 days.

Both guarantee types need a cover_amount. See Deposits and guarantees.

Create an agreement

POST/api/v1/gateway/agreements

Creates a payment agreement without a checkout session. Use this when you want the tenant relationship first and will bill later - by API, or by emailing invoice PDFs to the returned email_alias.

Body

tenant.emailstringREQUIRED

Tenant email. Max 255.

tenant.first_namestringREQUIRED

Max 255.

tenant.last_namestringREQUIRED

Max 255.

tenant.phonestring

Max 50.

tenant.personal_codestring

National ID. Max 50.

agreement_typeenumREQUIRED

payment_link, ontime or cover.

cover_amountnumber

Guarantee amount. 0 to 999999.99. Not allowed for payment_link.

currencyenum

EUR, GBP, USD or CAD.

descriptionstring

Agreement title. Max 1000.

curl -X POST https://manage.casapay.com/api/v1/gateway/agreements \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "tenant": {
      "email": "tenant@example.com",
      "first_name": "Mari",
      "last_name": "Tamm"
    },
    "agreement_type": "ontime",
    "cover_amount": 800,
    "currency": "EUR",
    "description": "Tartu mnt 12, apt 4B"
  }'

Returns 201:

{
  "id": 4821,
  "agreement_id": "9f2c1e84-3b7a-4d6f-8e21-5c0a9b7d1234",
  "agreement_type": "ontime",
  "status": "active",
  "email_alias": "mari.tamm.4821@invoice.casapay.com",
  "currency": "EUR",
  "cover_amount": 800.0,
  "description": "Tartu mnt 12, apt 4B",
  "tenant": {
    "id": 1152,
    "email": "tenant@example.com"
  }
}

Email alias invoicing

Forward a supplier or rent invoice PDF to email_alias and CasaPay parses it, creates the invoice, and emails the tenant a checkout link automatically. No API call needed.

Create agreements in bulk

POST/api/v1/gateway/agreements/batch

Creates many agreements in one request. Each entry follows the same rules as a single create; the response reports per-entry success so a partial failure does not lose the successful rows.

List agreements

GET/api/v1/gateway/agreements

Returns agreements for your entity, newest first.

Query

statusenum

active, paused, completed, cancelled or draft.

per_pageinteger

1 to 200. Defaults to 50.

pageinteger

Page number, from 1.

Retrieve an agreement

GET/api/v1/gateway/agreements/{id}

Returns one agreement with its tenant and current status. Agreements owned by another entity return 404 AGREEMENT_NOT_FOUND.

List agreement invoices

GET/api/v1/gateway/agreements/{id}/invoices

Returns invoices raised against the agreement, including payment and payout state.

Query

statusenum

paid, partial, unpaid, cancelled or rejected.

payout_statusenum

created, pending, in_disbursement, settled, failed or cancelled.

per_pageinteger

1 to 200. Defaults to 50.

pageinteger

Page number, from 1.