Mandates#

Mandates represent authorization from a tenant to collect payments via Direct Debit. CasaPay supports BACS (UK), SEPA (EU), and ACH (US) mandate schemes.

The Mandate object#

Attribute	Type	Description
`id`	string	Unique identifier with `md_` prefix
`object`	string	Always `"mandate"`
`customer`	string	Customer ID
`payment_method`	string	Associated Payment Method ID
`status`	enum	`pending_submission`, `submitted`, `active`, `cancelled`, `expired`, `failed`
`scheme`	enum	`bacs`, `sepa`, `ach`
`reference`	string	Unique mandate reference
`next_possible_charge_date`	string	Earliest date a charge can be created (YYYY-MM-DD)
`creditor_identifier`	string	Your creditor ID for the scheme
`metadata`	hash	Key-value pairs
`created`	timestamp	Time at which the object was created

Status Flow#

pending_submission → submitted → active → cancelled / expired / failed

{
  "id": "md_abc123",
  "object": "mandate",
  "customer": "cus_123456789",
  "payment_method": "pm_dd_sepa",
  "status": "active",
  "scheme": "sepa",
  "reference": "CASAPAY-MD-ABC123",
  "next_possible_charge_date": "2025-02-03",
  "creditor_identifier": "DE98ZZZ09999999999",
  "metadata": {
    "property_id": "prop_456"
  },
  "created": 1706140800
}

Create a Mandate#

POST /v1/mandates

Parameter	Type	Required	Description
`customer`	string	Yes	Customer ID
`scheme`	string	Yes	Direct debit scheme: `bacs`, `sepa`, `ach`
`account_holder_name`	string	Yes	Name on the bank account
`account_number`	string	Conditional	Bank account number (BACS/ACH)
`sort_code`	string	Conditional	Sort code (BACS)
`iban`	string	Conditional	IBAN (SEPA)
`routing_number`	string	Conditional	Routing number (ACH)
`metadata`	hash	No	Key-value pairs

curl https://api.casapay.com/v1/mandates \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_123456789",
    "scheme": "sepa",
    "account_holder_name": "Jane Doe",
    "iban": "DE89370400440532013000"
  }'

{
  "id": "md_abc123",
  "object": "mandate",
  "status": "pending_submission",
  "scheme": "sepa",
  "reference": "CASAPAY-MD-ABC123",
  "next_possible_charge_date": "2025-02-03",
  "created": 1706140800
}

Retrieve a Mandate#

GET /v1/mandates/:id

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

Update a Mandate#

POST /v1/mandates/:id

curl https://api.casapay.com/v1/mandates/md_abc123 \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"lease_id": "lease_789"}}'

List Mandates#

GET /v1/mandates

Parameter	Type	Description
`customer`	string	Filter by customer
`scheme`	string	Filter by scheme
`status`	string	Filter by status
`limit`	integer	Number of objects (1–100)

curl "https://api.casapay.com/v1/mandates?customer=cus_123456789&status=active" \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

Cancel a Mandate#

POST /v1/mandates/:id/cancel

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

Reinstate a Mandate#

Reinstates a cancelled mandate if the scheme allows it.

POST /v1/mandates/:id/reinstate

curl -X POST https://api.casapay.com/v1/mandates/md_abc123/reinstate \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"