Alias Invoices#

Alias Invoices represent PDF invoices that were sent to a CasaPay email alias and processed into payment requests. Each Alias Invoice tracks the original PDF, extracted data, processing status, and the resulting payment request.

The Alias Invoice object#

Attribute	Type	Description
`id`	string	Unique identifier with `ainv_` prefix
`object`	string	Always `"alias_invoice"`
`email_alias`	string	The Email Alias ID that received this invoice
`alias_email`	string	The alias address (e.g., `jane.doe@casapay.me`)
`tenant`	string	Associated tenant/customer ID
`status`	enum	`received`, `processing`, `processed`, `failed`, `paid`
`sender_email`	string	Email address that sent the PDF
`subject`	string	Subject line of the incoming email
`pdf_url`	string	Signed URL to the original PDF
`extracted_data`	object	Data extracted from the PDF
`payment_request`	object	The generated payment request details
`payment_intent`	string	Associated PaymentIntent ID (once payment initiated)
`error`	object	Error details if processing failed
`metadata`	hash	Key-value pairs
`received_at`	timestamp	When the email was received
`processed_at`	timestamp	When processing completed
`paid_at`	timestamp	When the tenant paid
`created`	timestamp	Time at which the object was created
`livemode`	boolean	Whether this is a live mode object

{
  "id": "ainv_abc123",
  "object": "alias_invoice",
  "email_alias": "alias_def456",
  "alias_email": "jane.doe@casapay.me",
  "tenant": "cus_123456789",
  "status": "processed",
  "sender_email": "billing@property-manager.com",
  "subject": "Invoice #INV-2025-001 - January Rent",
  "pdf_url": "https://files.casapay.com/ainv_abc123/invoice.pdf",
  "extracted_data": {
    "total_amount": 125000,
    "currency": "eur",
    "due_date": "2025-02-01",
    "reference": "INV-2025-001",
    "line_items": [
      {
        "description": "Monthly rent — Unit 4B",
        "amount": 120000
      },
      {
        "description": "Parking space",
        "amount": 5000
      }
    ],
    "tax_amount": 0,
    "confidence_score": 0.95
  },
  "payment_request": {
    "id": "pr_xyz789",
    "payment_link": "https://pay.casapay.com/pr_xyz789",
    "amount": 125000,
    "currency": "eur",
    "status": "sent",
    "sent_via": ["email", "wallet"],
    "sent_at": 1706745600
  },
  "payment_intent": null,
  "error": null,
  "metadata": {},
  "received_at": 1706745500,
  "processed_at": 1706745600,
  "paid_at": null,
  "created": 1706745500,
  "livemode": true
}

Retrieve an Alias Invoice#

Retrieves the details of an alias invoice that has been received.

GET/v1/alias_invoices/:id

Parameters#

idstringREQUIRED

The alias invoice ID.

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

List Alias Invoices#

Returns a list of alias invoices. Sorted by received date, newest first.

GET/v1/alias_invoices

Parameters#

email_aliasstring

Filter by Email Alias ID.

tenantstring

Filter by tenant/customer ID.

statusstring

Filter by status: received, processing, processed, failed, paid.

limitinteger

Maximum number of objects to return. Default is 10.

starting_afterstring

Cursor for pagination.

curl "https://api.casapay.com/v1/alias_invoices?email_alias=alias_def456&status=processed" \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

Retry Processing#

Retries processing for a failed alias invoice.

POST/v1/alias_invoices/:id/retry

Parameters#

idstringREQUIRED

The alias invoice ID.

curl -X POST https://api.casapay.com/v1/alias_invoices/ainv_abc123/retry \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

Processing statuses#

Status	Description
`received`	PDF email received, queued for processing
`processing`	PDF is being analyzed and data extracted
`processed`	Successfully processed, payment request sent to tenant
`failed`	Processing failed (unreadable PDF, missing data, etc.)
`paid`	Tenant has completed payment

Extracted data#

The extracted_data object contains information parsed from the PDF:

Field	Type	Description
`total_amount`	integer	Total amount in smallest currency unit
`currency`	string	Detected currency (ISO 4217)
`due_date`	string	Payment due date (ISO 8601)
`reference`	string	Invoice reference number
`line_items`	array	Individual line items with description and amount
`tax_amount`	integer	Total tax amount detected
`confidence_score`	float	Extraction confidence (0.0 to 1.0)

Confidence threshold

Invoices with a confidence score below 0.7 are flagged for manual review. You can configure this threshold in your Dashboard settings.