Quickstart#

Collect your first payment in sandbox. You need an entity API key beginning sk_test_.

1

Create a session

Post the tenant, the amount and your return URLs. This example is a plain payment link - no deposit, no guarantee.

curl -X POST https://manage.test.casapay.com/api/v1/gateway/sessions \
  -H 'Authorization: Bearer sk_test_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "tenant": {
      "email": "tenant@example.com",
      "first_name": "Mari",
      "last_name": "Tamm"
    },
    "agreement_type": "payment_link",
    "first_payment_amount": 650,
    "first_payment_description": "March rent",
    "currency": "EUR",
    "success_url": "https://your-app.com/done",
    "cancel_url": "https://your-app.com/cancelled"
  }'
{
  "session_id": "gwy_9mK2xQ7pLr4vT1sZ",
  "gateway_url": "https://gateway.casapay.com/s/gwy_9mK2xQ7pLr4vT1sZ",
  "status": "pending",
  "expires_at": "2026-03-02T09:00:00+00:00",
  "first_payment_amount": 650.0,
  "total_amount": 650.0
}
2

Redirect the tenant

Send the tenant to gateway_url. Do not rebuild this URL yourself - it is returned per session.

CasaPay hosts every step from here: verification if required, the deposit choice if offered, then payment.

3

Complete the payment

In sandbox the checkout shows a simulator rather than a card form. Pick success to settle the payment, or bank_declined / insufficient_funds to exercise your failure handling.

The tenant is then redirected to your success_url, or cancel_url if they abandon.

4

Handle the webhook

Do not treat the browser redirect as proof of payment - the tenant may close the tab. Trust the webhook.

{
  "event": "gateway.session.completed",
  "session_id": "gwy_9mK2xQ7pLr4vT1sZ",
  "timestamp": "2026-03-01T09:12:33+00:00",
  "payment": {
    "cash_amount": 650.0,
    "currency": "EUR",
    "status": "paid",
    "paid_at": "2026-03-01T09:12:30+00:00",
    "payment_method": "everypay_card"
  },
  "payment_agreement_id": 4821,
  "invoice_id": 91733
}

Verify the signature before trusting the body - see Webhooks.

Next steps#