FairePlace Property Management API

Credits

Endpointhttps://api.faireplace.com/api

Credit system management.

Credits allow owners to pay for platform services (e.g., lease signing) without having to enter their payment information each time.

Features

Purchase credits via Stripe Checkout Session
Check credit balance
Transaction history (purchases, consumption)
List available packages

Restrictions

Only users with the owner role can purchase credits
Credits are isolated by tenant (multi-tenant)

Create a payment intent for a lease

POST

https://api.faireplace.com/api

/leases/{lease_id}/payment/create-intent

Creates a payment intent for a lease (signing fees, etc.).

Supported methods:

stripe: creates a Stripe PaymentIntent; the response contains client_secret for Stripe Elements (web).
credit: debits the user's credit balance; the response may contain balance_after.

Prerequisites:

The lease must exist (otherwise 404).
LeasesWrite permission required.
For credits: sufficient balance (otherwise 422 business error).

Create a payment intent for a lease › path Parameters

lease_id

string · uuid · required

Lease ID

Create a payment intent for a lease › Request Body

Request to create a payment intent for a lease. The `lease_id` is provided in the route path, not in the body.

amount

integer · int64 · min: 1 · required

Amount in cents (e.g. 2990 = 29.90 EUR).

Example: 2990

currency

string · minLength: 1 · maxLength: 10 · required

Currency code (e.g. "eur", "EUR").

Example: eur

payment_method

string · enum · required

Payment method for a lease.

stripe: card payment via Stripe (PaymentIntent)
credit: debit from the user's credit balance

Enum values:

stripe

credit

Example: stripe

object | null

Optional metadata propagated to the payment port. The backend automatically adds lease_id and reason (e.g. "lease_payment").

Create a payment intent for a lease › Responses

Payment intent created successfully

Response after creating a payment intent. - For Stripe: contains `client_secret` for Stripe Elements. - For credits: may contain `balance_after` (balance after debit).

payment_intent_id

string · required

Stripe PaymentIntent ID (e.g. "pi_xxx") or credit transaction ID.

Example: pi_3ABC123xyz

status

string · enum · required

Payment status.

Enum values:

pending

succeeded

failed

canceled

Example: succeeded

amount

integer · int64 · required

Amount in cents.

Example: 2990

currency

string · required

payment_method

string · enum · required

Payment method for a lease.

stripe: card payment via Stripe (PaymentIntent)
credit: debit from the user's credit balance

Enum values:

stripe

credit

Example: stripe

client_secret

string | null

Client secret for Stripe Elements (web). Absent for credit payments.

Example: pi_3ABC123xyz_secret_xxx

balance_after

integer | null · int64

Credit balance after consumption (only if payment_method = credit).

Example: 4710

POST/leases/{lease_id}/payment/create-intent

curl --request POST \
  --url https://api.faireplace.com/api/leases/:lease_id/payment/create-intent \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 2990,
  "currency": "eur",
  "payment_method": "stripe"
}
'

shell

Example Request Body

{
  "amount": 2990,
  "currency": "eur",
  "payment_method": "stripe"
}

json

application/json

Example Responses

{
  "payment_intent_id": "pi_3ABC123xyz",
  "client_secret": "pi_3ABC123xyz_secret_xxx",
  "status": "pending",
  "amount": 2990,
  "currency": "eur",
  "payment_method": "stripe"
}

json

application/json

Purchase credits

POST

https://api.faireplace.com/api

/credits/purchase

Initiates credit purchase via Stripe Checkout Session.

Purchase Process

Code
 
┌─────────────────────────────────────────────────────────────┐
│  1. Client calls POST /credits/purchase                    │
│     with package_id, success_url, cancel_url               │
└─────────────────────────────────────────────────────────────┘
                      │
                      ▼
            ┌─────────────────────┐
            │ Verify package      │
            │ - Exists?           │
            │ - Active?           │
            │ - stripe_price_id?  │
            └─────────────────────┘
             │              │
    VALID    │              │      INVALID
             ▼              ▼
┌──────────────────┐  ┌──────────────────┐
│ Retrieve         │  │ Error 404/400    │
│ stripeCustomerId │  │                  │
│ from Better      │  │                  │
│ Auth             │  │                  │
└──────────────────┘  └──────────────────┘
             │
             ▼
┌──────────────────────────────┐
│ Create Stripe Checkout       │
│ Session with:                │
│ - customer_id                │
│ - price_id                   │
│ - metadata (tenant_id,       │
│   user_id, package_id)       │
│ - success_url                │
│ - cancel_url                 │
└──────────────────────────────┘
             │
             ▼
┌──────────────────────────────┐
│ Return checkout_url          │
│                              │
│ Client redirects to          │
│ Stripe Checkout              │
└──────────────────────────────┘
             │
             ▼
┌──────────────────────────────┐
│ User pays on Stripe          │
│                              │
│ Stripe sends webhook         │
│ checkout.session.completed   │
└──────────────────────────────┘
             │
             ▼
┌──────────────────────────────┐
│ Backend credits the credits  │
│ via webhook handler          │
└──────────────────────────────┘

Prerequisites

The user must have the owner role (no Stripe account for tenants)
The user must have a stripeCustomerId in Better Auth
- If absent, error 400: "You must have a Stripe account to purchase credits"
The package must be active and have a stripe_price_id configured

Validations

✅ Validation of package_id (valid UUID)
✅ URL validation (success_url and cancel_url must be valid URLs)
✅ Verification that the package exists and is active
✅ Verification that the package has a stripe_price_id
✅ Retrieval of stripeCustomerId from Better Auth
✅ Creation of Stripe Checkout Session with complete metadata

Stripe Metadata

The Stripe Checkout Session includes the following metadata for webhook processing:


Code
 
{
  "tenant_id": "tenant_123",
  "user_id": "user_456",
  "package_id": "550e8400-e29b-41d4-a716-446655440000"
}

This metadata allows the webhook to credit the right user in the correct tenant after successful payment.

Error Handling

400 Bad Request: Invalid package, invalid URLs, or no Stripe account
401 Unauthorized: Invalid or expired JWT token
403 Forbidden: User is not an owner
404 Not Found: Package not found or inactive
500 Internal Server Error: Error creating the Checkout Session

Usage Example

Code
 
curl -X POST https://api.faireplace.com/v1/credits/purchase \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "package_id": "550e8400-e29b-41d4-a716-446655440000",
    "success_url": "https://app.faireplace.com/credits/success?session_id={CHECKOUT_SESSION_ID}",
    "cancel_url": "https://app.faireplace.com/credits/cancel"
  }'

Response:


Code
 
{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4e5f6...",
  "package_id": "550e8400-e29b-41d4-a716-446655440000",
  "package_name": "Pack Starter",
  "credits_amount": 1000,
  "price_cents": 2990
}

The user must then be redirected to checkout_url to complete payment.

Purchase credits › Request Body

Request to initiate a credit purchase. This request creates a Stripe Checkout Session and returns the payment URL. Payment is processed by Stripe, and credits are automatically credited via webhook when payment is confirmed.

package_id

string · uuid · required

Identifier of the credit package to purchase.

The package must be active and have a configured stripe_price_id.

Example: 550e8400-e29b-41d4-a716-446655440000

success_url

string · uri · required

Redirect URL after successful payment.

The user will be redirected to this URL after completing the payment on the Stripe Checkout page.

Recommendations:

Include a success parameter to identify the transaction
Example: https://app.fairplace.com/credits/success?session_id={CHECKOUT_SESSION_ID}

Example: https://app.fairplace.com/credits/success?session_id={CHECKOUT_SESSION_ID}

cancel_url

string · uri · required

Redirect URL if the user cancels the payment.

The user will be redirected to this URL if they close the Stripe Checkout page without completing the payment.

Example: https://app.fairplace.com/credits/cancel

Purchase credits › Responses

Purchase session created successfully.

The user must be redirected to checkout_url to complete payment. Credits will be automatically credited after successful payment via webhook.

Response after creating a credit purchase session. Contains the Stripe Checkout page URL where the user must be redirected to complete the payment.

checkout_url

string · uri · required

Stripe Checkout page URL.

Required action: Redirect the user to this URL to complete the payment.

This URL is valid for a limited time (typically 24 hours). If the user does not complete the payment within this period, the session expires.

Example: https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4e5f6...

package_id

string · uuid · required

Identifier of the selected package.

Example: 550e8400-e29b-41d4-a716-446655440000

package_name

string · required

Name of the selected package.

Example: Pack Starter

credits_amount

integer · int64 · required

Number of credits that will be credited after successful payment (in cents).

Example: 1000

price_cents

integer · int64 · required

Package price in euro cents.

Example: 2990

POST/credits/purchase

curl --request POST \
  --url https://api.faireplace.com/api/credits/purchase \
  --header 'Content-Type: application/json' \
  --data '
{
  "package_id": "550e8400-e29b-41d4-a716-446655440000",
  "success_url": "https://app.faireplace.com/credits/success?session_id={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://app.faireplace.com/credits/cancel"
}
'

shell

Example Request Body

{
  "package_id": "550e8400-e29b-41d4-a716-446655440000",
  "success_url": "https://app.faireplace.com/credits/success?session_id={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://app.faireplace.com/credits/cancel"
}

json

application/json

Example Responses

{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4e5f6...",
  "package_id": "550e8400-e29b-41d4-a716-446655440000",
  "package_name": "Pack Starter",
  "credits_amount": 1000,
  "price_cents": 2990
}

json

application/json

Get credit balance

GET

https://api.faireplace.com/api

/credits/balance

Retrieves the current credit balance of the authenticated user.

Behavior

If the user has never had credits, returns a balance of 0 (no 404 error)
The balance is always expressed in euro cents
The currency is always EUR for now

Multi-Tenant Isolation

The returned balance is automatically filtered by:

tenant_id extracted from the JWT
user_id extracted from the JWT (claim sub)

A user can only see their own balance, and only within their tenant.

Balance Format

The balance is returned in cents:

5000 = 50.00 EUR of available credits
2990 = 29.90 EUR of available credits
0 = No credits available

Usage Example

Code
 
curl -X GET https://api.faireplace.com/v1/credits/balance \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:


Code
 
{
  "balance": 5000,
  "currency": "EUR",
  "last_updated": "2026-01-28T10:30:00Z"
}

Get credit balance › Responses

Balance retrieved successfully.

Always returns a balance (0 if the user has never had credits).

Credit balance for a user. The balance is expressed in euro cents (1 credit = 1 cent). A user without an existing balance will return a zero balance rather than an error.

balance

integer · int64 · min: 0 · required

Credit balance in euro cents.

Examples:

5000 = 50.00 EUR in credits
2990 = 29.90 EUR in credits
0 = No credits available

Example: 5000

currency

string · enum · required

Balance currency (always "EUR" for now).

Enum values:

EUR

Example: EUR

last_updated

string | null · date-time

Date and time of the last balance update (ISO 8601).

Format: YYYY-MM-DDTHH:mm:ssZ

Example: 2026-01-28T10:30:00Z

GET/credits/balance

curl --request GET \
  --url https://api.faireplace.com/api/credits/balance

shell

Example Responses

{
  "balance": 5000,
  "currency": "EUR",
  "last_updated": "2026-01-28T10:30:00Z"
}

json

application/json

Get transaction history

GET

https://api.faireplace.com/api

/credits/transactions

Retrieves the credit transaction history of the authenticated user with pagination.

Pagination

Transactions are returned with pagination:

limit: Maximum number of transactions to return (default: 50, max: 100)
offset: Number of transactions to skip (default: 0)

Transactions are sorted by creation date descending (most recent first).

Transaction Types

Transactions can be of different types:

purchase: Credit purchase via Stripe
consumption: Credit consumption for a payment
expiration: Credit expiration (if applicable)
refund: Credit refund
adjustment: Manual adjustment by an administrator

Amount Format

Amounts are in cents:

Positive amount for purchases and additions
Negative amount for consumptions

Multi-Tenant Isolation

The returned transactions are automatically filtered by:

tenant_id extracted from the JWT
user_id extracted from the JWT (claim sub)

A user can only see their own transactions, and only within their tenant.

Usage Example

Code
 
# Retrieve the first 20 transactions
curl -X GET "https://api.faireplace.com/v1/credits/transactions?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Retrieve the next transactions (pagination)
curl -X GET "https://api.faireplace.com/v1/credits/transactions?limit=20&offset=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:


Code
 
{
  "transactions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "amount": 1000,
      "transaction_type": "purchase",
      "reason": "Credit purchase via Stripe Checkout Session cs_test_123",
      "balance_before": 2000,
      "balance_after": 3000,
      "created_at": "2026-01-28T10:30:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "amount": -2990,
      "transaction_type": "consumption",
      "reason": "Consumption for lease signing lease_789",
      "balance_before": 5000,
      "balance_after": 2010,
      "created_at": "2026-01-27T15:20:00Z"
    }
  ],
  "total": 2,
  "limit": 20,
  "offset": 0
}

Get transaction history › query Parameters

limit

integer · int64 · min: 1 · max: 100

Maximum number of transactions to return.

Default: 50
Maximum: 100
Minimum: 1

Default: 50

offset

integer · int64 · min: 0

Offset for pagination (number of transactions to skip).

Default: 0
Minimum: 0

Default: 0

Get transaction history › Responses

Transaction history retrieved successfully.

Always returns an array (empty if the user has never had transactions).

Response containing the list of credit transactions with pagination.

object[] · required

List of transactions, sorted by creation date descending (most recent first).

total

integer · int32 · required

Total number of transactions returned in this response.

Note: This is not the total number of user transactions, but only the count returned in this page.

Example: 10

limit

integer · int64 · required

Maximum number of requested transactions.

Default value: 50 Maximum: 100

Example: 50

offset

integer · int64 · required

Offset for pagination (number of transactions to skip).

Default value: 0

Example: 0

GET/credits/transactions

curl --request GET \
  --url https://api.faireplace.com/api/credits/transactions

shell

Example Responses

{
  "transactions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "amount": 1000,
      "transaction_type": "purchase",
      "reason": "Credit purchase via Stripe Checkout Session cs_test_123",
      "balance_before": 2000,
      "balance_after": 3000,
      "created_at": "2026-01-28T10:30:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "amount": -2990,
      "transaction_type": "consumption",
      "reason": "Consumption for lease signing lease_789",
      "balance_before": 5000,
      "balance_after": 2010,
      "created_at": "2026-01-27T15:20:00Z"
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}

json

application/json

List available credit packages

GET

https://api.faireplace.com/api

/credits/packages

Retrieves the list of credit packages available for purchase for the tenant.

Filtering

By default, only active packages are returned. To include inactive packages, use active_only=false.

Sorting

Packages are sorted by:

display_order ascending (configured display order)
Creation date ascending (in case of display_order tie)

Multi-Tenant Isolation

The returned packages are automatically filtered by:

tenant_id extracted from the JWT

Each tenant can have its own configured credit packages.

Prerequisites for Purchase

For a package to be purchasable, it must:

Be active (active: true)
Have a stripe_price_id configured
Belong to the user's tenant

Usage Example

Code
 
# List only active packages (default)
curl -X GET "https://api.faireplace.com/v1/credits/packages" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# List all packages (active and inactive)
curl -X GET "https://api.faireplace.com/v1/credits/packages?active_only=false" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:


Code
 
{
  "packages": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Pack Starter",
      "description": "Starter pack ideal for small landlords",
      "credits_amount": 1000,
      "price_cents": 2990,
      "active": true,
      "display_order": 1
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Pack Pro",
      "description": "Professional pack for active landlords",
      "credits_amount": 5000,
      "price_cents": 12990,
      "active": true,
      "display_order": 2
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "name": "Pack Business",
      "description": "Business pack for large portfolio owners",
      "credits_amount": 20000,
      "price_cents": 49990,
      "active": true,
      "display_order": 3
    }
  ]
}

List available credit packages › query Parameters

active_only

boolean

Filter only active packages.

Default: true (only active packages are returned)
false: Also include inactive packages

Inactive packages cannot be purchased but may be visible for traceability or administration purposes.

Default: true

List available credit packages › Responses

Package list retrieved successfully.

Always returns an array (empty if no packages are configured for the tenant).

Response containing the list of available credit packages.

object[] · required

List of packages, sorted by display_order ascending, then by creation date.

GET/credits/packages

curl --request GET \
  --url https://api.faireplace.com/api/credits/packages

shell

Example Responses

{
  "packages": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Pack Starter",
      "description": "Starter pack ideal for small landlords",
      "credits_amount": 1000,
      "price_cents": 2990,
      "active": true,
      "display_order": 1
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Pack Pro",
      "description": "Professional pack for active landlords",
      "credits_amount": 5000,
      "price_cents": 12990,
      "active": true,
      "display_order": 2
    }
  ]
}

json

application/json

Services Lease Annexes

FairePlace Property Management API

Credits

Endpointhttps://api.faireplace.com/api

Credit system management.

Credits allow owners to pay for platform services (e.g., lease signing) without having to enter their payment information each time.

Features

Purchase credits via Stripe Checkout Session
Check credit balance
Transaction history (purchases, consumption)
List available packages

Restrictions

Only users with the owner role can purchase credits
Credits are isolated by tenant (multi-tenant)

Create a payment intent for a lease

POST

https://api.faireplace.com/api

/leases/{lease_id}/payment/create-intent

Creates a payment intent for a lease (signing fees, etc.).

Supported methods:

stripe: creates a Stripe PaymentIntent; the response contains client_secret for Stripe Elements (web).
credit: debits the user's credit balance; the response may contain balance_after.

Prerequisites:

The lease must exist (otherwise 404).
LeasesWrite permission required.
For credits: sufficient balance (otherwise 422 business error).

Create a payment intent for a lease › path Parameters

lease_id

string · uuid · required

Lease ID

Create a payment intent for a lease › Request Body

Request to create a payment intent for a lease. The `lease_id` is provided in the route path, not in the body.

amount

integer · int64 · min: 1 · required

Amount in cents (e.g. 2990 = 29.90 EUR).

Example: 2990

currency

string · minLength: 1 · maxLength: 10 · required

Currency code (e.g. "eur", "EUR").

Example: eur

payment_method

string · enum · required

Payment method for a lease.

stripe: card payment via Stripe (PaymentIntent)
credit: debit from the user's credit balance

Enum values:

stripe

credit

Example: stripe

object | null

Optional metadata propagated to the payment port. The backend automatically adds lease_id and reason (e.g. "lease_payment").

Create a payment intent for a lease › Responses

Payment intent created successfully

Response after creating a payment intent. - For Stripe: contains `client_secret` for Stripe Elements. - For credits: may contain `balance_after` (balance after debit).

payment_intent_id

string · required

Stripe PaymentIntent ID (e.g. "pi_xxx") or credit transaction ID.

Example: pi_3ABC123xyz

status

string · enum · required

Payment status.

Enum values:

pending

succeeded

failed

canceled

Example: succeeded

amount

integer · int64 · required

Amount in cents.

Example: 2990

currency

string · required

payment_method

string · enum · required

Payment method for a lease.

stripe: card payment via Stripe (PaymentIntent)
credit: debit from the user's credit balance

Enum values:

stripe

credit

Example: stripe

client_secret

string | null

Client secret for Stripe Elements (web). Absent for credit payments.

Example: pi_3ABC123xyz_secret_xxx

balance_after

integer | null · int64

Credit balance after consumption (only if payment_method = credit).

Example: 4710

POST/leases/{lease_id}/payment/create-intent

curl --request POST \
  --url https://api.faireplace.com/api/leases/:lease_id/payment/create-intent \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 2990,
  "currency": "eur",
  "payment_method": "stripe"
}
'

shell

Example Request Body

{
  "amount": 2990,
  "currency": "eur",
  "payment_method": "stripe"
}

json

application/json

Example Responses

{
  "payment_intent_id": "pi_3ABC123xyz",
  "client_secret": "pi_3ABC123xyz_secret_xxx",
  "status": "pending",
  "amount": 2990,
  "currency": "eur",
  "payment_method": "stripe"
}

json

application/json

Purchase credits

POST

https://api.faireplace.com/api

/credits/purchase

Initiates credit purchase via Stripe Checkout Session.

Purchase Process

Code
 
┌─────────────────────────────────────────────────────────────┐
│  1. Client calls POST /credits/purchase                    │
│     with package_id, success_url, cancel_url               │
└─────────────────────────────────────────────────────────────┘
                      │
                      ▼
            ┌─────────────────────┐
            │ Verify package      │
            │ - Exists?           │
            │ - Active?           │
            │ - stripe_price_id?  │
            └─────────────────────┘
             │              │
    VALID    │              │      INVALID
             ▼              ▼
┌──────────────────┐  ┌──────────────────┐
│ Retrieve         │  │ Error 404/400    │
│ stripeCustomerId │  │                  │
│ from Better      │  │                  │
│ Auth             │  │                  │
└──────────────────┘  └──────────────────┘
             │
             ▼
┌──────────────────────────────┐
│ Create Stripe Checkout       │
│ Session with:                │
│ - customer_id                │
│ - price_id                   │
│ - metadata (tenant_id,       │
│   user_id, package_id)       │
│ - success_url                │
│ - cancel_url                 │
└──────────────────────────────┘
             │
             ▼
┌──────────────────────────────┐
│ Return checkout_url          │
│                              │
│ Client redirects to          │
│ Stripe Checkout              │
└──────────────────────────────┘
             │
             ▼
┌──────────────────────────────┐
│ User pays on Stripe          │
│                              │
│ Stripe sends webhook         │
│ checkout.session.completed   │
└──────────────────────────────┘
             │
             ▼
┌──────────────────────────────┐
│ Backend credits the credits  │
│ via webhook handler          │
└──────────────────────────────┘

Prerequisites

The user must have the owner role (no Stripe account for tenants)
The user must have a stripeCustomerId in Better Auth
- If absent, error 400: "You must have a Stripe account to purchase credits"
The package must be active and have a stripe_price_id configured

Validations

✅ Validation of package_id (valid UUID)
✅ URL validation (success_url and cancel_url must be valid URLs)
✅ Verification that the package exists and is active
✅ Verification that the package has a stripe_price_id
✅ Retrieval of stripeCustomerId from Better Auth
✅ Creation of Stripe Checkout Session with complete metadata

Stripe Metadata

The Stripe Checkout Session includes the following metadata for webhook processing:


Code
 
{
  "tenant_id": "tenant_123",
  "user_id": "user_456",
  "package_id": "550e8400-e29b-41d4-a716-446655440000"
}

This metadata allows the webhook to credit the right user in the correct tenant after successful payment.

Error Handling

400 Bad Request: Invalid package, invalid URLs, or no Stripe account
401 Unauthorized: Invalid or expired JWT token
403 Forbidden: User is not an owner
404 Not Found: Package not found or inactive
500 Internal Server Error: Error creating the Checkout Session

Usage Example

Code
 
curl -X POST https://api.faireplace.com/v1/credits/purchase \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "package_id": "550e8400-e29b-41d4-a716-446655440000",
    "success_url": "https://app.faireplace.com/credits/success?session_id={CHECKOUT_SESSION_ID}",
    "cancel_url": "https://app.faireplace.com/credits/cancel"
  }'

Response:


Code
 
{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4e5f6...",
  "package_id": "550e8400-e29b-41d4-a716-446655440000",
  "package_name": "Pack Starter",
  "credits_amount": 1000,
  "price_cents": 2990
}

The user must then be redirected to checkout_url to complete payment.

Purchase credits › Request Body

package_id

string · uuid · required

Identifier of the credit package to purchase.

The package must be active and have a configured stripe_price_id.

Example: 550e8400-e29b-41d4-a716-446655440000

success_url

string · uri · required

Redirect URL after successful payment.

The user will be redirected to this URL after completing the payment on the Stripe Checkout page.

Recommendations:

Include a success parameter to identify the transaction
Example: https://app.fairplace.com/credits/success?session_id={CHECKOUT_SESSION_ID}

Example: https://app.fairplace.com/credits/success?session_id={CHECKOUT_SESSION_ID}

cancel_url

string · uri · required

Redirect URL if the user cancels the payment.

The user will be redirected to this URL if they close the Stripe Checkout page without completing the payment.

Example: https://app.fairplace.com/credits/cancel

Purchase credits › Responses

Purchase session created successfully.

The user must be redirected to checkout_url to complete payment. Credits will be automatically credited after successful payment via webhook.

Response after creating a credit purchase session. Contains the Stripe Checkout page URL where the user must be redirected to complete the payment.

checkout_url

string · uri · required

Stripe Checkout page URL.

Required action: Redirect the user to this URL to complete the payment.

This URL is valid for a limited time (typically 24 hours). If the user does not complete the payment within this period, the session expires.

Example: https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4e5f6...

package_id

string · uuid · required

Identifier of the selected package.

Example: 550e8400-e29b-41d4-a716-446655440000

package_name

string · required

Name of the selected package.

Example: Pack Starter

credits_amount

integer · int64 · required

Number of credits that will be credited after successful payment (in cents).

Example: 1000

price_cents

integer · int64 · required

Package price in euro cents.

Example: 2990

POST/credits/purchase

curl --request POST \
  --url https://api.faireplace.com/api/credits/purchase \
  --header 'Content-Type: application/json' \
  --data '
{
  "package_id": "550e8400-e29b-41d4-a716-446655440000",
  "success_url": "https://app.faireplace.com/credits/success?session_id={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://app.faireplace.com/credits/cancel"
}
'

shell

Example Request Body

{
  "package_id": "550e8400-e29b-41d4-a716-446655440000",
  "success_url": "https://app.faireplace.com/credits/success?session_id={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://app.faireplace.com/credits/cancel"
}

json

application/json

Example Responses

{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4e5f6...",
  "package_id": "550e8400-e29b-41d4-a716-446655440000",
  "package_name": "Pack Starter",
  "credits_amount": 1000,
  "price_cents": 2990
}

json

application/json

Get credit balance

GET

https://api.faireplace.com/api

/credits/balance

Retrieves the current credit balance of the authenticated user.

Behavior

If the user has never had credits, returns a balance of 0 (no 404 error)
The balance is always expressed in euro cents
The currency is always EUR for now

Multi-Tenant Isolation

The returned balance is automatically filtered by:

tenant_id extracted from the JWT
user_id extracted from the JWT (claim sub)

A user can only see their own balance, and only within their tenant.

Balance Format

The balance is returned in cents:

5000 = 50.00 EUR of available credits
2990 = 29.90 EUR of available credits
0 = No credits available

Usage Example

Code
 
curl -X GET https://api.faireplace.com/v1/credits/balance \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:


Code
 
{
  "balance": 5000,
  "currency": "EUR",
  "last_updated": "2026-01-28T10:30:00Z"
}

Get credit balance › Responses

Balance retrieved successfully.

Always returns a balance (0 if the user has never had credits).

Credit balance for a user. The balance is expressed in euro cents (1 credit = 1 cent). A user without an existing balance will return a zero balance rather than an error.

balance

integer · int64 · min: 0 · required

Credit balance in euro cents.

Examples:

5000 = 50.00 EUR in credits
2990 = 29.90 EUR in credits
0 = No credits available

Example: 5000

currency

string · enum · required

Balance currency (always "EUR" for now).

Enum values:

EUR

Example: EUR

last_updated

string | null · date-time

Date and time of the last balance update (ISO 8601).

Format: YYYY-MM-DDTHH:mm:ssZ

Example: 2026-01-28T10:30:00Z

GET/credits/balance

curl --request GET \
  --url https://api.faireplace.com/api/credits/balance

shell

Example Responses

{
  "balance": 5000,
  "currency": "EUR",
  "last_updated": "2026-01-28T10:30:00Z"
}

json

application/json

Get transaction history

GET

https://api.faireplace.com/api

/credits/transactions

Retrieves the credit transaction history of the authenticated user with pagination.

Pagination

Transactions are returned with pagination:

limit: Maximum number of transactions to return (default: 50, max: 100)
offset: Number of transactions to skip (default: 0)

Transactions are sorted by creation date descending (most recent first).

Transaction Types

Transactions can be of different types:

purchase: Credit purchase via Stripe
consumption: Credit consumption for a payment
expiration: Credit expiration (if applicable)
refund: Credit refund
adjustment: Manual adjustment by an administrator

Amount Format

Amounts are in cents:

Positive amount for purchases and additions
Negative amount for consumptions

Multi-Tenant Isolation

The returned transactions are automatically filtered by:

tenant_id extracted from the JWT
user_id extracted from the JWT (claim sub)

A user can only see their own transactions, and only within their tenant.

Usage Example

Code
 
# Retrieve the first 20 transactions
curl -X GET "https://api.faireplace.com/v1/credits/transactions?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Retrieve the next transactions (pagination)
curl -X GET "https://api.faireplace.com/v1/credits/transactions?limit=20&offset=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:


Code
 
{
  "transactions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "amount": 1000,
      "transaction_type": "purchase",
      "reason": "Credit purchase via Stripe Checkout Session cs_test_123",
      "balance_before": 2000,
      "balance_after": 3000,
      "created_at": "2026-01-28T10:30:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "amount": -2990,
      "transaction_type": "consumption",
      "reason": "Consumption for lease signing lease_789",
      "balance_before": 5000,
      "balance_after": 2010,
      "created_at": "2026-01-27T15:20:00Z"
    }
  ],
  "total": 2,
  "limit": 20,
  "offset": 0
}

Get transaction history › query Parameters

limit

integer · int64 · min: 1 · max: 100

Maximum number of transactions to return.

Default: 50
Maximum: 100
Minimum: 1

Default: 50

offset

integer · int64 · min: 0

Offset for pagination (number of transactions to skip).

Default: 0
Minimum: 0

Default: 0

Get transaction history › Responses

Transaction history retrieved successfully.

Always returns an array (empty if the user has never had transactions).

Response containing the list of credit transactions with pagination.

object[] · required

List of transactions, sorted by creation date descending (most recent first).

total

integer · int32 · required

Total number of transactions returned in this response.

Note: This is not the total number of user transactions, but only the count returned in this page.

Example: 10

limit

integer · int64 · required

Maximum number of requested transactions.

Default value: 50 Maximum: 100

Example: 50

offset

integer · int64 · required

Offset for pagination (number of transactions to skip).

Default value: 0

Example: 0

GET/credits/transactions

curl --request GET \
  --url https://api.faireplace.com/api/credits/transactions

shell

Example Responses

{
  "transactions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "amount": 1000,
      "transaction_type": "purchase",
      "reason": "Credit purchase via Stripe Checkout Session cs_test_123",
      "balance_before": 2000,
      "balance_after": 3000,
      "created_at": "2026-01-28T10:30:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "amount": -2990,
      "transaction_type": "consumption",
      "reason": "Consumption for lease signing lease_789",
      "balance_before": 5000,
      "balance_after": 2010,
      "created_at": "2026-01-27T15:20:00Z"
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}

json

application/json

List available credit packages

GET

https://api.faireplace.com/api

/credits/packages

Retrieves the list of credit packages available for purchase for the tenant.

Filtering

By default, only active packages are returned. To include inactive packages, use active_only=false.

Sorting

Packages are sorted by:

display_order ascending (configured display order)
Creation date ascending (in case of display_order tie)

Multi-Tenant Isolation

The returned packages are automatically filtered by:

tenant_id extracted from the JWT

Each tenant can have its own configured credit packages.

Prerequisites for Purchase

For a package to be purchasable, it must:

Be active (active: true)
Have a stripe_price_id configured
Belong to the user's tenant

Usage Example

Code
 
# List only active packages (default)
curl -X GET "https://api.faireplace.com/v1/credits/packages" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# List all packages (active and inactive)
curl -X GET "https://api.faireplace.com/v1/credits/packages?active_only=false" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:


Code
 
{
  "packages": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Pack Starter",
      "description": "Starter pack ideal for small landlords",
      "credits_amount": 1000,
      "price_cents": 2990,
      "active": true,
      "display_order": 1
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Pack Pro",
      "description": "Professional pack for active landlords",
      "credits_amount": 5000,
      "price_cents": 12990,
      "active": true,
      "display_order": 2
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "name": "Pack Business",
      "description": "Business pack for large portfolio owners",
      "credits_amount": 20000,
      "price_cents": 49990,
      "active": true,
      "display_order": 3
    }
  ]
}

List available credit packages › query Parameters

active_only

boolean

Filter only active packages.

Default: true (only active packages are returned)
false: Also include inactive packages

Inactive packages cannot be purchased but may be visible for traceability or administration purposes.

Default: true

List available credit packages › Responses

Package list retrieved successfully.

Always returns an array (empty if no packages are configured for the tenant).

Response containing the list of available credit packages.

object[] · required

List of packages, sorted by display_order ascending, then by creation date.

GET/credits/packages

curl --request GET \
  --url https://api.faireplace.com/api/credits/packages

shell

Example Responses

{
  "packages": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Pack Starter",
      "description": "Starter pack ideal for small landlords",
      "credits_amount": 1000,
      "price_cents": 2990,
      "active": true,
      "display_order": 1
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Pack Pro",
      "description": "Professional pack for active landlords",
      "credits_amount": 5000,
      "price_cents": 12990,
      "active": true,
      "display_order": 2
    }
  ]
}

json

application/json

Services Lease Annexes