Payments & Credits

Copy page

Payments & Credits

Pay for lease signatures using the FairePlace credit system, powered by Stripe.

How credits work

• 1 credit = 1 lease signature (includes all signers on that lease)
• Credits are purchased via Stripe Checkout
• Credits never expire
• Credits are scoped to your organization (tenant)

Check your balance

Code
 
curl https://api.faireplace.com/api/credits/balance \
  -H "Authorization: Bearer $TOKEN"

Code
 
{
  "credits_available": 12,
  "credits_used": 38,
  "credits_total": 50
}

Purchase credits

1. Create a checkout session

Code
 
curl -X POST https://api.faireplace.com/api/credits/purchase \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "package": "10_credits",
    "success_url": "https://your-app.com/credits/success",
    "cancel_url": "https://your-app.com/credits/cancel"
  }'

Code
 
{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_a1b2c3...",
  "session_id": "cs_live_a1b2c3d4e5f6g7h8",
  "package": "10_credits",
  "amount": 300.00,
  "currency": "EUR"
}

2. Redirect to Stripe

Open the checkout_url in the user's browser. Stripe handles the payment form, card validation, and 3D Secure if required.

3. Credits are added automatically

After successful payment, credits are added to your balance immediately. The user is redirected to your success_url.

Pricing

Package	Credits	Price	Per signature
1_credit	1	30.00 EUR	30.00 EUR
5_credits	5	140.00 EUR	28.00 EUR
10_credits	10	250.00 EUR	25.00 EUR
25_credits	25	575.00 EUR	23.00 EUR
50_credits	50	1,000.00 EUR	20.00 EUR

All prices exclude VAT. VAT is calculated at checkout based on your billing country.

Credit history

View your transaction history:

Code
 
curl https://api.faireplace.com/api/credits/history \
  -H "Authorization: Bearer $TOKEN"

Code
 
{
  "transactions": [
    {
      "id": "txn-aabb1122-3344-5566-7788-99aabbccddee",
      "type": "purchase",
      "credits": 10,
      "amount": 250.00,
      "currency": "EUR",
      "stripe_payment_id": "pi_3abc123def456",
      "created_at": "2026-02-15T09:00:00Z"
    },
    {
      "id": "txn-ccdd3344-5566-7788-99aa-bbccddeeff00",
      "type": "usage",
      "credits": -1,
      "lease_id": "lease-4d5e6f78-90ab-cdef-1234-567890abcdef",
      "description": "Signature for BAIL-2026-001",
      "created_at": "2026-02-19T10:08:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 48
    }
  }
}

Stripe webhooks

FairePlace uses Stripe webhooks to process payments reliably. If you need to track payment events in your own system, you can listen for these webhook events.

Webhook endpoint

Configure your webhook endpoint in Stripe Dashboard to receive events at your URL.

Key events

Event	Description
checkout.session.completed	Payment successful, credits added to balance
charge.succeeded	Charge confirmed by the payment provider
charge.refunded	Refund processed (credits will be deducted)

Webhook payload example

Code
 
{
  "type": "checkout.session.completed",
  "data": {
    "object": {
      "id": "cs_live_a1b2c3d4e5f6g7h8",
      "payment_status": "paid",
      "amount_total": 25000,
      "currency": "eur",
      "metadata": {
        "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
        "package": "10_credits",
        "credits": "10"
      }
    }
  }
}

Verifying webhook signatures

Always verify the Stripe webhook signature to ensure the event is authentic:

Code
 
const stripe = require("stripe")(process.env.STRIPE_SECRET_KEY);

app.post("/webhooks/stripe", (req, res) => {
  const sig = req.headers["stripe-signature"];
  const event = stripe.webhooks.constructEvent(
    req.body,
    sig,
    process.env.STRIPE_WEBHOOK_SECRET
  );

  if (event.type === "checkout.session.completed") {
    const session = event.data.object;
    console.log(
      `Payment confirmed: ${session.metadata.credits} credits for tenant ${session.metadata.tenant_id}`
    );
  }

  res.json({ received: true });
});

Error handling

Insufficient credits when signing

If you try to initiate a signature without credits:

Code
 
{
  "error": {
    "code": 402,
    "type": "PAYMENT_REQUIRED",
    "message": "Insufficient signature credits",
    "details": {
      "credits_required": 1,
      "credits_available": 0,
      "purchase_url": "/api/credits/purchase"
    }
  }
}

Payment failed

If the Stripe checkout fails, no credits are added. The user can retry by creating a new checkout session.

---

Related

• Electronic Signatures — How signatures use credits
• Create a Lease End-to-End — Full workflow including payment
• Error Handling — All error codes and troubleshooting