Payment Requests#

A PaymentRequest represents a single collection attempt against a PaymentAgreement. When rent is due, create a PaymentRequest and CasaPay handles charging the tenant's preferred method, retries, and fallback logic.

The PaymentRequest object#

Attribute	Type	Description
`id`	string	Unique identifier with `preq_` prefix
`object`	string	Always `"payment_request"`
`payment_agreement`	string	The PaymentAgreement ID this request is charged against
`amount`	integer	Amount in the smallest currency unit (e.g., cents)
`currency`	string	Three-letter ISO 4217 currency code
`description`	string	Description shown to the tenant (e.g., "Rent — March 2025")
`status`	enum	`pending`, `processing`, `succeeded`, `failed`, `cancelled`
`payment_method_used`	string	The payment method that was charged (populated after processing)
`failure_reason`	string	Reason for failure if `status` is `failed`
`attempts`	integer	Number of collection attempts made
`next_retry_at`	timestamp	When the next retry will occur (if applicable)
`metadata`	hash	Key-value pairs
`created`	timestamp	Time at which the request was created
`livemode`	boolean	Whether this is a live mode object

{
  "id": "preq_abc123",
  "object": "payment_request",
  "payment_agreement": "pa_abc123",
  "amount": 120000,
  "currency": "eur",
  "description": "Rent — March 2025",
  "status": "succeeded",
  "payment_method_used": "direct_debit",
  "failure_reason": null,
  "attempts": 1,
  "next_retry_at": null,
  "metadata": {
    "property_id": "prop_456",
    "period": "2025-03"
  },
  "created": 1709251200,
  "livemode": true
}

Create a PaymentRequest#

Creates a new PaymentRequest against an active PaymentAgreement. CasaPay will begin collection immediately.

POST/v1/payment_requests

Parameters#

payment_agreementstringREQUIRED

The PaymentAgreement ID to charge against.

amountintegerREQUIRED

Amount in the smallest currency unit.

currencystringREQUIRED

Three-letter ISO 4217 currency code.

descriptionstring

Description shown to the tenant.

metadatahash

Set of key-value pairs for additional information.

Response#

Returns the PaymentRequest object with status: "pending".

curl https://api.casapay.com/v1/payment_requests \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_agreement": "pa_abc123",
    "amount": 120000,
    "currency": "eur",
    "description": "Rent — March 2025",
    "metadata": {
      "property_id": "prop_456",
      "period": "2025-03"
    }
  }'

{
  "id": "preq_abc123",
  "object": "payment_request",
  "payment_agreement": "pa_abc123",
  "amount": 120000,
  "currency": "eur",
  "description": "Rent — March 2025",
  "status": "pending",
  "payment_method_used": null,
  "failure_reason": null,
  "attempts": 0,
  "next_retry_at": null,
  "metadata": {
    "property_id": "prop_456",
    "period": "2025-03"
  },
  "created": 1709251200,
  "livemode": false
}

Bulk Create PaymentRequests#

Creates multiple PaymentRequests in a single API call. Useful for recurring rent runs where you need to charge multiple tenants at once.

POST/v1/payment_requests/bulk

Parameters#

requestsarrayREQUIRED

Array of PaymentRequest creation objects, each containing payment_agreement, amount, currency, and optionally description and metadata.

Response#

Returns a list of created PaymentRequest objects.

curl https://api.casapay.com/v1/payment_requests/bulk \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "payment_agreement": "pa_abc123",
        "amount": 120000,
        "currency": "eur",
        "description": "Rent — March 2025",
        "metadata": {"property_id": "prop_456", "period": "2025-03"}
      },
      {
        "payment_agreement": "pa_def456",
        "amount": 95000,
        "currency": "eur",
        "description": "Rent — March 2025",
        "metadata": {"property_id": "prop_789", "period": "2025-03"}
      },
      {
        "payment_agreement": "pa_ghi789",
        "amount": 150000,
        "currency": "eur",
        "description": "Rent — March 2025",
        "metadata": {"property_id": "prop_012", "period": "2025-03"}
      }
    ]
  }'

{
  "object": "list",
  "data": [
    {
      "id": "preq_001",
      "object": "payment_request",
      "payment_agreement": "pa_abc123",
      "amount": 120000,
      "currency": "eur",
      "status": "pending"
    },
    {
      "id": "preq_002",
      "object": "payment_request",
      "payment_agreement": "pa_def456",
      "amount": 95000,
      "currency": "eur",
      "status": "pending"
    },
    {
      "id": "preq_003",
      "object": "payment_request",
      "payment_agreement": "pa_ghi789",
      "amount": 150000,
      "currency": "eur",
      "status": "pending"
    }
  ],
  "total_created": 3
}

Retrieve a PaymentRequest#

Retrieves the details of an existing PaymentRequest.

GET/v1/payment_requests/:id

Parameters#

idstringREQUIRED

The PaymentRequest ID.

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

List PaymentRequests#

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

GET/v1/payment_requests

Parameters#

payment_agreementstring

Filter by PaymentAgreement ID.

statusstring

Filter by status: pending, processing, succeeded, failed, 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_requests?payment_agreement=pa_abc123&status=succeeded" \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

Cancel a PaymentRequest#

Cancels a pending or processing PaymentRequest. Requests that have already succeeded or failed cannot be cancelled.

POST/v1/payment_requests/:id/cancel

Parameters#

idstringREQUIRED

The PaymentRequest ID.

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

Statuses#

Status	Description
`pending`	Request created, collection not yet started
`processing`	CasaPay is actively attempting to collect payment
`succeeded`	Payment collected successfully
`failed`	All collection attempts exhausted, payment not collected
`cancelled`	Request was cancelled before completion

Retry logic#

CasaPay automatically retries failed collection attempts with exponential backoff:

Attempt 1 — Immediate on creation
Attempt 2 — 24 hours after first failure
Attempt 3 — 72 hours after second failure

If the preferred method fails, CasaPay falls back to other methods configured on the PaymentAgreement before exhausting retries. The next_retry_at field indicates when the next attempt is scheduled. Subscribe to payment_request.retrying webhooks to track retry progress.