**Versions de l’API** · [V2 (Latest)](/integrations/v2/docs?lang=fr) · **V1**

> **Cette version de l’API est obsolète.** Utilisez la dernière version pour toute nouvelle intégration. [Voir la documentation actuelle](/integrations/v2/docs?lang=fr)

# Paiements

OpenAPI 3.0.3 · API 1.0.0

```json
[
  {
    "url": "https://api.unisoft.world/integrations/v1",
    "description": "API"
  }
]
```

Dons et paiements.

## Opérations

## GET /paiements

Lister les paiements

`list_paiements`

Autorisation requise : `paiements:read`. Liste uniquement les paiements COMPLETED ou REFUNDED non supprimés, dans le périmètre de l’organisation et de la clé API. `externalRef` utilise une égalité exacte, sensible à la casse, et se combine avec les autres filtres ; plusieurs paiements peuvent partager cette valeur. Sans correspondance, renvoie une liste paginée vide. Les tentatives INIT, en attente et échouées restent exclues, même avec externalRef.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "paiements:read",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 200,
    "default": 50
  },
  "description": "Nombre de résultats par page."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Curseur opaque renvoyé par la requête précédente."
}
```

```json
{
  "name": "createdAfter",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "date-time"
  },
  "description": "Filtre : créé après cette date (ISO 8601)."
}
```

```json
{
  "name": "createdBefore",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "date-time"
  },
  "description": "Filtre : créé avant cette date (ISO 8601)."
}
```

```json
{
  "name": "type",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "GENERAL | SERVICE | CAISSE | DETTE | FORM"
}
```

```json
{
  "name": "platform",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "STRIPE | PAYGREEN | ..."
}
```

```json
{
  "name": "contactId",
  "in": "query",
  "schema": {
    "type": "string"
  }
}
```

```json
{
  "name": "externalRef",
  "in": "query",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 255,
    "pattern": "\\S",
    "example": "commande-1234",
    "description": "Référence facultative dans votre système. Non vide, enregistrée telle quelle ; correspondance exacte sensible à la casse. Non unique et ne constitue PAS une clé d’idempotence. À distinguer de externalId (dédoublonnage à l’import). Renvoyée lors de la lecture des paiements et dans les webhooks de paiement si elle est fournie. Héritée par les paiements récurrents."
  },
  "description": "Référence externe exacte, sensible à la casse ; encodez la valeur dans l’URL. Exemple : ?externalRef=commande-1234. Une valeur répétée/structurée ou invalide renvoie 400 INVALID_EXTERNAL_REF."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Paiement"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_EXTERNAL_REF",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INVALID_EXTERNAL_REF"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "ERREUR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "AUTORISATION_INSUFFISANTE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "paiements:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /paiements

Créer un lien de paiement autonome

`create_paiements`

Autorisation requise : `paiements:write`. Crée un enregistrement de paiement à l’état INIT et renvoie l’URL de la page de paiement hébergée (ou `clientSecret` pour les fournisseurs intégrés). L’entité cible (`typeId`) doit appartenir à l’organisation de la clé API. `config.organisation` est forcée côté serveur — toute valeur fournie par l’appelant est ignorée. `config` est validée avant traitement : `config.montant` doit être un nombre fini > 0 en unités majeures et ≤ 1000000 (sauf type SERVICE, dont le montant provient du service) ; `config.service` n’est accepté qu’avec type SERVICE ; chaque entrée `config.dettes[]` doit appartenir à votre organisation et avoir un montant fini > 0.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "paiements:write",
  "additional": []
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentRequest"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/PaymentResponse"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "MISSING_CONFIG / INVALID_MONTANT / MONTANT_TOO_LARGE / SERVICE_NOT_ALLOWED / INVALID_DETTES / INVALID_EXTERNAL_REF / INVALID_EXTERNAL_METADATA",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "MISSING_CONFIG / INVALID_MONTANT / MONTANT_TOO_LARGE / SERVICE_NOT_ALLOWED / INVALID_DETTES / INVALID_EXTERNAL_REF / INVALID_EXTERNAL_METADATA"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "ORG_NOT_FOUND / TARGET_NOT_FOUND / DETTE_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ORG_NOT_FOUND / TARGET_NOT_FOUND / DETTE_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "paiements:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## POST /paiements/import

Importer un paiement déjà encaissé

`import_paiement`

Autorisation requise : `paiements:write`. Enregistre un don encaissé AILLEURS (chèque, virement, espèces, ancien logiciel, autre plateforme) comme paiement historique/comptable — enregistré avec `imported:true` et `state:"COMPLETED"`. Il alimente statistiques, compteurs de campagne, CRM et conversions de devise, mais aucun reçu/cerfa n’est émis de nouveau. Équivalent unitaire et validé des importateurs CLI en masse. Utilisez `POST /paiements` (et non cette opération) pour qu’un donateur paie en ligne maintenant. Idempotent si `externalId` est fourni (migration relançable sans risque).

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "paiements:write",
  "additional": []
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaiementImportInput"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/Paiement"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_AMOUNT / INVALID_METHOD / ASSOC_NOT_FOUND / INVALID_EXTERNAL_REF / INVALID_EXTERNAL_METADATA",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INVALID_AMOUNT / INVALID_METHOD / ASSOC_NOT_FOUND / INVALID_EXTERNAL_REF / INVALID_EXTERNAL_METADATA"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND / TARGET_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND / TARGET_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp": false,
  "x-unisoft-scope": "paiements:write"
}
```

## GET /paiements/{id}

Obtenir un paiement

`get_paiement`

Autorisation requise : `paiements:read`. Le détail reste disponible à l’état REFUND_PENDING pour inspecter un remboursement non confirmé. Vérifiez auprès de Nedarim tout remboursement Nedarim non confirmé avant de réessayer.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "paiements:read",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/Paiement"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "paiements:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /paiements/{id}/refund

Rembourser un paiement

`refund_paiement`

Autorisation requise : `paiements:write`. Déclenche un remboursement intégral auprès du fournisseur de paiement. Fournisseurs pris en charge : Stripe, Stripe externe, iPay, Nedarim et PayGreen. Le paiement doit appartenir à l’organisation de la clé API, être terminé, ne pas être groupé ni déjà remboursé. Nedarim conserve le reçu d’origine et émet un reçu négatif. Une réponse Nedarim ou PayGreen non confirmée laisse le paiement à l’état REFUND_PENDING : vérifiez auprès du fournisseur avant de demander un autre remboursement. PayGreen vérifie la référence de commande, la boutique, le montant, la devise et les fonds encaissés avant de demander un remboursement complet. Cette opération financière est irréversible.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "paiements:write",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### Corps de la requête

```json
{
  "required": false,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentRefundRequest"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Remboursement accepté",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentRefundResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_REASON / INVALID_STATE / GROUPED_PAIEMENT / ALREADY_REFUNDED / REFUND_FAILED / NEDARIM_REFUND_UNCONFIRMED. Si pending vaut true, vérifiez la transaction dans Nedarim avant de réessayer.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentRefundResponse"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "PAIEMENT_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "PAIEMENT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

#### HTTP 405

```json
{
  "description": "METHOD_NOT_ALLOWED",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "METHOD_NOT_ALLOWED"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "paiements:write",
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": true,
    "idempotent": false,
    "warn": true
  }
}
```

## Schémas

```json
{
  "components": {
    "parameters": {
      "LimitParam": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 200,
          "default": 50
        },
        "description": "Nombre de résultats par page."
      },
      "CursorParam": {
        "name": "cursor",
        "in": "query",
        "schema": {
          "type": "string"
        },
        "description": "Curseur opaque renvoyé par la requête précédente."
      },
      "CreatedAfterParam": {
        "name": "createdAfter",
        "in": "query",
        "schema": {
          "type": "string",
          "format": "date-time"
        },
        "description": "Filtre : créé après cette date (ISO 8601)."
      },
      "CreatedBeforeParam": {
        "name": "createdBefore",
        "in": "query",
        "schema": {
          "type": "string",
          "format": "date-time"
        },
        "description": "Filtre : créé avant cette date (ISO 8601)."
      },
      "IdParam": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
        },
        "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
      }
    },
    "schemas": {
      "Paiement": {
        "type": "object",
        "description": "Un paiement (don, cotisation, paiement de formulaire, etc.). Les champs supplémentaires dépendent du fournisseur et du type de paiement.",
        "properties": {
          "externalRef": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "pattern": "\\S",
            "example": "commande-1234",
            "description": "Référence facultative dans votre système. Non vide, enregistrée telle quelle ; correspondance exacte sensible à la casse. Non unique et ne constitue PAS une clé d’idempotence. À distinguer de externalId (dédoublonnage à l’import). Renvoyée lors de la lecture des paiements et dans les webhooks de paiement si elle est fournie. Héritée par les paiements récurrents."
          },
          "externalMetadata": {
            "type": "object",
            "maxProperties": 50,
            "additionalProperties": {
              "type": "string",
              "maxLength": 500
            },
            "example": {
              "registrationId": "inscription-567",
              "eventId": "chabbat-890"
            },
            "description": "Carte facultative de chaînes clé-valeur gérée par l’appelant. Jusqu’à 50 clés (1–64 caractères chacune), valeurs de 500 caractères maximum. Les clés ne peuvent contenir . ou $, ni le caractère NUL, et ne peuvent être égales à __proto__, prototype ou constructor. Les valeurs null, tableaux, objets imbriqués et valeurs non textuelles sont refusés. Enregistrée telle quelle et renvoyée lors de la lecture des paiements et dans les webhooks ; héritée par les paiements récurrents. Distincte des métadonnées du fournisseur ; évitez d’y placer des secrets. Aucun de ces champs n’est obligatoire pour les paiements historiques."
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "typeId": {
            "type": "string",
            "nullable": true
          },
          "method": {
            "type": "string"
          },
          "refund": {
            "type": "object",
            "description": "Présent lorsqu’un remboursement a été demandé ; détails dépendant du fournisseur. Un remboursement confirmé a l’état SUCCEEDED.",
            "properties": {
              "state": {
                "type": "string"
              },
              "reason": {
                "type": "string"
              },
              "createdAt": {
                "type": "string",
                "format": "date-time"
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "id": {
            "type": "string"
          },
          "organisation": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "PENDING",
              "COMPLETED",
              "FAILED",
              "REFUNDED",
              "REFUND_PENDING",
              "CANCELED"
            ]
          },
          "type": {
            "type": "string",
            "enum": [
              "GENERAL",
              "SERVICE",
              "CAISSE",
              "DETTE",
              "FORM",
              "CAMPAGNE"
            ]
          },
          "platform": {
            "type": "string"
          },
          "amount": {
            "type": "integer",
            "description": "Montant en unités mineures (centimes)"
          },
          "devise": {
            "type": "string",
            "example": "EUR",
            "description": "Code de devise"
          },
          "contact": {
            "type": "string",
            "nullable": true,
            "description": "Identifiant du contact, lorsqu’il est identifié (pas un objet contact imbriqué)."
          },
          "info": {
            "$ref": "#/components/schemas/PaiementInfo"
          },
          "datetime": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PaiementInfo": {
        "type": "object",
        "nullable": true,
        "description": "Instantané de l’identité du donateur enregistrée sur le paiement (qui a donné). **Entièrement facultatif** — envoyez `null`, `{}` ou omettez-le pour un donateur anonyme/inconnu ; chaque sous-champ est également facultatif.\n\nRègles d’enregistrement : si AU MOINS un champ est renseigné, l’objet est enregistré au complet (les autres champs deviennent des chaînes vides, jamais null) ; si TOUS les champs sont vides, il est enregistré comme `null`, ce qui signifie « aucun contact donateur » et empêche l’envoi du reçu par EMAIL (le document du reçu est tout de même produit). `email` est l’adresse à laquelle le reçu est envoyé — sans elle, le donateur ne reçoit aucun email.\n\nUn seul cas est refusé (400 INVALID_INFO) : l’envoi d’une valeur qui n’est pas un objet, par ex. une chaîne ou un tableau. Cela indique toujours une erreur d’intégration (chaîne JSON non analysée), jamais un véritable donateur.",
        "properties": {
          "nom": {
            "type": "string",
            "description": "Nom de famille."
          },
          "prenom": {
            "type": "string",
            "description": "Prénom."
          },
          "email": {
            "type": "string",
            "description": "Adresse email à laquelle le reçu du paiement est envoyé."
          },
          "tel": {
            "type": "string",
            "description": "Numéro de téléphone (format E.164 recommandé)."
          }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "hasMore": {
            "type": "boolean"
          },
          "count": {
            "type": "integer"
          }
        }
      },
      "PaymentRequest": {
        "type": "object",
        "required": [
          "config"
        ],
        "properties": {
          "config": {
            "type": "object",
            "description": "Même structure que les données envoyées par le site web au endpoint de paiement public. La couche d’intégration force `config.organisation` à correspondre à l’organisation de la clé API.",
            "required": [
              "type",
              "montant"
            ],
            "properties": {
              "externalRef": {
                "type": "string",
                "minLength": 1,
                "maxLength": 255,
                "pattern": "\\S",
                "example": "commande-1234",
                "description": "Référence facultative dans votre système. Non vide, enregistrée telle quelle ; correspondance exacte sensible à la casse. Non unique et ne constitue PAS une clé d’idempotence. À distinguer de externalId (dédoublonnage à l’import). Renvoyée lors de la lecture des paiements et dans les webhooks de paiement si elle est fournie. Héritée par les paiements récurrents."
              },
              "externalMetadata": {
                "type": "object",
                "maxProperties": 50,
                "additionalProperties": {
                  "type": "string",
                  "maxLength": 500
                },
                "example": {
                  "registrationId": "inscription-567",
                  "eventId": "chabbat-890"
                },
                "description": "Carte facultative de chaînes clé-valeur gérée par l’appelant. Jusqu’à 50 clés (1–64 caractères chacune), valeurs de 500 caractères maximum. Les clés ne peuvent contenir . ou $, ni le caractère NUL, et ne peuvent être égales à __proto__, prototype ou constructor. Les valeurs null, tableaux, objets imbriqués et valeurs non textuelles sont refusés. Enregistrée telle quelle et renvoyée lors de la lecture des paiements et dans les webhooks ; héritée par les paiements récurrents. Distincte des métadonnées du fournisseur ; évitez d’y placer des secrets. Aucun de ces champs n’est obligatoire pour les paiements historiques."
              },
              "type": {
                "type": "string",
                "enum": [
                  "GENERAL",
                  "FORM",
                  "DETTE",
                  "CAISSE",
                  "SERVICE",
                  "CAMPAGNE"
                ]
              },
              "typeId": {
                "type": "string",
                "nullable": true,
                "description": "Identifiant de l’entité cible (obligatoire sauf si type=GENERAL)."
              },
              "montant": {
                "type": "number",
                "description": "Montant en unités majeures (par ex. euros)."
              },
              "devise": {
                "type": "string",
                "nullable": true
              },
              "name": {
                "type": "string",
                "nullable": true
              },
              "info": {
                "$ref": "#/components/schemas/PaiementInfo"
              },
              "facturation": {
                "$ref": "#/components/schemas/PaiementFacturation"
              },
              "returnUrl": {
                "type": "string",
                "nullable": true
              },
              "platform": {
                "type": "string",
                "nullable": true,
                "description": "Forcer une plateforme spécifique (par ex. STRIPE.SEPA, PAYME.IDD, PAYPAL)."
              },
              "abo": {
                "type": "boolean",
                "nullable": true
              },
              "nbMonth": {
                "type": "integer",
                "nullable": true
              },
              "maxAmount": {
                "type": "integer",
                "nullable": true
              }
            }
          }
        }
      },
      "PaiementFacturation": {
        "type": "object",
        "nullable": true,
        "description": "Identité de facturation/fiscale IMPRIMÉE SUR LE REÇU et le reçu fiscal (cerfa). **Entièrement facultative** — envoyez `null`, `{}` ou omettez-la ; chaque champ sera enregistré comme une chaîne vide (jamais null), ce qui permet de générer le reçu, mais celui-ci sera imprimé sans adresse. Chaque sous-champ est également facultatif. Renseignez-la TOUJOURS lorsque le don ouvre droit à un reçu fiscal, sans quoi le document sera vierge et inutilisable par le donateur.\n\n`perso` est le discriminant : `true` (par défaut) = particulier, le reçu est établi au nom de `nom` + `prenom` ; `false` = entreprise, le reçu est établi au nom de `raison` — fournissez TOUJOURS `raison` avec `perso:false`, sinon le reçu de l’entreprise portera un nom vide (accepté, mais inutilisable par le donateur). Lorsque `perso` est true et que `nom`/`prenom` sont omis, ils sont copiés depuis `info` si présents.\n\nDeux cas sont refusés (400 INVALID_FACTURATION) ; ils indiquent toujours une erreur d’intégration, pas un véritable don : envoyer une valeur qui n’est pas un objet (une chaîne ou un tableau au lieu du bloc), ou envoyer une valeur non booléenne pour `perso` (par ex. `1`, `0` ou `\"yes\"` — auparavant ces valeurs étaient interprétées silencieusement comme `true`, émettant un reçu de particulier pour une entreprise). Les champs texte fournis sous forme booléenne sont traités comme vides, de sorte que le mot \"false\" ne peut jamais être imprimé sur un reçu ; les nombres sont acceptés et convertis (`postal: 75001` → `\"75001\"`).",
        "properties": {
          "perso": {
            "type": "boolean",
            "default": true,
            "description": "true = particulier (nom/prenom), false = entreprise (raison/siren). Valeur par défaut : true."
          },
          "nom": {
            "type": "string",
            "description": "Nom de famille imprimé sur le reçu (particulier)."
          },
          "prenom": {
            "type": "string",
            "description": "Prénom imprimé sur le reçu (particulier)."
          },
          "civilite": {
            "type": "string",
            "description": "Civilité (M., Mme…) imprimée sur le reçu fiscal."
          },
          "raison": {
            "type": "string",
            "description": "Raison sociale. OBLIGATOIRE si perso est false — c’est le seul nom imprimé sur un reçu d’entreprise."
          },
          "siren": {
            "type": "string",
            "description": "Numéro d’immatriculation de l’entreprise (SIREN), imprimé à côté de sa raison sociale."
          },
          "adresse": {
            "type": "string",
            "description": "Adresse (rue) imprimée sur le reçu et synchronisée avec le contact CRM."
          },
          "postal": {
            "type": "string",
            "description": "Code postal."
          },
          "ville": {
            "type": "string",
            "description": "Ville."
          },
          "etat": {
            "type": "string",
            "description": "État / province. Imprimé sur le format de reçu canadien (CA) et synchronisé avec le CRM."
          },
          "pays": {
            "type": "string",
            "description": "Nom du pays. Utilisé par certains fournisseurs de paiement pour déterminer le code pays ISO."
          },
          "social_id": {
            "type": "string",
            "description": "Identifiant national (par ex. Teoudat Zehout) — utilisé par les plateformes de reçus israéliennes et synchronisé avec le contact CRM."
          },
          "giftAid": {
            "type": "boolean",
            "description": "Royaume-Uni uniquement : le donateur a accepté le Gift Aid. Active l’indicateur Gift Aid sur le contact CRM pour permettre à l’organisme de récupérer l’allègement fiscal. Omettez ce champ pour les dons hors Royaume-Uni."
          }
        }
      },
      "PaymentResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "paiementId": {
            "type": "string",
            "nullable": true
          },
          "url": {
            "type": "string",
            "nullable": true,
            "description": "URL de la page de paiement hébergée."
          },
          "clientSecret": {
            "type": "string",
            "nullable": true,
            "description": "Renvoyé par certains fournisseurs de type Stripe pour une interface intégrée."
          },
          "error": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "PaiementImportInput": {
        "type": "object",
        "description": "Don déjà encaissé à enregistrer comme paiement HISTORIQUE/comptable (chèque, virement, espèces, ancien logiciel ou autre plateforme). Il est enregistré avec `imported:true` et `state:\"COMPLETED\"` (forcés côté serveur) : il alimente les statistiques, compteurs de campagne, CRM et conversions de devise, mais aucun reçu/cerfa n’est émis de nouveau — le donateur l’a déjà reçu lors de l’encaissement. Utilisez cette opération pour migrer des paiements historiques ou consigner un don effectué hors plateforme ; utilisez plutôt `POST /paiements` pour qu’un donateur paie en ligne maintenant.",
        "required": [
          "method"
        ],
        "properties": {
          "externalRef": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "pattern": "\\S",
            "example": "commande-1234",
            "description": "Référence facultative dans votre système. Non vide, enregistrée telle quelle ; correspondance exacte sensible à la casse. Non unique et ne constitue PAS une clé d’idempotence. À distinguer de externalId (dédoublonnage à l’import). Renvoyée lors de la lecture des paiements et dans les webhooks de paiement si elle est fournie. Héritée par les paiements récurrents."
          },
          "externalMetadata": {
            "type": "object",
            "maxProperties": 50,
            "additionalProperties": {
              "type": "string",
              "maxLength": 500
            },
            "example": {
              "registrationId": "inscription-567",
              "eventId": "chabbat-890"
            },
            "description": "Carte facultative de chaînes clé-valeur gérée par l’appelant. Jusqu’à 50 clés (1–64 caractères chacune), valeurs de 500 caractères maximum. Les clés ne peuvent contenir . ou $, ni le caractère NUL, et ne peuvent être égales à __proto__, prototype ou constructor. Les valeurs null, tableaux, objets imbriqués et valeurs non textuelles sont refusés. Enregistrée telle quelle et renvoyée lors de la lecture des paiements et dans les webhooks ; héritée par les paiements récurrents. Distincte des métadonnées du fournisseur ; évitez d’y placer des secrets. Aucun de ces champs n’est obligatoire pour les paiements historiques."
          },
          "amount": {
            "type": "integer",
            "description": "Montant en unités mineures (centimes), par ex. 1500 = 15 €. Fournissez CE champ ou `montant` (pas les deux — `amount` est prioritaire). Doit être > 0."
          },
          "montant": {
            "type": "number",
            "description": "Montant en unités majeures de la devise, par ex. 50 = 50 € (comme le saisirait une personne). Converti en centimes côté serveur. Fournissez CE champ ou `amount`."
          },
          "method": {
            "type": "string",
            "enum": [
              "CB",
              "VIREMENT",
              "CHEQUE",
              "PRELEVEMENT",
              "CASH",
              "NATURE"
            ],
            "description": "Moyen de paiement. CB = carte/en ligne, VIREMENT = virement, CHEQUE = chèque, PRELEVEMENT = prélèvement bancaire, CASH = espèces, NATURE = don en nature. Les alias courants (wire/check/cash…) sont acceptés et normalisés."
          },
          "assoc": {
            "type": "string",
            "default": "MAIN",
            "description": "Association de l’organisation à laquelle ce don est rattaché — elle DÉTERMINE la devise et le reçu. Valeur par défaut : \"MAIN\". Consultez GET /associations pour les valeurs valides. `devise` en est toujours dérivée (ne peut pas être remplacée)."
          },
          "contactId": {
            "type": "string",
            "description": "Identifiant facultatif d’un contact CRM (de CETTE organisation) auquel rattacher le don. Aucun contact n’est créé implicitement — fournissez un identifiant existant ou omettez ce champ."
          },
          "type": {
            "type": "string",
            "enum": [
              "GENERAL",
              "CAMPAGNE",
              "DETTE",
              "CAISSE",
              "FORM"
            ],
            "default": "GENERAL",
            "description": "Type de rattachement. GENERAL (par défaut) = don simple. Sinon, rattachez à une entité de l’organisation via `typeId` : CAMPAGNE (alimente son compteur), DETTE (promesse de don), CAISSE, FORM (soumission). Le rattachement ne modifie PAS la devise (`assoc` la détermine)."
          },
          "typeId": {
            "type": "string",
            "description": "Identifiant de l’entité cible lorsque `type` ≠ GENERAL (campagne / dette / cagnotte / identifiant forms_submit). Doit appartenir à votre organisation."
          },
          "info": {
            "$ref": "#/components/schemas/PaiementInfo"
          },
          "facturation": {
            "$ref": "#/components/schemas/PaiementFacturation"
          },
          "commentaire": {
            "type": "string",
            "description": "Note en texte libre conservée sur le paiement."
          },
          "datetime": {
            "type": "string",
            "format": "date-time",
            "description": "Facultatif. Date RÉELLE d’encaissement du don, au format ISO 8601 (\"2024-01-15\" ou \"2024-01-15T10:30:00Z\") ; par défaut, la date actuelle si omise. À renseigner TOUJOURS lors d’une migration d’historique : cette date détermine l’ANNÉE FISCALE du reçu et sa séquence de numérotation ; une date erronée émet le reçu pour la mauvaise année. Si elle est fournie, elle doit être valide et ne pas être dans le futur — une valeur illisible (par ex. \"15/01/2024\", ambiguë, ou du texte libre) est refusée avec 400 INVALID_DATETIME au lieu d’être remplacée silencieusement par la date du jour ; une date future est refusée avec 400 DATETIME_IN_FUTURE (les dates jusqu’à 24h dans le futur sont tolérées pour compenser le décalage d’horloge du client)."
          },
          "source": {
            "type": "string",
            "default": "API_IMPORT",
            "description": "Libellé identifiant la provenance du paiement (par ex. \"HELLOASSO\", \"MY_OLD_SOFTWARE\"). Converti en majuscules. Valeur par défaut : \"API_IMPORT\"."
          },
          "externalId": {
            "type": "string",
            "description": "Votre référence stable pour ce paiement dans le système source. Lorsqu’elle est fournie, l’import est IDEMPOTENT : renvoyer le même externalId met à jour le même paiement au lieu d’en créer un doublon (réessai ou relance de migration sans risque). Sans cette référence, chaque appel crée un nouveau paiement."
          }
        }
      },
      "PaymentRefundRequest": {
        "type": "object",
        "properties": {
          "reason": {
            "type": "string",
            "enum": [
              "requested_by_customer",
              "duplicate",
              "fraudulent"
            ],
            "default": "requested_by_customer"
          },
          "message": {
            "type": "string",
            "description": "Note interne facultative enregistrée dans l’historique d’audit du remboursement."
          },
          "pauseAbo": {
            "type": "boolean",
            "default": false,
            "description": "Mettre également en pause l’abonnement associé, s’il existe."
          }
        }
      },
      "PaymentRefundResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "pending": {
            "type": "boolean",
            "description": "Le résultat du remboursement n’est pas confirmé. Vérifiez auprès du fournisseur avant de réessayer."
          },
          "refundId": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "nullable": true
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "message": {
            "type": "string",
            "nullable": true
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format : `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
