**API versions** · [V2 (Latest)](/integrations/v2/docs?lang=en) · **V1**

> **This API version is obsolete.** Use the latest version for new integrations. [View the current documentation](/integrations/v2/docs?lang=en)

# Payments

OpenAPI 3.0.3 · API 1.0.0

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

Donations and payments

## Operations

## GET /paiements

List payments

`list_paiements`

Required scope: `paiements:read`. Lists only non-deleted COMPLETED or REFUNDED payments within the organisation and API-key restrictions. externalRef uses exact, case-sensitive equality and combines with the other filters; multiple payments may share it. No match returns an empty paginated list. INIT, pending and failed attempts remain excluded even with externalRef.

### Authentication

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

### Required permissions

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

### Parameters

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 200,
    "default": 50
  },
  "description": "Number of results per page"
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Opaque cursor returned by the previous request"
}
```

```json
{
  "name": "createdAfter",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "date-time"
  },
  "description": "Filter: created after this date (ISO 8601)"
}
```

```json
{
  "name": "createdBefore",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "date-time"
  },
  "description": "Filter: created before this 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": "Optional reference in your system. Non-blank, stored verbatim; exact, case-sensitive matching. Not unique and NOT an idempotency key. Distinct from externalId (import deduplication). Returned on payment reads and payment webhooks when supplied. Recurring payments inherit it."
  },
  "description": "Exact, case-sensitive external reference; URL-encode the value. Example: ?externalRef=commande-1234. A repeated/structured or invalid value returns 400 INVALID_EXTERNAL_REF."
}
```

### Responses

#### 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": "ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE",
  "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

Create a standalone payment link

`create_paiements`

Required scope: `paiements:write`. Creates a payment record in INIT state and returns the hosted payment page URL (or clientSecret for embedded providers). The target entity (`typeId`) must belong to the API key's organisation. `config.organisation` is forced server-side — any value supplied by the caller is ignored. `config` is validated before processing: `config.montant` must be a finite number > 0 in major currency units and ≤ 1000000 (except type SERVICE, whose amount comes from the service); `config.service` is only accepted with type SERVICE; every `config.dettes[]` entry must belong to your organisation and carry a finite montant > 0.

### Authentication

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

### Required permissions

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

### Request body

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

### Responses

#### 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

Import an already-collected payment

`import_paiement`

Required scope: `paiements:write`. Records a donation cashed ELSEWHERE (cheque, wire, cash, a legacy software, another platform) as a historical/accounting payment — stored with `imported:true` and `state:"COMPLETED"`. It feeds stats, campaign counters, the CRM and currency conversion, but NO receipt/cerfa is (re)emitted. This is the unitary, validated equivalent of the bulk CLI importers. Use `POST /paiements` (not this) when you want a donor to pay online now. Idempotent when `externalId` is supplied (safe to re-run a migration).

### Authentication

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

### Required permissions

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

### Request body

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

### Responses

#### 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}

Get a payment

`get_paiement`

Required scope: `paiements:read`. The detail remains available in REFUND_PENDING so an unconfirmed refund can be inspected. Verify an unconfirmed Nedarim refund in Nedarim before retrying.

### Authentication

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

### Required permissions

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

### Parameters

```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": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### Responses

#### 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

Refund a payment

`refund_paiement`

Required scope: `paiements:write`. Issues a full refund through the payment's provider. Supported providers are Stripe, external Stripe, iPay, Nedarim and PayGreen. The payment must belong to the API key's organisation, be completed, not grouped and not already refunded. Nedarim preserves the original receipt and issues a negative receipt. An unconfirmed Nedarim or PayGreen response leaves the payment in REFUND_PENDING: verify it with the provider before attempting another refund. PayGreen verifies the order reference, shop, amount, currency and captured funds before submitting a full refund. This financial action is irreversible.

### Authentication

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

### Required permissions

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

### Parameters

```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": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### Request body

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

### Responses

#### HTTP 200

```json
{
  "description": "Refund accepted",
  "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. If pending is true, verify the transaction in Nedarim before retrying.",
  "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
  }
}
```

## Schemas

```json
{
  "components": {
    "parameters": {
      "LimitParam": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 200,
          "default": 50
        },
        "description": "Number of results per page"
      },
      "CursorParam": {
        "name": "cursor",
        "in": "query",
        "schema": {
          "type": "string"
        },
        "description": "Opaque cursor returned by the previous request"
      },
      "CreatedAfterParam": {
        "name": "createdAfter",
        "in": "query",
        "schema": {
          "type": "string",
          "format": "date-time"
        },
        "description": "Filter: created after this date (ISO 8601)"
      },
      "CreatedBeforeParam": {
        "name": "createdBefore",
        "in": "query",
        "schema": {
          "type": "string",
          "format": "date-time"
        },
        "description": "Filter: created before this 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": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
      }
    },
    "schemas": {
      "Paiement": {
        "type": "object",
        "description": "A payment (donation, dues, form payment, etc.). Additional fields depend on the payment provider and payment type.",
        "properties": {
          "externalRef": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "pattern": "\\S",
            "example": "commande-1234",
            "description": "Optional reference in your system. Non-blank, stored verbatim; exact, case-sensitive matching. Not unique and NOT an idempotency key. Distinct from externalId (import deduplication). Returned on payment reads and payment webhooks when supplied. Recurring payments inherit it."
          },
          "externalMetadata": {
            "type": "object",
            "maxProperties": 50,
            "additionalProperties": {
              "type": "string",
              "maxLength": 500
            },
            "example": {
              "registrationId": "inscription-567",
              "eventId": "chabbat-890"
            },
            "description": "Optional caller-owned string-to-string map. Up to 50 keys (1–64 characters each), values up to 500 characters. Keys cannot contain . or $ or a NUL character, or equal __proto__, prototype or constructor. Null, arrays, nested objects and non-string values are rejected. Stored verbatim and returned on payment reads and payment webhooks; recurring payments inherit it. Separate from provider metadata; avoid secrets. Neither field is required on historical payments."
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "typeId": {
            "type": "string",
            "nullable": true
          },
          "method": {
            "type": "string"
          },
          "refund": {
            "type": "object",
            "description": "Present when a refund has been requested; provider-dependent details. A confirmed refund has state 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": "Amount in minor units (cents)"
          },
          "devise": {
            "type": "string",
            "example": "EUR",
            "description": "Currency code"
          },
          "contact": {
            "type": "string",
            "nullable": true,
            "description": "Contact id, when identified (not a nested contact object)."
          },
          "info": {
            "$ref": "#/components/schemas/PaiementInfo"
          },
          "datetime": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PaiementInfo": {
        "type": "object",
        "nullable": true,
        "description": "Donor identity snapshot stored on the payment (who gave). **Entirely optional** — send `null`, `{}` or omit it for an anonymous / unknown donor; every sub-field is optional too.\n\nStorage rules: if ANY field is filled the object is stored complete (the other fields become empty strings, never null); if ALL are empty it is stored as `null`, which means \"no donor contact\" and suppresses the receipt EMAIL (the receipt document itself is still produced). `email` is the address the receipt is sent to — without it the donor gets no email.\n\nOnly one thing is rejected (400 INVALID_INFO): sending a non-object, e.g. a string or an array. That always indicates an integration mistake (an unparsed JSON string), never a real donor.",
        "properties": {
          "nom": {
            "type": "string",
            "description": "Last name."
          },
          "prenom": {
            "type": "string",
            "description": "First name."
          },
          "email": {
            "type": "string",
            "description": "Email the payment receipt is sent to."
          },
          "tel": {
            "type": "string",
            "description": "Phone number (E164 preferred)."
          }
        }
      },
      "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": "Same shape as the payload the website sends to the public payment endpoint. The integrations layer forces `config.organisation` to the API key's organisation.",
            "required": [
              "type",
              "montant"
            ],
            "properties": {
              "externalRef": {
                "type": "string",
                "minLength": 1,
                "maxLength": 255,
                "pattern": "\\S",
                "example": "commande-1234",
                "description": "Optional reference in your system. Non-blank, stored verbatim; exact, case-sensitive matching. Not unique and NOT an idempotency key. Distinct from externalId (import deduplication). Returned on payment reads and payment webhooks when supplied. Recurring payments inherit it."
              },
              "externalMetadata": {
                "type": "object",
                "maxProperties": 50,
                "additionalProperties": {
                  "type": "string",
                  "maxLength": 500
                },
                "example": {
                  "registrationId": "inscription-567",
                  "eventId": "chabbat-890"
                },
                "description": "Optional caller-owned string-to-string map. Up to 50 keys (1–64 characters each), values up to 500 characters. Keys cannot contain . or $ or a NUL character, or equal __proto__, prototype or constructor. Null, arrays, nested objects and non-string values are rejected. Stored verbatim and returned on payment reads and payment webhooks; recurring payments inherit it. Separate from provider metadata; avoid secrets. Neither field is required on historical payments."
              },
              "type": {
                "type": "string",
                "enum": [
                  "GENERAL",
                  "FORM",
                  "DETTE",
                  "CAISSE",
                  "SERVICE",
                  "CAMPAGNE"
                ]
              },
              "typeId": {
                "type": "string",
                "nullable": true,
                "description": "Target entity id (required except for type=GENERAL)."
              },
              "montant": {
                "type": "number",
                "description": "Amount in major units (e.g. 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": "Force a specific platform (e.g. 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": "Billing / fiscal identity PRINTED ON THE RECEIPT and the tax receipt (cerfa). **Entirely optional** — send `null`, `{}` or omit it and every field is stored as an empty string (never null), which keeps receipt generation working but prints a receipt with no address. Every sub-field is optional too. ALWAYS fill it when the donation is eligible for a tax receipt, otherwise the document is issued blank and is unusable by the donor.\n\n`perso` is the discriminant: `true` (default) = individual, the receipt is issued to `nom` + `prenom`; `false` = company, the receipt is issued to `raison` — so ALWAYS send `raison` with `perso:false`, otherwise the company receipt is issued with a blank name (accepted, but unusable by the donor). When `perso` is true and `nom`/`prenom` are omitted, they are copied from `info` if present.\n\nTwo things are rejected (400 INVALID_FACTURATION), both of which always indicate an integration mistake rather than a real donation: sending a non-object (a string or array instead of the block), and sending a non-boolean `perso` (e.g. `1`, `0` or `\"yes\"` — these used to be silently read as `true`, issuing an individual receipt to a company). Text fields sent as a boolean are treated as empty, so the word \"false\" can never be printed on a receipt; numbers are accepted and converted (`postal: 75001` → `\"75001\"`).",
        "properties": {
          "perso": {
            "type": "boolean",
            "default": true,
            "description": "true = individual (nom/prenom), false = company (raison/siren). Defaults to true."
          },
          "nom": {
            "type": "string",
            "description": "Last name on the receipt (individual)."
          },
          "prenom": {
            "type": "string",
            "description": "First name on the receipt (individual)."
          },
          "civilite": {
            "type": "string",
            "description": "Title (M., Mme…) printed on the tax receipt."
          },
          "raison": {
            "type": "string",
            "description": "Company name. REQUIRED when perso is false — it is the only name printed on a company receipt."
          },
          "siren": {
            "type": "string",
            "description": "Company registration number (SIREN) printed next to the company name."
          },
          "adresse": {
            "type": "string",
            "description": "Street address printed on the receipt and synced to the CRM contact."
          },
          "postal": {
            "type": "string",
            "description": "Postal code."
          },
          "ville": {
            "type": "string",
            "description": "City."
          },
          "etat": {
            "type": "string",
            "description": "State / province. Printed on the CA (Canada) receipt format and synced to the CRM."
          },
          "pays": {
            "type": "string",
            "description": "Country name. Used by some payment providers to resolve the ISO country code."
          },
          "social_id": {
            "type": "string",
            "description": "National ID (e.g. Teoudat Zehout) — used by the Israeli receipt platforms and synced to the CRM contact."
          },
          "giftAid": {
            "type": "boolean",
            "description": "UK only: the donor has agreed to Gift Aid. Sets the Gift Aid flag on the CRM contact so the charity can reclaim the tax relief. Omit it for non-UK donations."
          }
        }
      },
      "PaymentResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "paiementId": {
            "type": "string",
            "nullable": true
          },
          "url": {
            "type": "string",
            "nullable": true,
            "description": "Hosted payment page URL."
          },
          "clientSecret": {
            "type": "string",
            "nullable": true,
            "description": "Returned by some Stripe-style providers for embedded UX."
          },
          "error": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "PaiementImportInput": {
        "type": "object",
        "description": "An already-collected donation to record as a HISTORICAL / accounting payment (cheque, wire, cash, a legacy software, another platform). It is stored with `imported:true` and `state:\"COMPLETED\"` (forced server-side): it feeds stats, campaign counters, the CRM and currency conversion, but NO receipt / cerfa is (re)emitted — the donor already got one wherever the money was collected. Use this to migrate historical payments or to log an off-platform donation; use `POST /paiements` instead to make a donor pay online now.",
        "required": [
          "method"
        ],
        "properties": {
          "externalRef": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "pattern": "\\S",
            "example": "commande-1234",
            "description": "Optional reference in your system. Non-blank, stored verbatim; exact, case-sensitive matching. Not unique and NOT an idempotency key. Distinct from externalId (import deduplication). Returned on payment reads and payment webhooks when supplied. Recurring payments inherit it."
          },
          "externalMetadata": {
            "type": "object",
            "maxProperties": 50,
            "additionalProperties": {
              "type": "string",
              "maxLength": 500
            },
            "example": {
              "registrationId": "inscription-567",
              "eventId": "chabbat-890"
            },
            "description": "Optional caller-owned string-to-string map. Up to 50 keys (1–64 characters each), values up to 500 characters. Keys cannot contain . or $ or a NUL character, or equal __proto__, prototype or constructor. Null, arrays, nested objects and non-string values are rejected. Stored verbatim and returned on payment reads and payment webhooks; recurring payments inherit it. Separate from provider metadata; avoid secrets. Neither field is required on historical payments."
          },
          "amount": {
            "type": "integer",
            "description": "Amount in MINOR units (cents), e.g. 1500 = 15€. Provide THIS or `montant` (not both — `amount` wins). Must be > 0."
          },
          "montant": {
            "type": "number",
            "description": "Amount in MAJOR currency units, e.g. 50 = 50€ (like a human types). Converted to cents server-side. Provide THIS or `amount`."
          },
          "method": {
            "type": "string",
            "enum": [
              "CB",
              "VIREMENT",
              "CHEQUE",
              "PRELEVEMENT",
              "CASH",
              "NATURE"
            ],
            "description": "Payment instrument. CB = card / online, VIREMENT = wire, CHEQUE = cheque, PRELEVEMENT = direct debit, CASH = cash, NATURE = gift in kind. Human aliases (wire/check/cash…) are accepted and normalised."
          },
          "assoc": {
            "type": "string",
            "default": "MAIN",
            "description": "The org association this donation belongs to — it FIXES the currency and the receipt. Defaults to \"MAIN\". List valid values via GET /associations. The `devise` is always derived from it (never overridable)."
          },
          "contactId": {
            "type": "string",
            "description": "Optional CRM contact id (of THIS org) to attach the donation to. No contact is created implicitly — supply an existing id or omit."
          },
          "type": {
            "type": "string",
            "enum": [
              "GENERAL",
              "CAMPAGNE",
              "DETTE",
              "CAISSE",
              "FORM"
            ],
            "default": "GENERAL",
            "description": "Attachment kind. GENERAL (default) = a plain donation. Otherwise attach to one of your org's entities via `typeId`: CAMPAGNE (feeds its counter), DETTE (a pledge), CAISSE (a pot), FORM (a submission). The attachment does NOT change the currency (`assoc` does)."
          },
          "typeId": {
            "type": "string",
            "description": "Id of the target entity when `type` ≠ GENERAL (campaign / dette / caisse / forms_submit id). Must belong to your organisation."
          },
          "info": {
            "$ref": "#/components/schemas/PaiementInfo"
          },
          "facturation": {
            "$ref": "#/components/schemas/PaiementFacturation"
          },
          "commentaire": {
            "type": "string",
            "description": "Free-text note kept on the payment."
          },
          "datetime": {
            "type": "string",
            "format": "date-time",
            "description": "Optional. The REAL date the donation was collected, ISO 8601 (\"2024-01-15\" or \"2024-01-15T10:30:00Z\"); defaults to now when omitted. ALWAYS set it when migrating history: this date determines the FISCAL YEAR of the receipt and its numbering sequence, so a wrong value issues the receipt for the wrong year. When provided it must be a valid, non-future date — an unparseable value (e.g. the ambiguous \"15/01/2024\", or free text) is rejected with 400 INVALID_DATETIME rather than silently falling back to today, and a future date is rejected with 400 DATETIME_IN_FUTURE (dates up to 24h ahead are tolerated for client clock skew)."
          },
          "source": {
            "type": "string",
            "default": "API_IMPORT",
            "description": "A label identifying where the payment comes from (e.g. \"HELLOASSO\", \"MY_OLD_SOFTWARE\"). Upper-cased. Defaults to \"API_IMPORT\"."
          },
          "externalId": {
            "type": "string",
            "description": "Your own stable reference for this payment in the source system. When provided, the import is IDEMPOTENT: re-sending the same externalId updates the same payment instead of creating a duplicate (safe to retry / re-run a migration). Without it, every call creates a new payment."
          }
        }
      },
      "PaymentRefundRequest": {
        "type": "object",
        "properties": {
          "reason": {
            "type": "string",
            "enum": [
              "requested_by_customer",
              "duplicate",
              "fraudulent"
            ],
            "default": "requested_by_customer"
          },
          "message": {
            "type": "string",
            "description": "Optional internal note recorded in the refund audit."
          },
          "pauseAbo": {
            "type": "boolean",
            "default": false,
            "description": "Also pause the linked subscription, when one exists."
          }
        }
      },
      "PaymentRefundResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "pending": {
            "type": "boolean",
            "description": "The refund outcome is unconfirmed. Verify it with the provider before retrying."
          },
          "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"
      }
    }
  }
}
```
