> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finkare.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Paiements

> Consultation des paiements reçus (totaux et partiels), avec filtres par statut, période et facture associée.

<Info>**Tester en direct** — Essayez ces endpoints dans la [documentation interactive Scalar](https://api.finkare.io/docs).</Info>

## Lister les paiements

**Scope requis :** `payments:read`

<ParamField query="status" type="string" optional>
  Filtrer par statut : `pending`, `completed`, `failed`, `refunded`
</ParamField>

<ParamField query="fromDate" type="string" optional>
  Date de début (ISO 8601). Exemple : `2026-01-01`
</ParamField>

<ParamField query="toDate" type="string" optional>
  Date de fin (ISO 8601). Exemple : `2026-03-31`
</ParamField>

<ParamField query="invoiceId" type="string" optional>
  Filtrer par ID de facture associée (UUID)
</ParamField>

<ParamField query="page" type="number" optional default="1">
  Numéro de page
</ParamField>

<ParamField query="limit" type="number" optional default="20">
  Résultats par page (max 100)
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "X-API-Key: fk_live_xxx" \
    "https://api.finkare.io/api/v1/payments?status=completed&fromDate=2026-01-01&toDate=2026-03-31"
  ```

  ```typescript SDK theme={null}
  const payments = await finkare.payments.list({
    status: 'completed',
    fromDate: '2026-01-01',
    toDate: '2026-03-31',
  });
  ```
</CodeGroup>

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "d4e5f6a7-b1c2-8901-def0-234567890abc",
      "invoiceId": "c3d4e5f6-a1b2-7890-cdef-1234567890ab",
      "amountCents": 150000,
      "currency": "EUR",
      "status": "completed",
      "method": "card",
      "paidAt": "2026-03-10T14:22:00Z"
    },
    {
      "id": "e5f6a7b8-c1d2-9012-ef01-345678901bcd",
      "invoiceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "amountCents": 50000,
      "currency": "EUR",
      "status": "completed",
      "method": "bank_transfer",
      "paidAt": "2026-03-15T09:45:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2
  },
  "requestId": "req_p1a2y3",
  "timestamp": "2026-04-08T10:00:00Z"
}
```

***

## Récupérer un paiement

**Scope requis :** `payments:read`

<ParamField path="id" type="string" required>
  ID du paiement (UUID)
</ParamField>

```bash theme={null}
curl -H "X-API-Key: fk_live_xxx" \
  https://api.finkare.io/api/v1/payments/d4e5f6a7-b1c2-8901-def0-234567890abc
```

```json theme={null}
{
  "success": true,
  "data": {
    "id": "d4e5f6a7-b1c2-8901-def0-234567890abc",
    "invoiceId": "c3d4e5f6-a1b2-7890-cdef-1234567890ab",
    "amountCents": 75000,
    "currency": "EUR",
    "status": "completed",
    "method": "card",
    "paidAt": "2026-03-10T14:22:00Z"
  },
  "requestId": "req_x1y2z3",
  "timestamp": "2026-04-08T10:00:00Z"
}
```

<ResponseField name="data.amountCents" type="number">
  Montant du paiement en centimes. Peut être inférieur au montant de la facture (paiement partiel).
</ResponseField>

<ResponseField name="data.status" type="string">
  Statut du paiement : `pending` (en cours), `completed` (confirmé), `failed` (échoué), `refunded` (remboursé)
</ResponseField>

<ResponseField name="data.method" type="string">
  Méthode de paiement : `card`, `bank_transfer`, `sepa_debit`, `payment_link`
</ResponseField>

***

## Paiements d'une facture

Récupère tous les paiements associés à une facture (utile pour les paiements partiels).

**Scope requis :** `payments:read`

<ParamField path="invoiceId" type="string" required>
  ID de la facture (UUID)
</ParamField>

```bash theme={null}
curl -H "X-API-Key: fk_live_xxx" \
  https://api.finkare.io/api/v1/payments/invoice/c3d4e5f6-a1b2-7890-cdef-1234567890ab
```

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "d4e5f6a7-b1c2-8901-def0-234567890abc",
      "amountCents": 75000,
      "status": "completed",
      "method": "card",
      "paidAt": "2026-03-10T14:22:00Z"
    },
    {
      "id": "f6a7b8c9-d1e2-0123-f012-456789012cde",
      "amountCents": 75000,
      "status": "completed",
      "method": "bank_transfer",
      "paidAt": "2026-03-25T11:00:00Z"
    }
  ],
  "requestId": "req_inv_pay_01",
  "timestamp": "2026-04-08T10:00:00Z"
}
```

***

## Statistiques des paiements

**Scope requis :** `reports:read`

<ParamField query="period" type="string" optional>
  Période d'agrégation : `day`, `week`, `month`, `year`
</ParamField>

```bash theme={null}
curl -H "X-API-Key: fk_live_xxx" \
  "https://api.finkare.io/api/v1/payments/stats/summary?period=month"
```

```json theme={null}
{
  "success": true,
  "data": {
    "totalCollected": 4250000,
    "totalPending": 350000,
    "currency": "EUR",
    "period": "month",
    "byMethod": {
      "card": 2100000,
      "bank_transfer": 1500000,
      "sepa_debit": 650000
    },
    "conversionRate": 87.4
  },
  "requestId": "req_stats_p01",
  "timestamp": "2026-04-08T10:00:00Z"
}
```