Payment Agreements#

A PaymentAgreement represents a tenant's enrolment in CasaPay's aggregated collection. It holds their payment method preferences, onboarding state, and mandate authorisation. Once active, you can create PaymentRequests against the agreement to collect rent.

The PaymentAgreement object#

Attribute	Type	Description
`id`	string	Unique identifier with `pa_` prefix
`object`	string	Always `"payment_agreement"`
`tenant`	string	Associated tenant/customer ID
`entity`	string	Operator entity ID
`status`	enum	`pending_onboarding`, `active`, `suspended`, `cancelled`
`onboarding_url`	string	URL for the tenant to complete payment method setup
`payment_methods_available`	array	Methods available to the tenant (e.g., `["card", "open_banking", "direct_debit"]`)
`preferred_method`	string	The tenant's selected preferred payment method
`mandate`	string	Associated Mandate ID (if direct debit is the preferred or fallback method)
`metadata`	hash	Key-value pairs
`created`	timestamp	Time at which the agreement was created
`livemode`	boolean	Whether this is a live mode object

{
  "id": "pa_abc123",
  "object": "payment_agreement",
  "tenant": "cus_123456789",
  "entity": "ent_456def",
  "status": "active",
  "onboarding_url": "https://pay.casapay.com/onboard/pa_abc123",
  "payment_methods_available": ["card", "open_banking", "direct_debit"],
  "preferred_method": "direct_debit",
  "mandate": "md_xyz789",
  "metadata": {
    "property_id": "prop_456",
    "unit": "4B"
  },
  "created": 1706140800,
  "livemode": true
}

Statuses#

Status	Description
`pending_onboarding`	Agreement created, tenant has not yet completed onboarding
`active`	Tenant has completed onboarding and payments can be collected
`suspended`	Agreement temporarily suspended (e.g., mandate failed, payment method expired)
`cancelled`	Agreement permanently cancelled

Tenant onboarding flow#

When you create a PaymentAgreement, CasaPay generates a unique onboarding_url. The tenant visits this URL to:

View available payment methods — Based on the payment_methods_available you configured
Select a preferred method — Card, open banking, or direct debit
Authorise payments — Enter card details, complete bank authorisation, or sign a direct debit mandate
Confirm — The agreement moves to active and you receive a payment_agreement.activated webhook

Onboarding URL expiry

The onboarding URL expires after 7 days. If the tenant hasn't completed onboarding, create a new agreement or contact CasaPay support to generate a fresh URL.

Sending the onboarding link#

CasaPay does not automatically email the onboarding URL to the tenant. You should send it via your own communication channel (email, SMS, in-app notification) or embed it in your tenant portal.

# After creating a PaymentAgreement, send the onboarding_url to the tenant
# Example: retrieve the agreement and use the onboarding_url
curl https://api.casapay.com/v1/payment_agreements/pa_abc123 \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

{
  "id": "pa_abc123",
  "status": "pending_onboarding",
  "onboarding_url": "https://pay.casapay.com/onboard/pa_abc123",
  "payment_methods_available": ["card", "open_banking", "direct_debit"]
}

Method priority and fallback#

When a PaymentRequest is created against an active agreement, CasaPay charges the tenant's preferred_method first. If that fails, CasaPay falls back to other authorised methods in the following priority order:

Direct debit — Lowest cost, highest success rate for recurring payments
Open banking — Real-time bank transfers
Card — Highest cost but most universally available

You can control which methods are available by setting payment_methods_available when creating or updating the agreement. The tenant can only select from the methods you allow.

Suspended agreements

If a tenant's preferred method fails permanently (e.g., mandate cancelled, card expired), the agreement moves to suspended. CasaPay sends a payment_agreement.suspended webhook. To reactivate, the tenant must complete onboarding again via a new onboarding_url.

Mandate handling#

When a tenant selects direct debit during onboarding, CasaPay automatically creates a Mandate (BACS, SEPA, or ACH depending on the entity's region). The mandate ID is stored on the agreement's mandate field.

You don't need to interact with the Mandate directly — CasaPay manages the full lifecycle. However, if you need mandate details (e.g., for compliance), you can retrieve it via the Mandates API using the ID from the agreement.