Bank Authorisations#

Bank Authorisations represent an open banking payment flow where a tenant authorises a payment directly from their bank account. The tenant is redirected to their bank's authorization page.

The Bank Authorisation object#

Attribute	Type	Description
`id`	string	Unique identifier with `ba_` prefix
`object`	string	Always `"bank_authorisation"`
`status`	enum	`pending`, `authorised`, `consumed`, `expired`, `failed`
`authorization_url`	string	URL to redirect tenant for authorization
`institution`	object	Bank institution details
`institution.id`	string	Institution identifier
`institution.name`	string	Institution display name
`institution.logo_url`	string	Institution logo URL
`payment_intent`	string	Associated PaymentIntent ID
`customer`	string	Customer ID
`expires_at`	timestamp	When the authorisation expires
`metadata`	hash	Key-value pairs
`created`	timestamp	Time at which the object was created

{
  "id": "ba_xyz789",
  "object": "bank_authorisation",
  "status": "pending",
  "authorization_url": "https://bank.example.com/authorize?ref=ba_xyz789",
  "institution": {
    "id": "revolut",
    "name": "Revolut",
    "logo_url": "https://assets.casapay.com/institutions/revolut.svg"
  },
  "payment_intent": "pi_1a2b3c4d",
  "customer": "cus_123456789",
  "expires_at": 1706227200,
  "created": 1706140800
}

Create a Bank Authorisation#

POST /v1/bank_authorisations

Parameter	Type	Required	Description
`payment_intent`	string	Yes	PaymentIntent ID
`institution`	string	Yes	Institution identifier
`redirect_url`	string	Yes	Return URL after authorization

curl https://api.casapay.com/v1/bank_authorisations \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent": "pi_1a2b3c4d",
    "institution": "revolut",
    "redirect_url": "https://your-app.com/payment/complete"
  }'

Retrieve a Bank Authorisation#

GET /v1/bank_authorisations/:id

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

List Bank Authorisations#

GET /v1/bank_authorisations

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

curl "https://api.casapay.com/v1/bank_authorisations?payment_intent=pi_1a2b3c4d" \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"