Aggregated Collection#

Aggregated collection is CasaPay's turnkey solution for rent collection. Instead of integrating individual payment methods (cards, open banking, direct debit) via PaymentIntents, you send a single payment request and CasaPay handles the entire flow — method selection, mandate setup, collection, retries, and failure handling.

How it works#

Create a PaymentAgreement — Onboard a tenant with a single API call. CasaPay generates an onboarding_url for the tenant to set up their preferred payment method.
Tenant completes onboarding — The tenant visits the onboarding URL, selects a payment method (card, open banking, or direct debit), and authorises future payments. CasaPay handles mandate creation if needed.
Create PaymentRequests — When rent is due, create a PaymentRequest against the agreement. You can also bulk-create requests for an entire rent run.
CasaPay handles collection — CasaPay charges the tenant's preferred method, falls back to alternatives if configured, and retries on transient failures.
Receive webhook results — Get notified via webhooks when payments succeed, fail, or require attention.

Custom vs Aggregated

Custom collection (PaymentIntents, Mandates, etc.) gives you full control over payment routing, method selection, and retry logic — ideal for operators with complex payment orchestration needs.

Aggregated collection (PaymentAgreements + PaymentRequests) abstracts all of that away — ideal for operators who want to send a single request and let CasaPay handle everything. Both options live under Payments — Collection and can be used together.

The PaymentAgreement object#

A PaymentAgreement represents a tenant's onboarding into aggregated collection. It holds the tenant's payment method preferences and authorisation state.

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 set up
`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
}

Create a PaymentAgreement#

Creates a new PaymentAgreement and generates an onboarding URL for the tenant.

POST/v1/payment_agreements

Parameters#

tenantstringREQUIRED

The tenant/customer ID.

entitystringREQUIRED

The operator entity ID.

payment_methods_availablearray

Payment methods to offer the tenant. Defaults to all methods enabled on the entity.

metadatahash

Set of key-value pairs for additional information.

Response#

Returns the PaymentAgreement object with status: "pending_onboarding" and an onboarding_url.

curl https://api.casapay.com/v1/payment_agreements \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant": "cus_123456789",
    "entity": "ent_456def",
    "payment_methods_available": ["card", "open_banking", "direct_debit"],
    "metadata": {
      "property_id": "prop_456",
      "unit": "4B"
    }
  }'

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

Retrieve a PaymentAgreement#

Retrieves the details of an existing PaymentAgreement.

GET/v1/payment_agreements/:id

Parameters#

idstringREQUIRED

The PaymentAgreement ID.

curl https://api.casapay.com/v1/payment_agreements/pa_abc123 \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

List PaymentAgreements#

Returns a list of PaymentAgreements. Sorted by creation date, newest first.

GET/v1/payment_agreements

Parameters#

tenantstring

Filter by tenant/customer ID.

entitystring

Filter by operator entity ID.

statusstring

Filter by status: pending_onboarding, active, suspended, or cancelled.

limitinteger

Maximum number of objects to return. Default is 10, maximum is 100.

starting_afterstring

Cursor for pagination. Pass the ID of the last object from the previous page.

curl "https://api.casapay.com/v1/payment_agreements?entity=ent_456def&status=active&limit=20" \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

Update a PaymentAgreement#

Updates the specified PaymentAgreement.

POST/v1/payment_agreements/:id

Parameters#

payment_methods_availablearray

Update the methods available to the tenant.

metadatahash

Update key-value pairs.

curl https://api.casapay.com/v1/payment_agreements/pa_abc123 \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_methods_available": ["card", "direct_debit"]
  }'

Cancel a PaymentAgreement#

Cancels a PaymentAgreement. Any pending PaymentRequests against this agreement will also be cancelled.

POST/v1/payment_agreements/:id/cancel

Parameters#

idstringREQUIRED

The PaymentAgreement ID.

curl -X POST https://api.casapay.com/v1/payment_agreements/pa_abc123/cancel \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"