# Payments

Read every payment — from checkout, invoices, links and plugins — through one endpoint.

# Payments

A **Payment** is a single money movement from a customer to your account. It is created for you when a Checkout Session completes, an invoice is paid or a payment link is used — you never create one directly.

Base URL `https://api.southbill.com` · Auth `Authorization: Bearer sk_live_…` · Scope `payments:read` (read-only — any non-`GET` returns `405`).

## Endpoints

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/payments` | List payments, newest first. |
| `GET` | `/v1/payments/{id}` | Retrieve by payment id, `payment_intent` or `charge`. |

## List payments

```bash
curl "https://api.southbill.com/v1/payments?limit=20&status=succeeded" \
  -H "Authorization: Bearer $SOUTHBILL_SECRET_KEY"
```

```node
const payments = await fetch(
  "https://api.southbill.com/v1/payments?limit=20&status=succeeded",
  { headers: { Authorization: `Bearer ${process.env.SOUTHBILL_SECRET_KEY}` } },
).then((r) => r.json());

for (const p of payments.data) {
  console.log(p.id, p.amount, p.currency, p.status);
}
```

```python
import os, requests

payments = requests.get(
    "https://api.southbill.com/v1/payments",
    headers={"Authorization": f"Bearer {os.environ['SOUTHBILL_SECRET_KEY']}"},
    params={"limit": 20, "status": "succeeded"},
    timeout=30,
).json()
```

```php
<?php
$ch = curl_init("https://api.southbill.com/v1/payments?limit=20&status=succeeded");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("SOUTHBILL_SECRET_KEY")],
]);
$payments = json_decode(curl_exec($ch), true);
```

Response:

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "cs_01J…",
      "object": "payment",
      "livemode": true,
      "status": "succeeded",
      "amount": 4990,
      "currency": "eur",
      "application_fee_amount": 132,
      "payment_intent": "pi_3P…",
      "charge": "ch_3P…",
      "checkout_session": "cs_01J…",
      "customer": "cus_9f2c…",
      "customer_email": "jane@example.com",
      "customer_name": "Jane Doe",
      "description": "Order 12345",
      "reference": "ORDER-12345",
      "payment_method_type": "card",
      "metadata": {},
      "source": "checkout",
      "created": 1756000000,
      "succeeded_at": 1756000042
    }
  ]
}
```

## Query parameters

| Parameter | Behaviour |
|---|---|
| `limit` | 1–100, default 25. |
| `starting_after` | Payment id, `payment_intent` or `charge` — returns rows created before it. |
| `status` | `succeeded` (settled) or `pending` (not completed yet). |
| `customer` | Customer id. |

## Status values

| Status | Meaning |
|---|---|
| `succeeded` | Captured; your fee is already deducted. |
| `pending` | Created but not completed — abandoned checkout or async method still clearing. |
| `refunded` / `partially_refunded` | See [Refunds](/docs/api/refunds). |
| `disputed` | A chargeback was opened. Handle it in the dashboard. |

Rate limit: 300 requests/min per key.