PaymentIntents#

A PaymentIntent guides you through the process of collecting a payment from your tenant. It tracks a payment from creation through checkout, and triggers additional authentication steps when required.

The PaymentIntent object#

Attribute	Type	Description
`id`	string	Unique identifier with `pi_` prefix
`object`	string	Always `"payment_intent"`
`amount`	integer	Amount in smallest currency unit
`currency`	string	Three-letter ISO 4217 currency code
`status`	enum	See status flow below
`customer`	string	Customer ID
`payment_method`	string	Payment Method ID
`payment_method_types`	array	Allowed payment method types
`description`	string	Description of the payment
`client_secret`	string	Secret for client-side confirmation
`capture_method`	enum	`automatic` or `manual`
`confirmation_method`	enum	`automatic` or `manual`
`amount_received`	integer	Amount actually received
`charges`	list	List of Charge objects
`last_payment_error`	object	Last payment error, if any
`next_action`	object	Next action required (redirect, etc.)
`metadata`	hash	Key-value pairs
`created`	timestamp	Time at which the object was created
`livemode`	boolean	Whether this is a live mode object

Status Flow#

requires_payment_method → requires_confirmation → requires_action → processing → requires_capture → succeeded
                                                                                                   ↘ canceled

{
  "id": "pi_1a2b3c4d",
  "object": "payment_intent",
  "amount": 120000,
  "currency": "eur",
  "status": "requires_payment_method",
  "customer": "cus_123456789",
  "payment_method": null,
  "payment_method_types": ["card", "open_banking", "direct_debit"],
  "description": "Rent payment — February 2025",
  "client_secret": "pi_1a2b3c4d_secret_xyz789",
  "capture_method": "automatic",
  "amount_received": 0,
  "metadata": {
    "property_id": "prop_456",
    "period": "2025-02"
  },
  "created": 1706140800,
  "livemode": false
}

Create a PaymentIntent#

POST /v1/payment_intents

Parameter	Type	Required	Description
`amount`	integer	Yes	Amount in smallest currency unit
`currency`	string	Yes	ISO 4217 currency code
`customer`	string	No	Customer ID
`payment_method`	string	No	Payment Method ID to use
`payment_method_types`	array	No	Allowed types (default: `["card"]`)
`description`	string	No	Payment description
`capture_method`	string	No	`automatic` (default) or `manual`
`confirm`	boolean	No	Immediately confirm (default: false)
`return_url`	string	No	URL for redirect-based payment methods
`metadata`	hash	No	Key-value pairs

curl https://api.casapay.com/v1/payment_intents \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 120000,
    "currency": "eur",
    "customer": "cus_123456789",
    "payment_method_types": ["card", "open_banking", "direct_debit"],
    "description": "Rent payment — February 2025"
  }'

{
  "id": "pi_1a2b3c4d",
  "object": "payment_intent",
  "amount": 120000,
  "currency": "eur",
  "status": "requires_payment_method",
  "client_secret": "pi_1a2b3c4d_secret_xyz789",
  "created": 1706140800
}

Retrieve a PaymentIntent#

GET /v1/payment_intents/:id

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

Update a PaymentIntent#

POST /v1/payment_intents/:id

Parameter	Type	Description
`amount`	integer	Updated amount
`currency`	string	Updated currency
`description`	string	Updated description
`payment_method`	string	Attach a payment method
`metadata`	hash	Updated metadata

curl https://api.casapay.com/v1/payment_intents/pi_1a2b3c4d \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{"amount": 125000, "description": "Rent + parking — February 2025"}'

List PaymentIntents#

GET /v1/payment_intents

Parameter	Type	Description
`customer`	string	Filter by customer
`status`	string	Filter by status
`created[gte]`	timestamp	Created on or after
`created[lte]`	timestamp	Created on or before
`limit`	integer	Number of objects (1–100)
`starting_after`	string	Cursor for pagination

curl "https://api.casapay.com/v1/payment_intents?customer=cus_123456789&limit=10" \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

Confirm a PaymentIntent#

Confirms a PaymentIntent with a payment method, triggering the payment flow.

POST /v1/payment_intents/:id/confirm

Parameter	Type	Description
`payment_method`	string	Payment Method ID
`return_url`	string	URL for redirect-based methods

curl -X POST https://api.casapay.com/v1/payment_intents/pi_1a2b3c4d/confirm \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "pm_card_visa",
    "return_url": "https://your-app.com/payment/complete"
  }'

Cancel a PaymentIntent#

POST /v1/payment_intents/:id/cancel

Parameter	Type	Description
`cancellation_reason`	string	`duplicate`, `fraudulent`, `requested_by_customer`, `abandoned`

curl -X POST https://api.casapay.com/v1/payment_intents/pi_1a2b3c4d/cancel \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{"cancellation_reason": "requested_by_customer"}'

Capture a PaymentIntent#

Captures a PaymentIntent that was created with capture_method: manual.

POST /v1/payment_intents/:id/capture

Parameter	Type	Description
`amount_to_capture`	integer	Amount to capture (partial capture)

curl -X POST https://api.casapay.com/v1/payment_intents/pi_1a2b3c4d/capture \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"