[Goto Home](/docs/index.html)

# 🌍 POST `/payments/webhook`

## Description

- **Public API** (no authentication required).
- Webhook for Stripe checkout session updates.
- Accepts a checkout session id, finds the payment by `stripeCheckoutId`, and runs `services.managePayment` to sync status (e.g. completed or expired).
- Use this as the Stripe webhook endpoint for events like `checkout.session.completed` or `checkout.session.expired`.

## Request Body

The body can be in either format below.

### Option 1: Stripe event format (as sent by Stripe)

When configuring Stripe to send events to this URL, Stripe sends the full event object. The webhook uses `data.object.id` as the checkout session id.

```json
{
  "id": "evt_xxxxxxxxxxxxx",
  "object": "event",
  "type": "checkout.session.completed",
  "data": {
    "object": {
      "id": "cs_test_xxxxxxxxxxxxxxxxxxxxxxxx",
      "object": "checkout.session",
      "status": "complete",
      "payment_status": "paid"
    }
  }
}
```

### Option 2: Simple format (checkout session id only)

You can also POST a minimal body with just the checkout session id.

```json
{
  "checkoutSessionId": "cs_test_xxxxxxxxxxxxxxxxxxxxxxxx"
}
```

## Response Body

**Success (200):**

```json
{
  "message": "ok"
}
```

**Validation error (400):** Missing checkout session id

```json
{
  "message": "checkout session id required"
}
```

**Not found (404):** No payment found for the given checkout session id

```json
{
  "message": "payment not found"
}
```

# Links

[Goto Home](/docs/index.html)