**גרסאות API** · **V2 (Latest)** · [V1](/integrations/v1/docs?lang=he)

# Payments

OpenAPI 3.0.3 · API 2.0.0

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

Donations and payments

## פעולות

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

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```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",
    "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.",
    "example": "commande-1234"
  },
  "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."
}
```

### תגובות

#### 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`. Prepares a one-time payment request 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 forbidden as input; the authenticated organisation is supplied by the server. `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. Creating a hosted link or obtaining an embedded checkout result is not proof of collection. Recurring creation is unavailable here; use prepare_subscription for the supported GENERAL monthly hosted Stripe flow. Updating an existing payment is unavailable here, including donor identity completion. Only false or omission is admitted for config.abo and config.update. The response is the direct payment result, not a data-wrapped resource.

### אימות

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

### הרשאות נדרשות

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

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "config": {
            "$ref": "#/components/schemas/UnisoftRequest_414e1860ccd141107a40"
          }
        },
        "required": [
          "config"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Direct payment request result.",
  "content": {
    "application/json": {
      "schema": {
        "$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). The target association and currency must agree with the canonical target context. Contradictions return IMPORT_TARGET_FINANCE_MISMATCH; an unproven target context returns IMPORT_TARGET_FINANCE_UNAVAILABLE, before persistence or cache recalculation.

### אימות

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

### הרשאות נדרשות

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

### גוף הבקשה

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

### תגובות

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

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "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}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### תגובות

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

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "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}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### גוף הבקשה

```json
{
  "required": false,
  "content": {
    "application/json": {
      "schema": {
        "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",
            "description": "Also pause the linked subscription, when one exists.",
            "default": false
          }
        },
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

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

## GET /paiements/{id}/status

Read the recorded state of a payment attempt

`get_paiement_status`

Requires paiements:read. Reads one current database record in the authenticated organisation and campaign restriction. Includes attempts hidden by the historical completed-payment list. Accepts only the payment id: query parameters and non-empty request bodies are rejected. Missing, deleted and out-of-scope payments all return 404. The result is an allowlisted observation, not a bank verification, a retry instruction or a receipt-readiness check. Interpret the returned fields separately: state is the stored code; phase maps INIT to PREPARED, pending states to PROCESSING, COMPLETED to RECORDED_COMPLETED, REFUNDED to RECORDED_REFUNDED and unrecognised codes to UNKNOWN. RECORDED_COMPLETED can be an Axepta authorisation before capture or a historical imported collection; it does not prove capture, bank settlement or payout. amountMinor is this payment's amount in minor units (5000 for EUR 50), not the subscription's nominal amount. Null money or currency stays unknown. imported is the explicit stored boolean, or null when absent/invalid. donorInformationStatus interprets finalized independently of financial state and receipt issuance; COMPLETED can coexist with INCOMPLETE. recordedAt is payment datetime (preparation time online or supplied manual/import business date), not bank settlement or receipt issue time. Never infer expiry from age or permission to retry from this observation. No provider call, debit, refund, subscription execution or business-state mutation occurs. The shared authentication layer may update API-key usage telemetry.

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "Unisoft payment UUID returned by the payment flow.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Recorded payment status; inspect phase, imported and donorInformationStatus separately.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentStatusResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID, unexpected query parameters or non-empty request body.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid API key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing paiements:read scope or disabled organisation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Payment missing, deleted or outside the authorised organisation/campaign.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Status could not be read. No financial operation was attempted.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

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

## GET /paiements/{id}/context

Read the dated observations and authorised relations of a payment

`get_paiement_context`

Requires ALL of paiements:read, contacts:read, promesses:read, abonnements:read, forms_submit:read and receipts:read; a missing scope returns 403 without returning payment or relation data. Accepts only a payment UUID; query parameters and non-empty bodies are rejected. Missing, deleted, foreign and campaign-inaccessible payments return the same 404. Each linked resource is independently readmitted in the authenticated organisation and campaign restriction; a stored reference never grants access. Contact and submission references are withheld for every campaign-limited key, as reported in campaignRestrictedDomains, because their own campaign membership cannot be established. FORM typeId refers to a submission, abo to a subscription. Null/empty relations mean no admissible relation was returned and do not prove historical absence. Pledge references identify targets or stored allocations without computing balances, prorata or subscription schedules; explicit empty frozen allocation maps suppress legacy dettes references. Documentary references require receipts:read and current admission of their payment, including all grouped/annual members. Timeline contains only supported stored dates: payment.datetime, latest refund.createdAt/updatedAt and admitted document.datetime, sorted ascending with deterministic ties. It is partial and never reconstructs transitions, every refund attempt, provider events, bank settlement, capture, delivery or expiry. Online datetime commonly records preparation; manual/import datetime can be the supplied business date. Stored status semantics remain unchanged: COMPLETED can be an Axepta authorisation before capture or a historical import; finalized describes donor information independently. Unknown money/currency/dates remain unknown. More than 200 pledge references or an oversized documentary context returns 409 without a partial graph. No debit, retry, provider call, document emission/delivery, reconciliation or persistent schedule initialisation occurs. Authentication may update API-key usage telemetry.

### אימות

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

### הרשאות נדרשות

```json
{
  "accepted": "paiements:read",
  "additional": [
    "contacts:read",
    "promesses:read",
    "abonnements:read",
    "forms_submit:read",
    "receipts:read"
  ]
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "Unisoft payment UUID returned by the payment flow.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Allowlisted payment observation, dated events and independently authorised references.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentContextResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID, unexpected query parameters or non-empty request body.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid API key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "At least one required domain read scope is missing, or the organisation is disabled.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Payment missing, deleted or outside the authorised organisation/campaign.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "PAYMENT_CONTEXT_LIMIT_EXCEEDED: the stored relation graph exceeds the safe read bound; no partial graph is returned.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Context could not be read. No financial or documentary operation was attempted.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "paiements:read",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "promesses:read",
    "abonnements:read",
    "forms_submit:read",
    "receipts:read"
  ],
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /payment-methods

Inspect configured payment choices for an association and target

`list_payment_methods`

Requires paiements:read. Read current local checkout configuration for one legal association, effective currency and payment allocation type. Supply assoc (MAIN or association UUID), currency (three letters), type (GENERAL, FORM, DETTE, CAISSE or CAMPAGNE), typeId for every type except GENERAL, and optional recurring (default false). FORM targets a submission and independently verifies its parent form. Target ownership, legal association, currency and campaign restrictions are checked before configuration is disclosed; campaign-limited keys can only use CAMPAGNE with an explicitly allowed typeId. Target currencies and association references must agree: no silent MAIN fallback or conversion. Virtual campaign display currencies are refused. A target refused by the current campaign publication/lifecycle owner is INELIGIBLE. AVAILABLE describes only observed local configuration: it is not payment acceptance, valid credentials or a reusable method. The current selection owner resolves provider priority without persisting a selection. Missing merchant references remain INDETERMINATE; a requested option that falls back to another choice is UNAVAILABLE. Final eligibility is always INDETERMINATE or an observed INELIGIBLE refusal because amount, donor, allocations, schedule, stock/checkout and provider requirements are not supplied. Read prerequisites for required follow-up; never infer permission to charge or retry. Wallets additionally require browser checks; SEPA_XML configuration requires its separate runtime admission and mandate/schedule and is not selected by the card owner. No debit, checkout/link creation, mandate creation, provider call, credential check, reconciliation or business write occurs; shared authentication may update API-key usage telemetry. No provider configuration ID, account reference, reusable method, secret or private target snapshot is returned. Unknown query fields, repeated/structured values and non-empty request bodies are rejected. SERVICE, LIVRET, installments and offline methods are outside this read.

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```json
{
  "name": "assoc",
  "in": "query",
  "required": true,
  "description": "Legal association: MAIN or an association UUID from list_associations.",
  "schema": {
    "type": "string",
    "pattern": "^(MAIN|[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})$"
  }
}
```

```json
{
  "name": "currency",
  "in": "query",
  "required": true,
  "description": "Effective three-letter collection currency; case-insensitive and normalized to lowercase.",
  "schema": {
    "type": "string",
    "pattern": "^[A-Za-z]{3}$"
  }
}
```

```json
{
  "name": "type",
  "in": "query",
  "required": true,
  "description": "Business allocation type. SERVICE and LIVRET are excluded.",
  "schema": {
    "type": "string",
    "enum": [
      "GENERAL",
      "FORM",
      "DETTE",
      "CAISSE",
      "CAMPAGNE"
    ]
  }
}
```

```json
{
  "name": "typeId",
  "in": "query",
  "description": "Required for FORM (submission UUID), DETTE (pledge), CAISSE or CAMPAGNE; forbidden for GENERAL.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "recurring",
  "in": "query",
  "description": "Recurring intent; default false. REST accepts only literal true or false, and MCP a boolean.",
  "schema": {
    "type": "boolean",
    "default": false
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Local configured choices with separate selection, eligibility and missing prerequisites.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentMethodsResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid/unknown query fields, association, currency, type, target, recurring or non-empty body.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentMethodsErrorResponse"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentMethodsErrorResponse"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing paiements:read or disabled organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentMethodsErrorResponse"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Association, target, parent or linked campaign missing, deleted, foreign or outside allowed campaigns.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentMethodsErrorResponse"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Stored configuration is invalid, association currency is unknown, or target association resolution is indeterminate. Complete or correct local configuration before relying on this read.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentMethodsErrorResponse"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Association/target/currency mismatch or VIRTUAL_CURRENCY_DISPLAY_ONLY. Use the target's effective collection association and currency.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentMethodsErrorResponse"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Configuration read failed; no payment operation was attempted.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentMethodsErrorResponse"
      }
    }
  }
}
```

### OpenAPI

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

## GET /paiements/{id}/refund-history

Read a payment's recorded refund status and partial history

`get_paiement_refund_history`

Requires paiements:read. Reads only the stored payment and its existing PAIEMENT_REFUND audits, within the authenticated organisation and campaign restriction. Accepts only the payment UUID: query parameters and non-empty request bodies are rejected. Missing, deleted and out-of-scope payments all return 404. latestAttempt exposes only the latest retained snapshot: state, positive attemptNumber, reservedAt and updatedAt; absent or invalid values stay null. A new attempt replaces previous snapshot data. status is NOT_RECORDED only when neither a retained refund snapshot nor a refund audit was found; absence does not prove failure or that no refund occurred. PENDING is a paired REFUND_PENDING/PENDING reservation without a stored error; pending errors, inconsistent pairs and unknown states yield UNKNOWN. RECORDED_SUCCEEDED is the REFUNDED/SUCCEEDED pair; RECORDED_FAILED and RECORDED_CANCELED require the COMPLETED/FAILED or COMPLETED/CANCELED pair. These are recorded business outcomes, not a bank verification: the current owner can record SUCCEEDED even for a provider response PENDING. Neither a successful audit nor the latest status proves bank settlement, receipt deletion, subscription pause or permission to replay. history contains only existing REFUND_RECORDED audit events, newest stored datetime first, capped at 100 with hasMore. Those audits are best effort, can predate a later failure, and do not preserve all reservations, failures, confirmations or attempt numbers. historyCompleteness is always PARTIAL, including for an empty list or hasMore=false. Dates are stored ISO instants or null, never inferred from age. UNKNOWN and PENDING require verification through the existing authorised business process before any further attempt; this read never authorises or triggers a replay. No partial-refund support, provider polling, reconciliation, refund, debit or business-state mutation occurs. Shared authentication may update API-key usage telemetry. Reasons, comments, actors, raw errors, private configuration, reusable payment methods and provider references are excluded.

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "Unisoft payment UUID whose recorded refund is being inspected.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Recorded refund observation with explicitly partial history.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentRefundHistoryResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, UNEXPECTED_QUERY_PARAMETERS or UNEXPECTED_REQUEST_BODY.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid API key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing paiements:read scope or disabled organisation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Payment missing, deleted or outside the authorised organisation/campaign.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Stored refund observation could not be read. No refund was attempted.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

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

## GET /paiements/{id}/finance

Read recorded payment fees and net with availability limits

`get_paiement_finance`

Requires paiements:read. Reads one stored payment in the authenticated organisation and allowed campaigns, including incomplete attempts. Accepts only its UUID; unknown query parameters and non-empty bodies are rejected. Missing, deleted and out-of-scope payments all return 404 NOT_FOUND. grossMinor is amount in the recorded payment currency's minor units: 5000 is EUR 50 for eur. bankFeesMinor and serviceFeesMinor are raw recorded bankFees/orgfees minor-unit numbers; their currency is unproven and is always null in bankFeesCurrency/serviceFeesCurrency. Stripe can store settlement-currency fees different from the payment currency. Never assign the payment currency to these fees or subtract nonzero fees across unproven currencies. Each fee basis is ESTIMATED when a PAYGREEN estimateFees component matches, RECORDED_WITHOUT_PROVENANCE for another valid stored fee, or UNKNOWN for an absent/invalid fee; no recorded fee is certified final. Missing or invalid amounts remain null; missing fees never imply zero. totalFeesMinor is zero and netMinor equals grossMinor only when both fees are explicitly zero and the gross/payment currency are known. Otherwise netAvailability is UNKNOWN with a prerequisite reason such as FEE_CURRENCY_NOT_RECORDED. AVAILABLE is a net from recorded zero fees, not bank receipt or proof of final fees. No currency, rate, refund/dispute adjustment or financial state is inferred. COMPLETED can be an authorisation before capture. This net is not provider settlement, payout or bank receipt. Converted data is UNAVAILABLE/HISTORICAL_CONVERSION_PROVENANCE_NOT_RECORDED because historical target currency/rate provenance is missing and converted fees may contain substituted zeroes. payout and reconciliation remain UNAVAILABLE/AUTHORIZED_OWNER_ADAPTER_REQUIRED in this operation only. For the separately authorised recorded treasury projection, use get_payment_treasury and get_payment_treasury_payouts with payment_treasury:read and current genuine creator-ADMIN/association authority; supported source and merchant conditions still apply. UNAVAILABLE never means no payout or unmatched. A payment/provider reference alone grants no authority. This ordinary financial reader cannot refresh or expose those separate projections. No bank/provider request, synchronisation, reconciliation, debit, refund or business mutation occurs; shared authentication may update API-key usage telemetry. Database failures return 500 INTERNAL_ERROR without private details.

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "Unisoft payment UUID.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Recorded fee arithmetic and explicit unavailable capabilities.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentFinanceResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, UNEXPECTED_QUERY_PARAMETERS or UNEXPECTED_REQUEST_BODY.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid API key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing paiements:read scope or disabled organisation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Payment missing, deleted or outside the organisation/campaign scope.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. No financial operation was attempted.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

### OpenAPI

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

## GET /paiements/{id}/incidents

Read persisted payment disputes and rejections

`get_paiement_incidents`

Required scope: `paiements:read`. Reads the latest persisted incident snapshot per supported source for one payment in the authenticated organisation and authorised campaign; includes failed attempts. This is partial stored coverage, never an exhaustive incident history or bank verification. Only the payment UUID is accepted: unknown query parameters and non-empty request bodies are rejected. Missing, deleted and out-of-scope payments return the same 404. Supported providers are the explicit Stripe card/wallet/SEPA families, GOCARDLESS and SEPA_XML; other platforms return UNSUPPORTED with no sources. PARTIAL_PERSISTED always remains partial, even when sources are empty or NOT_RECORDED. A provider error message, payment failure state, age or browser return alone never proves a dispute. Source observations are RECORDED, NOT_RECORDED (no selected persisted trace), UNRECOGNISED (trace cannot be safely interpreted) or UNAVAILABLE (Stripe treasury requires a separate banking/association authorisation adapter and is not read by this operation). Stripe debit_disputed is a dispute only for Stripe SEPA; card_declined is a rejection. GoCardless charged_back, refund_requested or authorisation_disputed prove a dispute; a bank reason code alone does not. SEPA_XML uses sepaXml.failure, verified against this payment and its current collection, with REJECT, RETURN, DISPUTE or REFUND types. Stripe treasury corrections and card-dispute histories are unavailable here: paiements:read and a stored paymentId do not grant the separate banking/association access required by that owner. For separately authorised recorded treasury corrections, use get_payment_treasury_corrections with payment_treasury:read and its current creator-ADMIN/association, account and source admission. This persisted-incidents reader does not include that separate projection; do not infer a card dispute from a payment error. These separate sources can describe the same incident and must not be counted or summed together. Only explicit code/reason/status allowlists are published; an unknown or absent reason is UNKNOWN, never copied from a raw message. providerStatus is a whitelisted provider/event code or null; recordedPaymentState is a whitelisted current Unisoft state or null and does not describe the provider dispute lifecycle; resolution is RESOLVED only for an explicit valid SEPA_XML resolvedAt, otherwise UNKNOWN. Dates are stored ISO instants or null: occurredAt is the stored incident event/creation time (not payment preparation or bank settlement); observedAt is null because no additional provider observation is read; resolvedAt is the owner's explicit SEPA resolution instant. There is no freshness guarantee and no permission to retry, restore a mandate or resume an abonnement. No provider call, polling, synchronization, reconciliation, debit or business write occurs; authentication may record API-key usage telemetry.

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "Unisoft payment attempt UUID.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Partial persisted observations, including explicit unknown and unsupported states.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentIncidentsResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, UNEXPECTED_QUERY_PARAMETERS or UNEXPECTED_REQUEST_BODY.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string",
            "enum": [
              "id"
            ]
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string",
            "enum": [
              "id"
            ]
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing paiements:read scope or disabled organisation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string",
            "enum": [
              "id"
            ]
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND: payment missing, deleted or outside the organisation/campaign.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string",
            "enum": [
              "id"
            ]
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR: persisted observation could not be read; no provider operation was attempted.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string",
            "enum": [
              "id"
            ]
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

### OpenAPI

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

## GET /paiements/export

Export recorded payments and qualified period totals

`export_paiements`

Requires paiements:read. Read-only JSON export of the authenticated organisation's recorded payments, restricted independently to authorised campaigns for a campaign-limited key (type must be CAMPAGNE). Required from/to are RFC 3339 instants with an explicit timezone and at most millisecond precision (zero to three fractional digits), from inclusive and to exclusive, at most 31 elapsed days. Filters associationId (MAIN or UUID), instrument and lowercase currency are exact and combined with AND. No arbitrary filter, pipeline, state selection, donor identity or non-empty body is accepted. All recorded states, imports, refund states, in-kind records and technical ABO_PAUSE traces are included; logically deleted records are excluded. Only supported stored datetime values can fall in the period: BSON dates, safe integer epoch milliseconds, or valid RFC 3339 strings with an explicit timezone and at most three fractional digits. Missing/invalid dates are outside this export and their count remains unknown. datetime usually means preparation time online or the supplied manual/import business date, never a guaranteed bank settlement date. Results sort by normalised datetime descending then payment UUID descending, with simple binary collation. The opaque cursor is bound to organisation, campaign restriction and filters; reuse it unchanged with the same filters. At most 10000 matching records per window and 200 per page (50 by default). A larger window returns 422 EXPORT_WINDOW_TOO_LARGE with no partial totals: split the period. A malformed or duplicate payment identity returns 409 INVALID_EXPORT_RECORDS. Each page repeats totals over the whole current filtered period, not just that page: never sum repeated totals across pages. Totals separate association, instrument, currency, exact stored state, explicit imported marker (including unknown null) and recordKind. They sum nominal recorded minor-unit amounts only, not bank receipts, payouts or distinct subscription occurrences. COMPLETED can be an Axepta authorisation before capture. REFUNDED retains its original positive nominal amount; refund movements have no period attribution here and no refund subtraction, fee netting or currency conversion occurs. Unknown amounts/currencies remain null, invalid-amount counts are explicit and unsafe sums return OVERFLOW. NATURE and ABO_PAUSE are separate from monetary records; even MONETARY_RECORD proves no receipt of funds. The projection excludes PII, free text, reusable payment methods, provider references and private snapshots. There is no snapshot across pages: insertions, changes or deletion may change records and totals. This read performs no provider call, debit, refund, reconciliation, calendar initialisation or document issuance; authentication may update API-key usage telemetry. Database work has a five-second server limit; on 500 INTERNAL_ERROR retry later or narrow the period without assuming an empty result.

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```json
{
  "name": "from",
  "in": "query",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^\\d{4}-\\d{2}-\\d{2}T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?(?:Z|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$",
    "format": "date-time"
  },
  "description": "Inclusive lower bound on payment datetime; RFC 3339 instant with explicit timezone and at most three fractional digits. Use an elapsed period of at most 31 days."
}
```

```json
{
  "name": "to",
  "in": "query",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^\\d{4}-\\d{2}-\\d{2}T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?(?:Z|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$",
    "format": "date-time"
  },
  "description": "Exclusive upper bound on payment datetime, later than from. Explicit timezone and at most three fractional digits required; adjacent periods may share this boundary without overlap."
}
```

```json
{
  "name": "associationId",
  "in": "query",
  "schema": {
    "type": "string",
    "maxLength": 36
  },
  "description": "Exact stored beneficiary association: MAIN or association UUID. Omit to include all associations, including unknown historical values."
}
```

```json
{
  "name": "instrument",
  "in": "query",
  "schema": {
    "type": "string",
    "enum": [
      "CASH",
      "CHEQUE",
      "VIREMENT",
      "PRELEVEMENT",
      "CB",
      "NATURE"
    ]
  },
  "description": "Exact stored instrument: CASH, CHEQUE, VIREMENT, PRELEVEMENT, CB or NATURE. Omit to include every instrument, including unknown historical values."
}
```

```json
{
  "name": "currency",
  "in": "query",
  "schema": {
    "type": "string",
    "pattern": "^[a-z]{3}$"
  },
  "description": "Exact stored three-letter currency after lowercase normalisation, such as eur. Omit to include separate totals for every currency and unknown currency."
}
```

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 200,
    "default": 50
  },
  "description": "Maximum payment records in this page. Does not limit the period totals."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "maxLength": 2048
  },
  "description": "Opaque nextCursor from this export with the same organisation, campaign restriction and period/filters. Do not use the ordinary payment-list cursor."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Allowlisted payment page and qualified totals for the whole current filtered period.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentExportResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid or missing period, period longer than 31 elapsed days, invalid filter/limit/cursor, unexpected query parameter or non-empty body.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentExportError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid API key.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentExportError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing paiements:read scope or disabled organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentExportError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_EXPORT_RECORDS: a malformed date/identity or duplicate identity prevents stable pagination. No partial export or total is returned.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentExportError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "EXPORT_WINDOW_TOO_LARGE: more than 10000 records match. Split the period; no partial export or total is returned.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentExportError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR: export could not be read, including the five-second database limit. Retry later or narrow the period; no financial operation was attempted.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentExportError"
      }
    }
  }
}
```

### OpenAPI

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

## GET /paiements/{id}/treasury

Read recorded settlement fees, net and capture observations

`get_payment_treasury`

Requires paiements:read AND explicitly granted payment_treasury:read on both the authenticated and current persisted key. The exact live key must have persisted createdBy pointing to a currently enabled, unexpired real ADMIN access of the same organisation with full access to every association of the merchant account. No synthetic administrator is constructed. ROOT, keys without a real creator, onlyAttr, campaign-restricted keys, unknown modes, ambiguous references, shared cross-organisation merchants and stale/inconsistent bindings are refused. Account mode must be explicitly known on the payment or wallet snapshot; historical mode is never guessed. These are persisted native Stripe Treasury observations, not a live provider/bank read. No SDK, secrets, queue, synchronization, financial mutation or message is exposed. All monetary fields are signed integer Stripe minor units with an explicit currency and exponent (0 or 2); never assume every currency has cents, substitute EUR/zero, combine presentment and settlement currencies, or calculate an undocumented FX rate. A missing observation does not prove that funds, disputes or payouts do not exist. COMPLETED alone does not prove capture or bank receipt. providerRefreshed and bankVerified are always false. Authority and local references are read again before returning data. presentment is the payment/charge denomination; settlement includes the native balanced amount, fee and net in its independently recorded settlement currency. Nonzero fees without this currency are refused. The two denominations can differ. The native maturity state and observation time qualify availability; AVAILABLE is not a payout or bank deposit. captured=null is unknown, not false. No payout amount is allocated from a pooled merchant balance. Read get_payment_treasury_payouts for a published verified composition and get_payment_treasury_corrections for separately recorded corrections.

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified persisted Treasury observations.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentTreasurySnapshotResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Fixed authority, historical-data or query error.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Fixed authority, historical-data or query error.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Fixed authority, historical-data or query error.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Fixed authority, historical-data or query error.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Fixed authority, historical-data or query error.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Fixed authority, historical-data or query error.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "paiements:read",
  "x-unisoft-additional-scopes": [
    "payment_treasury:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "idempotent": true,
    "destructive": false,
    "warn": false
  }
}
```

## GET /paiements/{id}/treasury/corrections

Read recorded Stripe refunds and disputes linked to this payment

`get_payment_treasury_corrections`

Requires paiements:read AND explicitly granted payment_treasury:read on both the authenticated and current persisted key. The exact live key must have persisted createdBy pointing to a currently enabled, unexpired real ADMIN access of the same organisation with full access to every association of the merchant account. No synthetic administrator is constructed. ROOT, keys without a real creator, onlyAttr, campaign-restricted keys, unknown modes, ambiguous references, shared cross-organisation merchants and stale/inconsistent bindings are refused. Account mode must be explicitly known on the payment or wallet snapshot; historical mode is never guessed. These are persisted native Stripe Treasury observations, not a live provider/bank read. No SDK, secrets, queue, synchronization, financial mutation or message is exposed. All monetary fields are signed integer Stripe minor units with an explicit currency and exponent (0 or 2); never assume every currency has cents, substitute EUR/zero, combine presentment and settlement currencies, or calculate an undocumented FX rate. A missing observation does not prove that funds, disputes or payouts do not exist. COMPLETED alone does not prove capture or bank receipt. providerRefreshed and bankVerified are always false. Authority and local references are read again before returning data. Native correction relations must match the current merchant/mode, local reference and charge/paymentIntent ancestry, not just a historical paymentId. type distinguishes refund from dispute; neither is an instruction to reimburse or retry. reason is always null because the native correction producer does not persist the dispute reason; refund failure/pending reasons are not substituted. Status is the recorded provider status with observedAt/stale. Pagination current/pageSize, at most 1000 relevant relations. Empty data is absence of admitted persisted relations only, not proof of no dispute.

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "current",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100000,
    "default": 1
  }
}
```

```json
{
  "name": "pageSize",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 25
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified persisted Treasury observations.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentTreasuryCorrectionPageResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Fixed authority, historical-data or query error.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Fixed authority, historical-data or query error.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Fixed authority, historical-data or query error.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Fixed authority, historical-data or query error.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Fixed authority, historical-data or query error.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Fixed authority, historical-data or query error.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "paiements:read",
  "x-unisoft-additional-scopes": [
    "payment_treasury:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "idempotent": true,
    "destructive": false,
    "warn": false
  }
}
```

## GET /paiements/{id}/treasury/payouts

Read verified payout composition relations and recorded bank matching

`get_payment_treasury_payouts`

Requires paiements:read AND explicitly granted payment_treasury:read on both the authenticated and current persisted key. The exact live key must have persisted createdBy pointing to a currently enabled, unexpired real ADMIN access of the same organisation with full access to every association of the merchant account. No synthetic administrator is constructed. ROOT, keys without a real creator, onlyAttr, campaign-restricted keys, unknown modes, ambiguous references, shared cross-organisation merchants and stale/inconsistent bindings are refused. Account mode must be explicitly known on the payment or wallet snapshot; historical mode is never guessed. These are persisted native Stripe Treasury observations, not a live provider/bank read. No SDK, secrets, queue, synchronization, financial mutation or message is exposed. All monetary fields are signed integer Stripe minor units with an explicit currency and exponent (0 or 2); never assume every currency has cents, substitute EUR/zero, combine presentment and settlement currencies, or calculate an undocumented FX rate. A missing observation does not prove that funds, disputes or payouts do not exist. COMPLETED alone does not prove capture or bank receipt. providerRefreshed and bankVerified are always false. Authority and local references are read again before returning data. Uses only the native published VERIFIED composition version joined to the current payment ancestry. net is this transaction contribution, not the entire payout nor another attribution from merchant balance. role PAYMENT can identify an initial payment contribution; REFUND/DISPUTE/FEES/OTHER must not be presented as its initial payout. A recorded payout status paid is not bank confirmation. bank.state is the native reread statement comparison: CONFIRMED describes a persisted matching statement observation, UNMATCHED means no admitted match, CONFLICT means disagreement. It is not a live verification and no bank identity, statement label, destination or account number is returned. Unknown/unpublished/manual/legacy composition is not fabricated from payment age or references. Pagination current/pageSize, at most 1000 native relations.

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "current",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100000,
    "default": 1
  }
}
```

```json
{
  "name": "pageSize",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 25
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified persisted Treasury observations.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentTreasuryPayoutPageResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Fixed authority, historical-data or query error.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Fixed authority, historical-data or query error.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Fixed authority, historical-data or query error.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Fixed authority, historical-data or query error.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Fixed authority, historical-data or query error.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Fixed authority, historical-data or query error.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "paiements:read",
  "x-unisoft-additional-scopes": [
    "payment_treasury:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "idempotent": true,
    "destructive": false,
    "warn": false
  }
}
```

## POST /paiements/{id}/allocations/preview

Preview a payment payer and pledge allocation change

`preview_payment_allocations`

Requires paiements:read AND promesses:read AND contacts:read. Pure read of one globally unique COMPLETED one-off GENERAL payment with known positive minor amount, association, lower-case currency and existing contact. No campaign-restricted principal, subscription payment, refund, legacy target or ambiguous historical allocation is admitted. dettes is the complete replacement list, maximum 50 unique pledge ids, with each montant in major units; [] detaches all. Optional contactId changes the CRM relation only; it does not rewrite donor/billing identity, issued documents or receiptPolicySnapshot. Selected pledges must belong to the resulting contact and same organisation/association/currency. Native debt calculation determines remaining balances and active subscription coverage; unknown currencies, fractional history without frozen per-payment allocation maps, duplicate references and more than 10000 relevant rows are refused, never replaced with zero/EUR. All amount, balance and fiscal response fields are integer minor units; dettes[].montant remains major. expectedRevision binds the payment, relevant ledger, pledges, issuer and exact proposed list/contact. It is an optimistic snapshot, not a reservation. fiscal.recordedAmount preserves historical fiscal authority; expectedForNewAllocation only describes the policy of the proposed accounting move. exception=true requires explicit acknowledgment during apply and never rewrites fiscal documents. No CRM, cache write, provider, receipt, debit or message runs.

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "dettes": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "montant": {
                  "type": "number",
                  "description": "Positive major units, exactly two decimals; response amounts use integer minor units.",
                  "minimum": 0,
                  "exclusiveMinimum": true
                }
              },
              "required": [
                "id",
                "montant"
              ],
              "additionalProperties": false
            }
          },
          "contactId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "pattern": "^\\S(?:.*\\S)?$",
            "description": "Optional exact existing contact. Omission preserves the payer relation. All selected pledges must belong to the resulting contact. Billing identity and issued documents are never rewritten."
          }
        },
        "required": [
          "dettes"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified accounting preview or command result.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentAllocationPreviewResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Fixed refusal or uncertainty code.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Fixed refusal or uncertainty code.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Fixed refusal or uncertainty code.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Fixed refusal or uncertainty code.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Fixed refusal or uncertainty code.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Fixed refusal or uncertainty code.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "paiements:read",
  "x-unisoft-additional-scopes": [
    "promesses:read",
    "contacts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "idempotent": true,
    "destructive": false,
    "warn": false
  }
}
```

## POST /paiements/{id}/allocations/apply

Apply a reviewed accounting allocation with a stable command key

`apply_payment_allocations`

Requires paiements:write AND explicitly granted payment_allocations:write AND promesses:write AND contacts:write. First call preview_payment_allocations with the complete desired dettes/contactId, then supply exactly that list/contact, its expectedRevision, a stable idempotency UUID and explicit confirmFiscalException. [] means detach all, not omission/no change. No automatic fiscal exception acknowledgment: obtain the operator decision when preview fiscal.exception is true. Revalidates tenant, contact, currency, native balances and full snapshot under persistent external payment/pledge locks before a compare-and-set update. Locks serialize these external allocation commands only; internal editors and incoming payment callbacks do not honor them. A changed observed ledger is refused; no global transactional or bank-settlement guarantee is asserted. Writes dettes and minor-unit pledgeAllocations, preserves all fiscal/billing snapshots and document references, records an API-attributed audit and the native declaration/suggestion resolution states, then refreshes debt caches and tags a changed contact. No charge, provider cancellation, document issuance, email or implicit contact creation. Warnings identify nonfinancial cache/tag follow-up without undoing an acknowledged accounting write. The atomic principal/organisation/UUID journal precedes effects. Same key/body reads its outcome and never repeats apply. PENDING/UNCERTAIN or a lost write acknowledgment never permits a new key, an import, or automatic replay; uncertain mutation locks have no timeout. SUCCEEDED/ACCOUNTING_UPDATED confirms the compare-and-set accounting write only, not bank verification or document correction. A contact change additionally checks the external contact mutation fence on the exact admitted old/new contact UUIDs for REFERENCE and LIFECYCLE, and only the new contact for TAGS. The check follows receipt replay and precedes the accounting CAS. CONTACT_MUTATION_BLOCKED (409) or CONTACT_MUTATION_FENCE_UNAVAILABLE (503) before the CAS refuses the new write. Pure preview, receipt replay and allocation without a contact change do not manufacture CRM effects. If a conflicting fence appears only after an acknowledged accounting CAS, contact tagging is skipped with CONTACT_TAG_PENDING; the known accounting result is preserved. No automatic tagging retry or alternate payment is permitted.

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### גוף הבקשה

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

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified accounting preview or command result.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentAllocationCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Fixed refusal or uncertainty code.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Fixed refusal or uncertainty code.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Fixed refusal or uncertainty code.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Fixed refusal or uncertainty code.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Fixed refusal or uncertainty code.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Fixed refusal or uncertainty code.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Fixed refusal or uncertainty code.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "paiements:write",
  "x-unisoft-additional-scopes": [
    "payment_allocations:write",
    "promesses:write",
    "contacts:write"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "idempotent": true,
    "destructive": false,
    "warn": true
  }
}
```

## GET /paiements/allocation-requests/{requestId}

Read the outcome of an accounting allocation command

`get_payment_allocation_request`

Requires paiements:write AND payment_allocations:write AND promesses:write AND contacts:write. Pure read of the same organisation/API-principal journal with the original idempotency UUID. No payment, CRM, cache, receipt or provider mutation. PENDING/UNCERTAIN may include committed effects and retained locks; never replay automatically or replace the key. SUCCEEDED/ACCOUNTING_UPDATED describes accounting only. receiptSnapshotChanged and bankVerified remain false. No raw historical identity, provider token or exception is returned.

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```json
{
  "name": "requestId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified accounting preview or command result.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentAllocationCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Fixed refusal or uncertainty code.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Fixed refusal or uncertainty code.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Fixed refusal or uncertainty code.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Fixed refusal or uncertainty code.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Fixed refusal or uncertainty code.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Fixed refusal or uncertainty code.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "paiements:write",
  "x-unisoft-additional-scopes": [
    "payment_allocations:write",
    "promesses:write",
    "contacts:write"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "idempotent": true,
    "destructive": false,
    "warn": false
  }
}
```

## POST /paiements/manual

Record externally observed funds as a manual payment

`record_manual_payment`

Requires paiements:write AND explicitly granted payment_manual:write AND contacts:write. This records an operator assertion of observed funds, not a payment link or historical import. Supply confirmation FUNDS_OBSERVED, montant in major units, an explicit real date, existing contactId, legal assoc/devise, method, complete donor/billing identity, cerfa and dontSendReceipt. It marks the native manual payment COMPLETED, non-imported and finalized; this is not proof of bank settlement. Native CRM tagging/synchronization runs and may fill empty contact identity or billing fields. The normal asynchronous fiscal/ordinary document owners can generate documents and may email when dontSendReceipt=false; SUCCEEDED does not prove issuance or delivery. The existing contact must be unique and belong to this organisation; no implicit contact matching or creation. Billing address/postal/city/country and the selected personal or company identity are required. No fiscal eligibility is invented. GENERAL requires no typeId; CAISSE/CAMPAGNE require a known exact target whose association/currency match. Campaign-restricted keys can only record their granted campaigns. Campaign recording uses its native stock lock with explicit productAction NONE: no product purchase, inventory allocation or instalment is sold. FORM, DETTE, recurring, legacy SERVICE and pledge splits are not admitted by this operation; they need their dedicated financial/validation owners. Methods describe observed instruments only: CB does not charge a card and PRELEVEMENT does not create a mandate. An atomic organisation/API-principal/UUID journal is claimed before effects; the same key never re-executes CRM or insertion. Reuse the same body/key to read its outcome after a lost response. PENDING and UNCERTAIN can contain effects and never authorize automatic retry, a new key, or another import. Read the journal and resolve uncertainty explicitly. No internal administrator identity or access is fabricated. CRM effects require the exact admitted contact UUID. After checking an existing receipt replay, the external contact mutation fence is checked before the native CRM owners for CORE, COORDINATES, TAGS and LIFECYCLE effects. A retained conflicting CRM command refuses a new recording with CONTACT_MUTATION_BLOCKED (409); an unprovable fence returns CONTACT_MUTATION_FENCE_UNAVAILABLE (503). No new payment or contact writer runs after these preflight refusals. Receipt replay remains read-only. A fence appearing after a partial native effect leaves the command UNCERTAIN and never authorizes a new key. This is passive admission, not a transaction with internal writers.

### אימות

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

### הרשאות נדרשות

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

### גוף הבקשה

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

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified manual recording command journal.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentManualResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Fixed admission or command error; no raw provider exception.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Fixed admission or command error; no raw provider exception.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Fixed admission or command error; no raw provider exception.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Fixed admission or command error; no raw provider exception.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Fixed admission or command error; no raw provider exception.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Fixed admission or command error; no raw provider exception.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Fixed admission or command error; no raw provider exception.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "paiements:write",
  "x-unisoft-additional-scopes": [
    "payment_manual:write",
    "contacts:write"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "idempotent": true,
    "destructive": false,
    "warn": true
  }
}
```

## GET /paiements/manual/requests/{requestId}

Read a manual payment recording outcome

`get_manual_payment_request`

Requires paiements:write AND payment_manual:write AND contacts:write. Read only, with the original idempotency UUID, same organisation and same API principal. Rechecks campaign grants. No CRM, document, bank or provider action. SUCCEEDED/MANUALLY_RECORDED acknowledges recorded manual funds only; bankVerified is always false. PENDING may mean an ongoing or interrupted execution; UNCERTAIN means effects cannot safely be ruled out. Neither permits another financial recording. Never replace the key to bypass uncertainty. Unknown private history is refused rather than interpreted as success.

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```json
{
  "name": "requestId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified manual recording command journal.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentManualResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Fixed admission or command error; no raw provider exception.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Fixed admission or command error; no raw provider exception.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Fixed admission or command error; no raw provider exception.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Fixed admission or command error; no raw provider exception.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Fixed admission or command error; no raw provider exception.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Fixed admission or command error; no raw provider exception.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "paiements:write",
  "x-unisoft-additional-scopes": [
    "payment_manual:write",
    "contacts:write"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "idempotent": true,
    "destructive": false,
    "warn": false
  }
}
```

## POST /payment-links

Create a one-off payment request with a stable retry key

`create_idempotent_payment_link`

Requires paiements:write. Creates a new one-off request through the existing POST /paiements facade, with all of its tenant, target, association, currency and identity checks. Supply config.montant in major units (125.5 means EUR 125.50 for eur), not cents. idempotencyKey is mandatory: one atomic journal claim per organisation, API principal, action and UUID; changed input conflicts. The same key never calls the owner twice, even after timeout or a lost journal write. Read the request journal after uncertainty; never invent a new UUID to force another attempt. HTTP success means the command was handled: inspect data.status and outcome. REQUEST_CREATED acknowledges the owner response, not collection, capture, settlement, receipt issuance or email delivery. A recorded command URL is not a fresh availability check; read get_payment_link before reusing an old URL. The returned URL may be null for embedded/provider flows; no clientSecret, reusable means or private provider response is exposed. An empty URL is not permission to recreate the request. No reminder is sent. Recurring, legacy SERVICE and identity-update intents are excluded.

### אימות

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

### הרשאות נדרשות

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

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "idempotencyKey": {
            "type": "string",
            "format": "uuid",
            "description": "Stable UUID for this one business intent. Reuse it with exactly the same config after a lost response; a different payload conflicts. A different UUID can create another payment."
          },
          "config": {
            "$ref": "#/components/schemas/UnisoftRequest_c6721c5be3f91d5f9f68"
          }
        },
        "required": [
          "idempotencyKey",
          "config"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified command or recorded link observation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

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

## GET /payment-links/requests/{requestId}

Read the outcome of an idempotent payment-link request

`get_payment_link_request`

Requires paiements:write. Read only, for the same authenticated organisation and API principal that created this request. requestId is the original idempotency UUID. PENDING may represent a running call or a process lost after a side effect; UNCERTAIN means the owner result is not safely recoverable. Neither permits another create automatically. No lease expiry re-executes the financial owner. SUCCEEDED/REQUEST_CREATED does not prove money collection. Existing payment/campaign access is checked again before returning a recorded payment capability. No provider call or message is sent.

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```json
{
  "name": "requestId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "The caller-generated idempotency UUID used for this request, within the same organisation and API principal."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified command or recorded link observation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

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

## GET /paiements/{id}/link

Read an existing authorised payment link and its recorded availability

`get_payment_link`

Requires paiements:read AND the explicit payment_links:read grant. Returns a checkout URL stored by the external command journal, or the exact native Paygreen gateway URL, only for an unambiguous authorised INIT payment. A missing URL remains null/NOT_RECORDED; no Stripe session or missing provider URL is regenerated. Known expired, malformed-expiry and non-INIT records return no URL. RECORDED_UNEXPIRED is only a local expiry observation; UNKNOWN does not prove a payable checkout and providerVerified is always false. This read does not create, refresh, retry, cancel, debit or send a reminder. revocation.supported is optimistic admission to the native Stripe-wallet cancellation owner only, not a guaranteed cancellation. Reuse its expectedRevision for the separate revoke action. Other platforms have no invented revocation.

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "Existing payment UUID; never generate an identifier to address an existing payment."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified command or recorded link observation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentExistingLinkResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "paiements:read",
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-additional-scopes": [
    "payment_links:read"
  ],
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "idempotent": true,
    "destructive": false,
    "warn": false
  }
}
```

## POST /paiements/{id}/link/revoke

Request native Stripe-wallet cancellation with recorded recovery

`revoke_payment_link`

Requires paiements:write AND the explicit payment_links:revoke grant. Only an INIT Stripe Apple Pay/Google Pay payment with an exact unique checkout and authorised references is admitted. First read get_payment_link and pass its expectedRevision plus a stable idempotencyKey. The external adapter first verifies Intent id, amount, currency and payment metadata through the native merchant binding, then rechecks the current revision. The native cancellation owner can refuse an in-progress payment, cancel an unpaid Intent and release its own reservation, or discover an already succeeded Intent and finalise that payment instead. Inspect outcome: CANCELED and RECORDED_COMPLETED are distinct; this is never a refund or generic local-state cancellation. The provider may be called and a discovered completion may invoke its normal completion effects. A thrown, unrecognised or lost result becomes UNCERTAIN and is never automatically retried. Read the revocation request journal; never use another key to bypass uncertainty. No checkout/session renewal or reminder delivery is provided. The optimistic revision is not a transaction lock over the internal application.

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "Existing payment UUID; never generate an identifier to address an existing payment."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "idempotencyKey": {
            "type": "string",
            "format": "uuid"
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$",
            "description": "Exact optimistic admission token from this payment link read. A changed payment or a different checkout is refused before delegation."
          }
        },
        "required": [
          "idempotencyKey",
          "expectedRevision"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified command or recorded link observation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "paiements:write",
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-additional-scopes": [
    "payment_links:revoke"
  ],
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "idempotent": true,
    "destructive": false,
    "warn": true
  }
}
```

## GET /paiements/link-revocations/{requestId}

Read the recorded outcome of a payment-link revocation request

`get_payment_link_revocation`

Requires paiements:write AND payment_links:revoke. Read the same API principal and organisation journal using the original idempotency UUID. No provider refresh, cancellation or completion effect is run. PENDING/UNCERTAIN is not permission to retry; CANCELED acknowledges the native owner result and RECORDED_COMPLETED means the owner found a succeeded Intent instead. A request journal is not a complete provider timeline, capture report or bank-settlement proof.

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```json
{
  "name": "requestId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "The caller-generated idempotency UUID used for this request, within the same organisation and API principal."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified command or recorded link observation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PaymentCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Fixed external error code; no provider exception or submitted value.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "query",
                  "path"
                ]
              }
            }
          },
          "param": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "paiements:write",
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-additional-scopes": [
    "payment_links:revoke"
  ],
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "idempotent": true,
    "destructive": false,
    "warn": false
  }
}
```

## סכמות

```json
{
  "components": {
    "schemas": {
      "Paiement": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "organisation",
          "name",
          "type",
          "typeId",
          "parentTypeId",
          "method",
          "platform",
          "source",
          "contact",
          "abo",
          "assoc",
          "externalId",
          "cerfaId",
          "recuId",
          "imported",
          "finalized",
          "cerfa",
          "cerfaYear",
          "amount",
          "devise",
          "state",
          "datetime",
          "info",
          "facturation",
          "refund"
        ],
        "properties": {
          "id": {
            "type": "string",
            "nullable": true
          },
          "organisation": {
            "type": "string",
            "nullable": true
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "type": {
            "type": "string",
            "nullable": true
          },
          "typeId": {
            "type": "string",
            "nullable": true
          },
          "parentTypeId": {
            "type": "string",
            "nullable": true
          },
          "method": {
            "type": "string",
            "nullable": true
          },
          "platform": {
            "type": "string",
            "nullable": true
          },
          "source": {
            "type": "string",
            "nullable": true
          },
          "contact": {
            "type": "string",
            "nullable": true
          },
          "abo": {
            "type": "string",
            "nullable": true
          },
          "assoc": {
            "type": "string",
            "nullable": true
          },
          "externalId": {
            "type": "string",
            "nullable": true
          },
          "cerfaId": {
            "type": "string",
            "nullable": true
          },
          "recuId": {
            "type": "string",
            "nullable": true
          },
          "imported": {
            "type": "boolean",
            "nullable": true
          },
          "finalized": {
            "type": "boolean",
            "nullable": true
          },
          "cerfa": {
            "type": "boolean",
            "nullable": true
          },
          "cerfaYear": {
            "type": "boolean",
            "nullable": true
          },
          "amount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "nullable": true,
            "description": "Recorded minor units; null when absent/invalid. 5000 = EUR 50. No bank-settlement inference."
          },
          "devise": {
            "type": "string",
            "nullable": true,
            "pattern": "^[a-z]{3}$"
          },
          "state": {
            "type": "string",
            "nullable": true,
            "pattern": "^[A-Za-z][A-Za-z0-9_.-]{0,63}$"
          },
          "datetime": {
            "type": "string",
            "nullable": true,
            "format": "date-time"
          },
          "info": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "nom",
              "prenom",
              "email",
              "tel"
            ],
            "properties": {
              "nom": {
                "type": "string",
                "nullable": true
              },
              "prenom": {
                "type": "string",
                "nullable": true
              },
              "email": {
                "type": "string",
                "nullable": true
              },
              "tel": {
                "type": "string",
                "nullable": true
              }
            },
            "nullable": true
          },
          "facturation": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "nom",
              "prenom",
              "raison",
              "siren",
              "civilite",
              "adresse",
              "postal",
              "ville",
              "etat",
              "pays",
              "social_id",
              "perso",
              "giftAid"
            ],
            "properties": {
              "nom": {
                "type": "string",
                "nullable": true
              },
              "prenom": {
                "type": "string",
                "nullable": true
              },
              "raison": {
                "type": "string",
                "nullable": true
              },
              "siren": {
                "type": "string",
                "nullable": true
              },
              "civilite": {
                "type": "string",
                "nullable": true
              },
              "adresse": {
                "type": "string",
                "nullable": true
              },
              "postal": {
                "type": "string",
                "nullable": true
              },
              "ville": {
                "type": "string",
                "nullable": true
              },
              "etat": {
                "type": "string",
                "nullable": true
              },
              "pays": {
                "type": "string",
                "nullable": true
              },
              "social_id": {
                "type": "string",
                "nullable": true
              },
              "perso": {
                "type": "boolean",
                "nullable": true
              },
              "giftAid": {
                "type": "boolean",
                "nullable": true
              }
            },
            "nullable": true
          },
          "refund": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "state",
              "reason",
              "createdAt",
              "updatedAt"
            ],
            "properties": {
              "state": {
                "type": "string",
                "nullable": true,
                "enum": [
                  "PENDING",
                  "SUCCEEDED",
                  "FAILED",
                  "CANCELED",
                  null
                ]
              },
              "reason": {
                "type": "string",
                "nullable": true,
                "enum": [
                  "requested_by_customer",
                  "duplicate",
                  "fraudulent",
                  null
                ]
              },
              "createdAt": {
                "type": "string",
                "nullable": true,
                "format": "date-time"
              },
              "updatedAt": {
                "type": "string",
                "nullable": true,
                "format": "date-time"
              }
            },
            "nullable": true
          },
          "externalRef": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255
          },
          "externalMetadata": {
            "type": "object",
            "maxProperties": 50,
            "additionalProperties": {
              "type": "string",
              "maxLength": 500
            }
          }
        },
        "description": "Allowlisted stored payment business projection shared by list, detail and import. Identity/billing snapshots remain separate from CRM. Unknown money, currency, dates and flags stay null. No reusable method, provider reference/configuration, checkout token, raw error, private snapshot or unknown future field is returned. Recorded COMPLETED can include authorisation before capture and historical imports; no bank settlement or refund credit is verified."
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "hasMore": {
            "type": "boolean"
          },
          "count": {
            "type": "integer"
          }
        }
      },
      "UnisoftRequest_414e1860ccd141107a40": {
        "type": "object",
        "properties": {
          "externalRef": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "pattern": "\\S",
            "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.",
            "example": "commande-1234"
          },
          "externalMetadata": {
            "type": "object",
            "maxProperties": 50,
            "additionalProperties": {
              "type": "string",
              "maxLength": 500
            },
            "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.",
            "example": {
              "registrationId": "inscription-567",
              "eventId": "chabbat-890"
            }
          },
          "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",
            "minimum": 0.01,
            "maximum": 1000000,
            "multipleOf": 0.01,
            "description": "Amount in major units (e.g. euros)."
          },
          "devise": {
            "type": "string",
            "nullable": true
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "info": {
            "$ref": "#/components/schemas/UnisoftRequest_b6eaf8c17ece06a2ed03"
          },
          "facturation": {
            "$ref": "#/components/schemas/UnisoftRequest_ef522362195300ba7557"
          },
          "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",
            "enum": [
              false
            ],
            "description": "Only a one-time request is supported here. For a supported subscription use prepare_subscription."
          },
          "nbMonth": {
            "type": "integer",
            "nullable": true
          },
          "maxAmount": {
            "type": "integer",
            "nullable": true
          },
          "assoc": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "Explicit beneficiary association for a GENERAL donation, resolved from list_associations. Omission keeps the owner selection, which may use defaultAssoc and is not guaranteed to be MAIN. Target-linked payment associations are derived by their business owner."
          },
          "cerfa": {
            "type": "boolean"
          },
          "update": {
            "type": "boolean",
            "enum": [
              false
            ],
            "description": "Existing payment updates, including identity completion, are unavailable through this operation. Omit this field or pass false."
          },
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "Historical payment identifier. Supplying it does not authorise updating an existing payment; update and UPDATE mode are unavailable."
          },
          "service": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              }
            },
            "required": [
              "id"
            ],
            "additionalProperties": false,
            "description": "Historical SERVICE target reference. It is not accepted for other payment types."
          },
          "dettes": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 200
                },
                "montant": {
                  "type": "number",
                  "minimum": 0.01,
                  "maximum": 90071992547409,
                  "multipleOf": 0.01
                }
              },
              "required": [
                "id",
                "montant"
              ],
              "additionalProperties": false
            },
            "description": "Authorised pledge allocations in major units; for a recurring request these are contractual allocation budgets, not one instalment."
          }
        },
        "required": [
          "type",
          "montant"
        ],
        "additionalProperties": false,
        "description": "Payment intent for the authenticated organisation. Organisation context is supplied by the server; config.organisation is not an admitted input field."
      },
      "UnisoftRequest_b6eaf8c17ece06a2ed03": {
        "type": "object",
        "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)."
          }
        },
        "additionalProperties": false,
        "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."
      },
      "UnisoftRequest_ef522362195300ba7557": {
        "type": "object",
        "properties": {
          "perso": {
            "type": "boolean",
            "description": "true = individual (nom/prenom), false = company (raison/siren). Defaults to true.",
            "default": 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."
          }
        },
        "additionalProperties": false,
        "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\"`)."
      },
      "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
          }
        }
      },
      "UnisoftRequest_810f34219cd254d860a7": {
        "type": "object",
        "properties": {
          "externalRef": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "pattern": "\\S",
            "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.",
            "example": "commande-1234"
          },
          "externalMetadata": {
            "type": "object",
            "maxProperties": 50,
            "additionalProperties": {
              "type": "string",
              "maxLength": 500
            },
            "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.",
            "example": {
              "registrationId": "inscription-567",
              "eventId": "chabbat-890"
            }
          },
          "amount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9007199254740991,
            "description": "Positive safe integer amount in minor units. If montant is also supplied, both amounts must agree exactly; no coercion or rounding."
          },
          "montant": {
            "type": "number",
            "minimum": 0.01,
            "maximum": 90071992547409,
            "multipleOf": 0.01,
            "description": "Positive amount in major units, with at most two decimal places and an exact safe-integer conversion to minor units. No rounding."
          },
          "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",
            "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).",
            "default": "MAIN"
          },
          "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"
            ],
            "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).",
            "default": "GENERAL"
          },
          "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/UnisoftRequest_b6eaf8c17ece06a2ed03"
          },
          "facturation": {
            "$ref": "#/components/schemas/UnisoftRequest_ef522362195300ba7557"
          },
          "commentaire": {
            "type": "string",
            "description": "Free-text note kept on the payment."
          },
          "datetime": {
            "type": "string",
            "anyOf": [
              {
                "format": "date"
              },
              {
                "format": "date-time"
              }
            ],
            "description": "Historical business date: YYYY-MM-DD interpreted at UTC midnight, or an RFC 3339 instant with timezone. Omission uses now; zero, ambiguous or impossible dates are rejected."
          },
          "source": {
            "type": "string",
            "description": "A label identifying where the payment comes from (e.g. \"HELLOASSO\", \"MY_OLD_SOFTWARE\"). Upper-cased. Defaults to \"API_IMPORT\".",
            "default": "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."
          }
        },
        "required": [
          "method"
        ],
        "additionalProperties": false,
        "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."
      },
      "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
          }
        }
      },
      "PaymentStatusResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/PaymentStatus"
          }
        }
      },
      "PaymentStatus": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "state",
          "phase",
          "amountMinor",
          "currency",
          "imported",
          "donorInformationStatus",
          "recordedAt"
        ],
        "description": "Allowlisted snapshot of one stored payment. No provider request or financial operation is performed. Unknown or invalid historical values remain null or UNKNOWN; they are never replaced by a successful result or a zero amount.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Stable Unisoft payment identifier; each payment attempt has its own identifier."
          },
          "state": {
            "type": "string",
            "nullable": true,
            "maxLength": 64,
            "pattern": "^[A-Za-z][A-Za-z0-9_.-]{0,63}$",
            "description": "Stored Unisoft state code, without inference from age, provider reference or browser return. Null when missing or structurally invalid. A new unrecognised code is retained here and maps to phase UNKNOWN."
          },
          "phase": {
            "type": "string",
            "enum": [
              "PREPARED",
              "PROCESSING",
              "RECORDED_COMPLETED",
              "FAILED",
              "CANCELED",
              "REFUND_PENDING",
              "RECORDED_REFUNDED",
              "TECHNICAL",
              "UNKNOWN"
            ],
            "description": "Conservative interpretation of state. INIT=PREPARED; AWAITING_DEVICE/PENDING/PRELEVEMENT-SUBMITED/SEPA_PENDING=PROCESSING; COMPLETED=RECORDED_COMPLETED; FAILED/ERROR/REQUIRES_PAYMENT_METHOD=FAILED; CANCELED/CANCELLED=CANCELED; REFUND_PENDING=REFUND_PENDING; REFUNDED=RECORDED_REFUNDED; ABO_PAUSE=TECHNICAL; all other values=UNKNOWN. RECORDED_COMPLETED is Unisoft's stored business result: Axepta can record an authorisation before capture, and imports record an already-collected historical payment. It does not prove capture, bank settlement, payout, or permission to retry. RECORDED_REFUNDED likewise describes the stored result. Pending and unknown states must not trigger a new charge automatically."
          },
          "amountMinor": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Stored payment amount in minor currency units, such as 5000 for EUR 50. It is the amount of this attempt, not the nominal subscription amount. Null when missing, negative, fractional or unsafe; zero can be a technical ABO_PAUSE trace."
          },
          "currency": {
            "type": "string",
            "nullable": true,
            "pattern": "^[a-z]{3}$",
            "description": "Stored three-letter currency code, normalised to lowercase. Null when missing or malformed; no organisation currency is substituted."
          },
          "imported": {
            "type": "boolean",
            "nullable": true,
            "description": "Stored import marker: true or false only when explicitly recorded as a boolean; null when absent or invalid. Historical consumers commonly test imported:true, but an absent flag remains unknown in this response. Historical imports do not initiate a new debit and differ from native payments in document queues and some totals."
          },
          "donorInformationStatus": {
            "type": "string",
            "enum": [
              "NOT_REPORTED",
              "INCOMPLETE",
              "COMPLETE",
              "UNKNOWN"
            ],
            "description": "Separate interpretation of finalized: false=INCOMPLETE, true=COMPLETE, absent/null=NOT_REPORTED, invalid=UNKNOWN. This is a donor-information/publication marker, not receipt issuance or receipt of funds. COMPLETED may coexist with INCOMPLETE; NOT_REPORTED is not a failed finalisation."
          },
          "recordedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Stored payment datetime as an ISO instant. The producing flow defines its meaning: usually preparation time online, supplied business date for manual entry/import. It is not a confirmed bank settlement or receipt issue date. Null when missing or unsupported; never replaced with the current time."
          }
        },
        "example": {
          "id": "11111111-1111-4111-8111-111111111111",
          "state": "COMPLETED",
          "phase": "RECORDED_COMPLETED",
          "amountMinor": 5000,
          "currency": "eur",
          "imported": null,
          "donorInformationStatus": "INCOMPLETE",
          "recordedAt": "2026-11-07T10:00:00.000Z"
        }
      },
      "PaymentContextResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/PaymentContext"
          }
        }
      },
      "PaymentContext": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "payment",
          "timeline",
          "relations",
          "campaignRestrictedDomains"
        ],
        "properties": {
          "payment": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "state",
              "phase",
              "amountMinor",
              "currency",
              "imported",
              "donorInformationStatus",
              "recordedAt"
            ],
            "description": "Allowlisted snapshot of one stored payment. No provider request or financial operation is performed. Unknown or invalid historical values remain null or UNKNOWN; they are never replaced by a successful result or a zero amount.",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "description": "Stable Unisoft payment identifier; each payment attempt has its own identifier."
              },
              "state": {
                "type": "string",
                "nullable": true,
                "maxLength": 64,
                "pattern": "^[A-Za-z][A-Za-z0-9_.-]{0,63}$",
                "description": "Stored Unisoft state code, without inference from age, provider reference or browser return. Null when missing or structurally invalid. A new unrecognised code is retained here and maps to phase UNKNOWN."
              },
              "phase": {
                "type": "string",
                "enum": [
                  "PREPARED",
                  "PROCESSING",
                  "RECORDED_COMPLETED",
                  "FAILED",
                  "CANCELED",
                  "REFUND_PENDING",
                  "RECORDED_REFUNDED",
                  "TECHNICAL",
                  "UNKNOWN"
                ],
                "description": "Conservative interpretation of state. INIT=PREPARED; AWAITING_DEVICE/PENDING/PRELEVEMENT-SUBMITED/SEPA_PENDING=PROCESSING; COMPLETED=RECORDED_COMPLETED; FAILED/ERROR/REQUIRES_PAYMENT_METHOD=FAILED; CANCELED/CANCELLED=CANCELED; REFUND_PENDING=REFUND_PENDING; REFUNDED=RECORDED_REFUNDED; ABO_PAUSE=TECHNICAL; all other values=UNKNOWN. RECORDED_COMPLETED is Unisoft's stored business result: Axepta can record an authorisation before capture, and imports record an already-collected historical payment. It does not prove capture, bank settlement, payout, or permission to retry. RECORDED_REFUNDED likewise describes the stored result. Pending and unknown states must not trigger a new charge automatically."
              },
              "amountMinor": {
                "type": "integer",
                "nullable": true,
                "minimum": 0,
                "maximum": 9007199254740991,
                "description": "Stored payment amount in minor currency units, such as 5000 for EUR 50. It is the amount of this attempt, not the nominal subscription amount. Null when missing, negative, fractional or unsafe; zero can be a technical ABO_PAUSE trace."
              },
              "currency": {
                "type": "string",
                "nullable": true,
                "pattern": "^[a-z]{3}$",
                "description": "Stored three-letter currency code, normalised to lowercase. Null when missing or malformed; no organisation currency is substituted."
              },
              "imported": {
                "type": "boolean",
                "nullable": true,
                "description": "Stored import marker: true or false only when explicitly recorded as a boolean; null when absent or invalid. Historical consumers commonly test imported:true, but an absent flag remains unknown in this response. Historical imports do not initiate a new debit and differ from native payments in document queues and some totals."
              },
              "donorInformationStatus": {
                "type": "string",
                "enum": [
                  "NOT_REPORTED",
                  "INCOMPLETE",
                  "COMPLETE",
                  "UNKNOWN"
                ],
                "description": "Separate interpretation of finalized: false=INCOMPLETE, true=COMPLETE, absent/null=NOT_REPORTED, invalid=UNKNOWN. This is a donor-information/publication marker, not receipt issuance or receipt of funds. COMPLETED may coexist with INCOMPLETE; NOT_REPORTED is not a failed finalisation."
              },
              "recordedAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "Stored payment datetime as an ISO instant. The producing flow defines its meaning: usually preparation time online, supplied business date for manual entry/import. It is not a confirmed bank settlement or receipt issue date. Null when missing or unsupported; never replaced with the current time."
              }
            },
            "example": {
              "id": "11111111-1111-4111-8111-111111111111",
              "state": "COMPLETED",
              "phase": "RECORDED_COMPLETED",
              "amountMinor": 5000,
              "currency": "eur",
              "imported": null,
              "donorInformationStatus": "INCOMPLETE",
              "recordedAt": "2026-11-07T10:00:00.000Z"
            }
          },
          "timeline": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PaymentContextTimelineEvent"
            },
            "description": "Stored events sorted by instant ascending, then kind, resourceType and resourceId. This is a partial observation: no complete state history, provider event stream, capture, settlement, expiry or retry permission is reconstructed."
          },
          "relations": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "contact",
              "pledges",
              "subscription",
              "submission",
              "documents"
            ],
            "description": "Only currently admissible references. Null or an empty array means no admissible reference was returned; it does not prove that no historical relation exists. Invalid, deleted, foreign or campaign-inaccessible targets remain undisclosed.",
            "properties": {
              "contact": {
                "type": "object",
                "nullable": true,
                "additionalProperties": false,
                "required": [
                  "id"
                ],
                "description": "CRM reference from payment.contact. Always null under campaign restriction because contacts have no independent campaign membership owner.",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Current authorised resource identifier."
                  }
                }
              },
              "pledges": {
                "type": "array",
                "maxItems": 200,
                "items": {
                  "$ref": "#/components/schemas/PaymentContextPledgeReference"
                },
                "description": "Distinct authorised pledge references sorted by id. These references are not financial allocation totals."
              },
              "subscription": {
                "type": "object",
                "nullable": true,
                "additionalProperties": false,
                "required": [
                  "id"
                ],
                "description": "Contract reference from payment.abo, independently checked through payload.type=CAMPAGNE and payload.typeId when the key is campaign limited. No schedule is initialised or inferred.",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Current authorised resource identifier."
                  }
                }
              },
              "submission": {
                "type": "object",
                "nullable": true,
                "additionalProperties": false,
                "required": [
                  "id"
                ],
                "description": "FORM payment.typeId is a forms_submit submission, not the parent form. Always null under campaign restriction because submissions have no independent campaign membership owner.",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Current authorised resource identifier."
                  }
                }
              },
              "documents": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PaymentContextDocumentReference"
                },
                "description": "Currently authorised documents linked by the documentary owner, including admitted grouped and annual documents. No URL, donor identity, private snapshot or provider response is returned."
              }
            }
          },
          "campaignRestrictedDomains": {
            "type": "array",
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "CONTACT",
                "SUBMISSION"
              ]
            },
            "description": "CONTACT and SUBMISSION are listed for every campaign-limited key, independently of whether a historical link exists. Their references are withheld because independent campaign membership cannot be established. Empty for unrestricted keys."
          }
        }
      },
      "PaymentContextTimelineEvent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "kind",
          "at",
          "resourceType",
          "resourceId",
          "source"
        ],
        "description": "One supported stored date, never an inferred transition or a complete audit log. Invalid or absent dates produce no event.",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "PAYMENT_DATE_RECORDED",
              "REFUND_REQUEST_RECORDED",
              "REFUND_RECORD_UPDATED",
              "DOCUMENT_RECORDED"
            ],
            "description": "PAYMENT_DATE_RECORDED is payment.datetime, whose producer may record preparation or a supplied manual/import date. REFUND_REQUEST_RECORDED and REFUND_RECORD_UPDATED are the latest stored refund record dates, not every attempt or a bank verdict. DOCUMENT_RECORDED is document.datetime, not confirmed delivery."
          },
          "at": {
            "type": "string",
            "format": "date-time",
            "description": "Supported stored instant normalised to UTC ISO 8601; never replaced by the current time."
          },
          "resourceType": {
            "type": "string",
            "enum": [
              "PAYMENT",
              "FISCAL_RECEIPT",
              "RECEIPT"
            ],
            "description": "Type of the independently authorised resource carrying the recorded date."
          },
          "resourceId": {
            "type": "string",
            "format": "uuid",
            "description": "Identifier of the resource carrying this date."
          },
          "source": {
            "type": "string",
            "enum": [
              "payment.datetime",
              "payment.refund.createdAt",
              "payment.refund.updatedAt",
              "document.datetime"
            ],
            "description": "Exact allowlisted persisted date source."
          }
        }
      },
      "PaymentContextPledgeReference": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "sources"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Current authorised pledge identifier."
          },
          "sources": {
            "type": "array",
            "minItems": 1,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "PAYMENT_TARGET",
                "PAYMENT_ALLOCATION",
                "LEGACY_ALLOCATION_REFERENCE"
              ]
            },
            "description": "PAYMENT_TARGET is the stored DETTE typeId and does not assert a current allocation. PAYMENT_ALLOCATION is a positive safe-integer entry of pledgeAllocations, or subscriptionAllocations when the first map is absent. Explicit empty maps suppress legacy allocation references. LEGACY_ALLOCATION_REFERENCE is dettes[].id only when neither map exists; no amount, prorata, settled balance or contract allocation is inferred."
          }
        }
      },
      "PaymentContextDocumentReference": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "kind"
        ],
        "description": "Existing fiscal or ordinary receipt reference; the document owner checks the payment relation and all annual/group members. This reference does not generate, resend or download a document.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Current authorised document identifier."
          },
          "kind": {
            "type": "string",
            "enum": [
              "FISCAL_RECEIPT",
              "RECEIPT"
            ],
            "description": "FISCAL_RECEIPT identifies a cerfas record; RECEIPT identifies a recus record."
          }
        }
      },
      "PaymentMethodsResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/PaymentMethodsData"
          }
        }
      },
      "PaymentMethodsData": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "association",
          "currency",
          "type",
          "typeId",
          "recurring",
          "targetEligibility",
          "providerVerification",
          "methods"
        ],
        "properties": {
          "association": {
            "type": "string",
            "description": "Verified legal association reference: MAIN or an association UUID."
          },
          "currency": {
            "type": "string",
            "pattern": "^[a-z]{3}$",
            "description": "Effective collection currency matching the association; no conversion or virtual display currency."
          },
          "type": {
            "type": "string",
            "enum": [
              "GENERAL",
              "FORM",
              "DETTE",
              "CAISSE",
              "CAMPAGNE"
            ],
            "description": "Payment business allocation. FORM's typeId is a submission UUID, not the form definition."
          },
          "typeId": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "Verified target UUID; null for GENERAL."
          },
          "recurring": {
            "type": "boolean",
            "description": "Requested recurring intent, not an existing subscription or execution instruction."
          },
          "targetEligibility": {
            "type": "string",
            "enum": [
              "INDETERMINATE",
              "INELIGIBLE"
            ],
            "description": "A valid target reference is not proof that its complete payment context can be accepted."
          },
          "providerVerification": {
            "type": "string",
            "enum": [
              "NOT_PERFORMED"
            ],
            "description": "No provider request, credential validation, bank verification or browser capability test was performed."
          },
          "methods": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PaymentMethodOption"
            },
            "description": "Local checkout choices relevant to recurring intent. Unlisted choices are not advertised; their absence is not a statement about the provider's global capabilities."
          }
        }
      },
      "PaymentMethodOption": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "choice",
          "configuration",
          "selection",
          "platform",
          "instrument",
          "eligibility",
          "prerequisites"
        ],
        "properties": {
          "choice": {
            "type": "string",
            "enum": [
              "CARD",
              "PRELEVEMENT.GOCARDLESS",
              "STRIPE.SEPA",
              "SEPA_XML",
              "PAYPAL",
              "CARDCOM.BIT",
              "KESHER.BIT",
              "AAC",
              "STRIPE.APPLEPAY",
              "STRIPE.GOOGLEPAY"
            ],
            "description": "Requested checkout choice; CARD uses the association's current default card provider."
          },
          "configuration": {
            "type": "string",
            "enum": [
              "AVAILABLE",
              "UNAVAILABLE",
              "INDETERMINATE"
            ],
            "description": "AVAILABLE means local option configuration and merchant selection were observed. It never verifies credentials, provider health or acceptance."
          },
          "selection": {
            "type": "string",
            "enum": [
              "RESOLVED",
              "UNAVAILABLE",
              "INDETERMINATE",
              "NOT_EVALUATED"
            ],
            "description": "Pure current-owner selection result. SEPA_XML bypasses this owner and remains NOT_EVALUATED until its own runtime admission."
          },
          "platform": {
            "type": "string",
            "nullable": true,
            "enum": [
              "PAYGREEN",
              "STRIPE",
              "STRIPE_EXTERNAL",
              "STRIPE.SEPA",
              "STRIPE_EXTERNAL.SEPA",
              "AUTHORIZENET",
              "PAYME",
              "CARDCOM",
              "CARDCOM.BIT",
              "NEDARIM",
              "IPAY",
              "AXEPTA",
              "HYP",
              "PAYPAL",
              "AAC",
              "KESHER",
              "KESHER.BIT",
              "GOCARDLESS",
              "STRIPE.APPLEPAY",
              "STRIPE.GOOGLEPAY",
              "STRIPE_EXTERNAL.APPLEPAY",
              "STRIPE_EXTERNAL.GOOGLEPAY",
              "SEPA_XML",
              null
            ],
            "description": "Allowlisted selected provider code, or null when selection is unavailable, uncertain or not evaluated."
          },
          "instrument": {
            "type": "string",
            "nullable": true,
            "enum": [
              "CB",
              "PRELEVEMENT",
              "VIREMENT",
              null
            ],
            "description": "Instrument returned by the selection owner. Null is unknown, never inferred from a provider name."
          },
          "eligibility": {
            "type": "string",
            "enum": [
              "INDETERMINATE",
              "INELIGIBLE"
            ],
            "description": "Final payment eligibility is never confirmed by this configuration read. INELIGIBLE identifies an observed local refusal; INDETERMINATE requires the listed prerequisites."
          },
          "prerequisites": {
            "type": "array",
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "PAYMENT_CONTEXT_REQUIRED",
                "PROVIDER_VERIFICATION_REQUIRED",
                "MERCHANT_CONFIGURATION_NOT_CONFIRMED",
                "CONFIGURATION_REVIEW_REQUIRED",
                "REQUESTED_CHOICE_NOT_SELECTED",
                "BROWSER_WALLET_CHECK_REQUIRED",
                "MANDATE_AND_SCHEDULE_REQUIRED",
                "SEPA_RUNTIME_ADMISSION_REQUIRED",
                "TARGET_CURRENCY_NOT_RECORDED",
                "TARGET_CHECKOUT_REQUIRED",
                "TARGET_NOT_ACCEPTING_PAYMENTS",
                "FORM_REQUIRES_BANK_WITHDRAWAL"
              ]
            },
            "description": "Remaining checks or local refusal reasons. PAYMENT_CONTEXT_REQUIRED includes amount, donor, allocations, schedule and target-specific rules absent from this request."
          }
        }
      },
      "PaymentMethodsErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "PaymentRefundHistoryResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/PaymentRefundHistory"
          }
        }
      },
      "PaymentRefundHistory": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "paymentId",
          "status",
          "latestAttempt",
          "history",
          "historyCompleteness",
          "hasMore"
        ],
        "properties": {
          "paymentId": {
            "type": "string",
            "format": "uuid",
            "description": "Stable Unisoft payment identifier."
          },
          "status": {
            "type": "string",
            "enum": [
              "NOT_RECORDED",
              "PENDING",
              "RECORDED_SUCCEEDED",
              "RECORDED_FAILED",
              "RECORDED_CANCELED",
              "UNKNOWN"
            ],
            "description": "Conservative recorded result. NOT_RECORDED means neither a retained refund snapshot nor a refund audit was found; it does not prove that no refund occurred or that one failed. PENDING is the paired REFUND_PENDING/PENDING reservation without a stored error; a pending error or contradictory/malformed record gives UNKNOWN. RECORDED_SUCCEEDED is the REFUNDED/SUCCEEDED pair; RECORDED_FAILED and RECORDED_CANCELED are the COMPLETED/FAILED or COMPLETED/CANCELED pairs. These describe Unisoft's record, not independently verified bank results or permission to retry."
          },
          "latestAttempt": {
            "$ref": "#/components/schemas/PaymentRefundAttempt"
          },
          "history": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/PaymentRefundAuditEvent"
            },
            "description": "At most 100 existing refund audits, ordered by stored datetime descending then private Mongo _id descending. Malformed or missing dates remain null. This list does not reconstruct reservations, failures, callback confirmations or attempts."
          },
          "historyCompleteness": {
            "type": "string",
            "enum": [
              "PARTIAL"
            ],
            "description": "Always PARTIAL: audits are best effort and the payment retains only the latest attempt. No complete financial event ledger exists here, even when hasMore is false."
          },
          "hasMore": {
            "type": "boolean",
            "description": "True when more than 100 matching audit rows were found. There is no continuation parameter on this bounded observation; false does not establish complete history."
          }
        }
      },
      "PaymentRefundAttempt": {
        "type": "object",
        "additionalProperties": false,
        "nullable": true,
        "required": [
          "state",
          "attemptNumber",
          "reservedAt",
          "updatedAt"
        ],
        "description": "Latest retained refund attempt only. A new reservation overwrites this snapshot; it is not an array of all attempts.",
        "properties": {
          "state": {
            "type": "string",
            "nullable": true,
            "enum": [
              "PENDING",
              "SUCCEEDED",
              "FAILED",
              "CANCELED",
              null
            ],
            "description": "Allowlisted stored refund state. Null when absent, invalid or unrecognised. PENDING can be a reservation or an unconfirmed provider result; inspect the top-level status."
          },
          "attemptNumber": {
            "type": "integer",
            "nullable": true,
            "minimum": 1,
            "maximum": 9007199254740991,
            "description": "Positive stored refund.attempt counter, or null when absent/invalid. It is neither a list of prior attempts nor a count of completed refunds."
          },
          "reservedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Stored refund.createdAt as an ISO instant, or null when absent/invalid. This marks the local reservation, not proof of provider submission or completion."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Stored refund.updatedAt as an ISO instant, or null when absent/invalid. This is the latest retained update; no intermediate transitions are reconstructed."
          }
        }
      },
      "PaymentRefundAuditEvent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "event",
          "recordedAt"
        ],
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "REFUND_RECORDED"
            ],
            "description": "Existing PAIEMENT_REFUND audit from the shared finaliser. It records a business step, not a fresh bank verification, and is not tied to an attempt number."
          },
          "recordedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Stored audit datetime as an ISO instant, or null when absent/invalid. It is not a bank settlement date."
          }
        }
      },
      "PaymentFinanceResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/PaymentFinance"
          }
        }
      },
      "PaymentFinance": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "currency",
          "grossMinor",
          "bankFeesMinor",
          "serviceFeesMinor",
          "bankFeesCurrency",
          "serviceFeesCurrency",
          "bankFeesBasis",
          "serviceFeesBasis",
          "totalFeesMinor",
          "netMinor",
          "netAvailability",
          "netUnavailableReason",
          "conversion",
          "payout",
          "reconciliation"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Stable Unisoft payment attempt identifier."
          },
          "currency": {
            "type": "string",
            "nullable": true,
            "pattern": "^[a-z]{3}$",
            "description": "Stored payment currency, normalised to lowercase; null when absent or invalid. No organisation currency is substituted."
          },
          "grossMinor": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Stored payment amount in minor currency units; 5000 means EUR 50 when currency is eur. Null when absent, negative, fractional or unsafe. Zero may represent a technical trace."
          },
          "bankFeesMinor": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Raw recorded bankFees in minor units whose currency is not retained by the legacy producer. Do not label it with currency or subtract a nonzero fee from grossMinor. Null when absent or invalid; never an inferred zero. Can be an estimate."
          },
          "serviceFeesMinor": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Raw recorded orgfees service/software fee in minor units whose currency/provenance is not retained. Do not label it with the payment currency or subtract a nonzero fee. An explicit zero remains zero; an absent or invalid fee remains null."
          },
          "bankFeesCurrency": {
            "type": "string",
            "nullable": true,
            "enum": [
              null
            ],
            "description": "Always null: the producer did not retain the fee denomination. In Stripe, settlement-currency fees can differ from payment currency. No currency is guessed."
          },
          "serviceFeesCurrency": {
            "type": "string",
            "nullable": true,
            "enum": [
              null
            ],
            "description": "Always null: no independently recorded denomination for this fee is available. It is not inferred from payment, organisation or converted fields."
          },
          "bankFeesBasis": {
            "type": "string",
            "enum": [
              "ESTIMATED",
              "RECORDED_WITHOUT_PROVENANCE",
              "UNKNOWN"
            ],
            "description": "ESTIMATED when a PAYGREEN estimateFees.bankFees matches the recorded fee; otherwise RECORDED_WITHOUT_PROVENANCE for a valid amount, or UNKNOWN for an absent/invalid amount. A recorded fee is never labelled verified or final."
          },
          "serviceFeesBasis": {
            "type": "string",
            "enum": [
              "ESTIMATED",
              "RECORDED_WITHOUT_PROVENANCE",
              "UNKNOWN"
            ],
            "description": "ESTIMATED when a PAYGREEN estimateFees.orgfees matches the recorded fee; otherwise RECORDED_WITHOUT_PROVENANCE for a valid amount, or UNKNOWN. Absence of an estimate marker is not proof of a final fee."
          },
          "totalFeesMinor": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Zero only when both recorded fees are explicitly zero and payment currency is known; otherwise null because fee denomination is not proven. Null does not mean free of fees."
          },
          "netMinor": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Available only when both recorded fees are explicitly zero and grossMinor/payment currency are known: netMinor then equals grossMinor without mixing currencies. Any nonzero fee has unproven denomination and keeps net unknown. No refund adjustment, provider settlement or bank receipt is inferred."
          },
          "netAvailability": {
            "type": "string",
            "enum": [
              "AVAILABLE",
              "UNKNOWN"
            ],
            "description": "AVAILABLE means a net from recorded zero fees can be expressed in the payment currency; it does not mean final fees, funds received, provider settlement or payout."
          },
          "netUnavailableReason": {
            "type": "string",
            "nullable": true,
            "enum": [
              "MISSING_OR_INVALID_CURRENCY",
              "MISSING_OR_INVALID_GROSS",
              "MISSING_OR_INVALID_BANK_FEES",
              "MISSING_OR_INVALID_SERVICE_FEES",
              "FEE_CURRENCY_NOT_RECORDED",
              null
            ],
            "description": "First missing/invalid prerequisite, or FEE_CURRENCY_NOT_RECORDED for any nonzero fee; null only when netMinor is available."
          },
          "conversion": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "availability",
              "reason"
            ],
            "properties": {
              "availability": {
                "type": "string",
                "enum": [
                  "UNAVAILABLE"
                ]
              },
              "reason": {
                "type": "string",
                "enum": [
                  "HISTORICAL_CONVERSION_PROVENANCE_NOT_RECORDED"
                ]
              }
            },
            "description": "Converted amounts are not exposed: the historical target currency is not recorded and converted fees may have been produced from missing fees. No rate is fetched or assumed."
          },
          "payout": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "availability",
              "reason"
            ],
            "properties": {
              "availability": {
                "type": "string",
                "enum": [
                  "UNAVAILABLE"
                ]
              },
              "reason": {
                "type": "string",
                "enum": [
                  "AUTHORIZED_OWNER_ADAPTER_REQUIRED"
                ]
              }
            },
            "description": "Payout is not exposed by this external operation. This says nothing about the existence or state of a payout. Current internal treasury authority cannot be inferred from a payment reference or API key."
          },
          "reconciliation": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "availability",
              "reason"
            ],
            "properties": {
              "availability": {
                "type": "string",
                "enum": [
                  "UNAVAILABLE"
                ]
              },
              "reason": {
                "type": "string",
                "enum": [
                  "AUTHORIZED_OWNER_ADAPTER_REQUIRED"
                ]
              }
            },
            "description": "Reconciliation is not exposed by this external operation. UNAVAILABLE is not UNMATCHED or CONFIRMED. An explicitly authorised owner adapter is a prerequisite."
          }
        }
      },
      "PaymentIncidentsResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/PaymentIncidents"
          }
        }
      },
      "PaymentIncidents": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "provider",
          "coverage",
          "sources"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Authorised Unisoft payment attempt identifier."
          },
          "provider": {
            "type": "string",
            "nullable": true,
            "enum": [
              "STRIPE",
              "GOCARDLESS",
              "SEPA_XML",
              null
            ],
            "description": "Supported persisted provider family, or null. Arbitrary historical platform text is never returned."
          },
          "coverage": {
            "type": "string",
            "enum": [
              "PARTIAL_PERSISTED",
              "UNSUPPORTED"
            ],
            "description": "PARTIAL_PERSISTED covers only the listed stored snapshots and is never complete. UNSUPPORTED means this platform has no supported incident source here."
          },
          "sources": {
            "type": "array",
            "maxItems": 2,
            "items": {
              "$ref": "#/components/schemas/PaymentIncidentSource"
            },
            "description": "Two source observations for Stripe, one for GoCardless/SEPA_XML, none for unsupported platforms. Latest snapshot per source; no deduplication, history completeness or monetary aggregation is claimed."
          }
        }
      },
      "PaymentIncidentSource": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "source",
          "observation",
          "snapshot"
        ],
        "properties": {
          "source": {
            "type": "string",
            "enum": [
              "STRIPE_PAYMENT_FAILURE",
              "STRIPE_TREASURY_DISPUTE",
              "GOCARDLESS_PAYMENT_FAILURE",
              "SEPA_XML_PAYMENT_FAILURE"
            ],
            "description": "Persisted source of this single snapshot. Sources may overlap; they are not separate charge or incident counts."
          },
          "observation": {
            "type": "string",
            "enum": [
              "RECORDED",
              "NOT_RECORDED",
              "UNRECOGNISED",
              "UNAVAILABLE"
            ],
            "description": "RECORDED supplies a safe snapshot. NOT_RECORDED means no selected persisted trace; UNRECOGNISED means unsupported/invalid trace; UNAVAILABLE means a separate authorisation adapter is required to read Stripe treasury. None asserts absence of a bank incident."
          },
          "snapshot": {
            "$ref": "#/components/schemas/PaymentIncidentSnapshot"
          }
        }
      },
      "PaymentIncidentSnapshot": {
        "type": "object",
        "nullable": true,
        "additionalProperties": false,
        "description": "Latest supported stored snapshot for this source, or null. This is not a provider event history.",
        "required": [
          "kind",
          "reason",
          "code",
          "bankReasonCode",
          "providerStatus",
          "recordedPaymentState",
          "resolution",
          "occurredAt",
          "observedAt",
          "resolvedAt"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "DISPUTE",
              "REJECTION",
              "RETURN",
              "REFUND",
              "UNKNOWN"
            ],
            "description": "Classification supported by the persisted provider source, not by arbitrary error text. REFUND here is an explicit SEPA_XML bank-return event, not a generic merchant refund."
          },
          "reason": {
            "type": "string",
            "enum": [
              "DEBIT_DISPUTED",
              "INSUFFICIENT_FUNDS",
              "PAYMENT_DECLINED",
              "MANDATE_UNUSABLE",
              "PAYER_APPROVAL_DENIED",
              "UNKNOWN"
            ],
            "description": "Safe presentation reason: DEBIT_DISPUTED means debit/authorisation contested; INSUFFICIENT_FUNDS means insufficient balance; PAYMENT_DECLINED means recorded refusal; MANDATE_UNUSABLE means the stored cause or SEPA policy identifies an unusable mandate; PAYER_APPROVAL_DENIED means payer approval refused. UNKNOWN means no supported reason; it is not a retry instruction."
          },
          "code": {
            "type": "string",
            "nullable": true,
            "enum": [
              "debit_disputed",
              "card_declined",
              "refund_requested",
              "authorisation_disputed",
              "insufficient_funds",
              "customer_approval_denied",
              "return_on_odd_details",
              "refer_to_payer",
              "bank_account_transferred",
              "mandate_cancelled",
              "mandate_expired",
              "mandate_suspended",
              "mandate_is_inactive",
              "bank_account_closed",
              "bank_account_disabled",
              "invalid_bank_details",
              "account_blocked_for_direct_debit",
              "account_blocked_for_any_financial_transaction",
              "direct_debit_not_enabled",
              null
            ],
            "description": "Whitelisted persisted Stripe/GoCardless cause, or null. Unknown codes and all raw provider messages are omitted."
          },
          "bankReasonCode": {
            "type": "string",
            "nullable": true,
            "enum": [
              "AM04",
              "AC01",
              "AC04",
              "AC06",
              "AG01",
              "MD01",
              "MD06",
              null
            ],
            "description": "Whitelisted bank reason code, or null. A GoCardless bank code belongs to its bank scheme and never by itself proves a dispute or a common cross-scheme meaning."
          },
          "providerStatus": {
            "type": "string",
            "nullable": true,
            "enum": [
              "failed",
              "late_failure",
              "charged_back",
              "cancelled",
              "customer_approval_denied",
              "REJECT",
              "RETURN",
              "DISPUTE",
              "REFUND",
              null
            ],
            "description": "Whitelisted GoCardless action or SEPA_XML event type, or null. Unknown statuses remain null; no provider state is retrieved live."
          },
          "recordedPaymentState": {
            "type": "string",
            "nullable": true,
            "enum": [
              "FAILED",
              "ERROR",
              "REQUIRES_PAYMENT_METHOD",
              "CANCELED",
              "COMPLETED",
              "SEPA_PARTIAL",
              null
            ],
            "description": "Whitelisted current Unisoft payment state associated with the stored snapshot, or null. This is not a provider dispute lifecycle state. COMPLETED can coexist with a resolved SEPA_XML failure; it does not certify bank settlement or permission to resume an abonnement."
          },
          "resolution": {
            "type": "string",
            "enum": [
              "UNKNOWN",
              "RESOLVED"
            ],
            "description": "RESOLVED requires the SEPA_XML owner's explicit valid resolvedAt. All other sources remain UNKNOWN; absence of resolution is not evidence that a dispute is open."
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Persisted incident instant; null when absent or invalid. Stripe payment-failure snapshots have no dedicated persisted event instant and return null. Never replaced by payment datetime or the current time."
          },
          "observedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Null in this version: no separate provider observation is read. No freshness guarantee is provided."
          },
          "resolvedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Persisted SEPA_XML resolution instant, otherwise null. Resolution of funds does not authorise resuming an abonnement."
          }
        }
      },
      "PaymentExportResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data",
          "totals",
          "meta"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "$ref": "#/components/schemas/PaymentExportRecord"
            }
          },
          "totals": {
            "type": "array",
            "maxItems": 10000,
            "items": {
              "$ref": "#/components/schemas/PaymentExportTotal"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/PaymentExportMeta"
          }
        }
      },
      "PaymentExportRecord": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "recordedAt",
          "associationId",
          "instrument",
          "currency",
          "state",
          "imported",
          "recordKind",
          "amountMinor"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Stable payment-attempt UUID. Several attempts may concern the same subscription occurrence; no occurrence count is inferred."
          },
          "recordedAt": {
            "type": "string",
            "format": "date-time",
            "description": "The stored datetime normalised to a UTC instant. This is usually preparation time online or the supplied business date for manual entry/import, not bank settlement or receipt-issue time."
          },
          "associationId": {
            "type": "string",
            "nullable": true,
            "description": "Stored beneficiary association UUID or MAIN. Missing or malformed values remain null; no current organisation default is substituted."
          },
          "instrument": {
            "type": "string",
            "nullable": true,
            "enum": [
              "CASH",
              "CHEQUE",
              "VIREMENT",
              "PRELEVEMENT",
              "CB",
              "NATURE",
              null
            ],
            "description": "Stored payment instrument. NATURE is an in-kind record. Missing or unsupported instruments remain null; no instrument is inferred from the provider."
          },
          "currency": {
            "type": "string",
            "nullable": true,
            "pattern": "^[a-z]{3}$",
            "description": "Stored three-letter currency code, normalised to lowercase. Missing or malformed values remain null; there is no currency conversion or default."
          },
          "state": {
            "type": "string",
            "nullable": true,
            "pattern": "^[A-Z][A-Z0-9_-]{0,63}$",
            "description": "Stored Unisoft state, including future well-formed codes; null when missing or malformed. COMPLETED can mean an Axepta authorisation before capture. REFUND_PENDING and REFUNDED are retained as separate recorded states, not negative cash flows."
          },
          "imported": {
            "type": "boolean",
            "nullable": true,
            "description": "Explicit stored import marker. True, false and absent/invalid (null) are separate groups. An absent marker is not asserted to be a native payment."
          },
          "recordKind": {
            "type": "string",
            "enum": [
              "MONETARY_RECORD",
              "IN_KIND",
              "TECHNICAL",
              "UNKNOWN"
            ],
            "description": "TECHNICAL for ABO_PAUSE, otherwise IN_KIND for NATURE, otherwise MONETARY_RECORD for a recognised instrument and a positive safe stored amount, otherwise UNKNOWN. This classification does not prove receipt of funds."
          },
          "amountMinor": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Nominal stored amount in minor currency units (5000 for EUR 50), including the original positive nominal amount of a refunded record. Null for missing, negative, fractional or unsafe values; technical zero is preserved."
          }
        }
      },
      "PaymentExportTotal": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "associationId",
          "instrument",
          "currency",
          "state",
          "imported",
          "recordKind",
          "recordCount",
          "validAmountCount",
          "unknownAmountCount",
          "amountMinor",
          "amountStatus"
        ],
        "properties": {
          "associationId": {
            "type": "string",
            "nullable": true,
            "description": "Stored beneficiary association UUID or MAIN. Missing or malformed values remain null; no current organisation default is substituted."
          },
          "instrument": {
            "type": "string",
            "nullable": true,
            "enum": [
              "CASH",
              "CHEQUE",
              "VIREMENT",
              "PRELEVEMENT",
              "CB",
              "NATURE",
              null
            ],
            "description": "Stored payment instrument. NATURE is an in-kind record. Missing or unsupported instruments remain null; no instrument is inferred from the provider."
          },
          "currency": {
            "type": "string",
            "nullable": true,
            "pattern": "^[a-z]{3}$",
            "description": "Stored three-letter currency code, normalised to lowercase. Missing or malformed values remain null; there is no currency conversion or default."
          },
          "state": {
            "type": "string",
            "nullable": true,
            "pattern": "^[A-Z][A-Z0-9_-]{0,63}$",
            "description": "Stored Unisoft state, including future well-formed codes; null when missing or malformed. COMPLETED can mean an Axepta authorisation before capture. REFUND_PENDING and REFUNDED are retained as separate recorded states, not negative cash flows."
          },
          "imported": {
            "type": "boolean",
            "nullable": true,
            "description": "Explicit stored import marker. True, false and absent/invalid (null) are separate groups. An absent marker is not asserted to be a native payment."
          },
          "recordKind": {
            "type": "string",
            "enum": [
              "MONETARY_RECORD",
              "IN_KIND",
              "TECHNICAL",
              "UNKNOWN"
            ],
            "description": "TECHNICAL for ABO_PAUSE, otherwise IN_KIND for NATURE, otherwise MONETARY_RECORD for a recognised instrument and a positive safe stored amount, otherwise UNKNOWN. This classification does not prove receipt of funds."
          },
          "recordCount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10000,
            "description": "Number of stored payment records in this exact group. This is neither a bank collection count nor a count of distinct subscription occurrences."
          },
          "validAmountCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000,
            "description": "Records whose nominal amount is a safe non-negative integer, including technical zero. This does not prove financial success."
          },
          "unknownAmountCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000,
            "description": "Records whose nominal amount cannot be interpreted safely. These records are not silently counted as zero."
          },
          "amountMinor": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Exact sum of all nominal amounts in this group only when currency is known, every amount is valid and the sum is safe. Otherwise null. No netting, subtraction of refunds, fees, bank settlement or cross-currency conversion is performed."
          },
          "amountStatus": {
            "type": "string",
            "enum": [
              "COMPLETE",
              "INCOMPLETE",
              "UNKNOWN_CURRENCY",
              "OVERFLOW"
            ],
            "description": "COMPLETE means the nominal sum is exact; UNKNOWN_CURRENCY takes precedence when currency is absent, then INCOMPLETE when an amount is invalid, then OVERFLOW when the exact integer sum exceeds JavaScript's safe range. An unknown total is never zero."
          }
        }
      },
      "PaymentExportMeta": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "period",
          "count",
          "matchedRecordCount",
          "hasMore",
          "nextCursor",
          "totalsScope",
          "totalMeaning",
          "bankSettlementVerified",
          "snapshot",
          "excludedInvalidDatetimeCount"
        ],
        "properties": {
          "period": {
            "$ref": "#/components/schemas/PaymentExportPeriod"
          },
          "count": {
            "type": "integer",
            "minimum": 0,
            "maximum": 200
          },
          "matchedRecordCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000,
            "description": "Matching, non-deleted records with a supported datetime in the filtered period. Does not claim completeness of the real-world financial history."
          },
          "hasMore": {
            "type": "boolean"
          },
          "nextCursor": {
            "type": "string",
            "nullable": true,
            "maxLength": 2048,
            "description": "Opaque continuation for the same organisation, campaign restriction and filters. Null on the final page. Limit may change between pages; the result is not a snapshot."
          },
          "totalsScope": {
            "type": "string",
            "enum": [
              "FILTERED_PERIOD"
            ],
            "description": "Totals always cover the entire filtered period returned by the current read, including rows before and after the current page. Do not add the repeated period totals across pages."
          },
          "totalMeaning": {
            "type": "string",
            "enum": [
              "RECORDED_NOMINAL_AMOUNTS"
            ]
          },
          "bankSettlementVerified": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "snapshot": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "excludedInvalidDatetimeCount": {
            "type": "integer",
            "nullable": true,
            "enum": [
              null
            ],
            "description": "Always null: this operation cannot place missing or unsupported historical datetimes in a period and does not count them. Null means unknown, not zero excluded records."
          }
        }
      },
      "PaymentExportPeriod": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "from",
          "to",
          "datetimeField",
          "upperBoundExclusive"
        ],
        "properties": {
          "from": {
            "type": "string",
            "format": "date-time",
            "description": "Inclusive UTC-normalised lower bound on stored payment datetime."
          },
          "to": {
            "type": "string",
            "format": "date-time",
            "description": "Exclusive UTC-normalised upper bound on stored payment datetime."
          },
          "datetimeField": {
            "type": "string",
            "enum": [
              "datetime"
            ]
          },
          "upperBoundExclusive": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        }
      },
      "PaymentExportError": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "PaymentTreasurySnapshotResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/PaymentTreasurySnapshot"
          }
        }
      },
      "PaymentTreasurySnapshot": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "paymentId",
          "coverage",
          "observations",
          "providerRefreshed",
          "bankVerified"
        ],
        "properties": {
          "paymentId": {
            "type": "string",
            "format": "uuid"
          },
          "providerRefreshed": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "bankVerified": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "coverage": {
            "type": "string",
            "enum": [
              "PERSISTED_SNAPSHOT",
              "NOT_SYNCHRONIZED"
            ]
          },
          "observations": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "accountKey",
                "livemode",
                "presentment",
                "settlement",
                "captured",
                "amountRefunded",
                "disputed",
                "maturity",
                "observedAt",
                "stale"
              ],
              "properties": {
                "accountKey": {
                  "type": "string",
                  "pattern": "^(test|live):acct_[A-Za-z0-9]+$"
                },
                "livemode": {
                  "type": "boolean"
                },
                "presentment": {
                  "type": "object",
                  "nullable": true,
                  "additionalProperties": false,
                  "required": [
                    "amount",
                    "currency",
                    "exponent"
                  ],
                  "properties": {
                    "amount": {
                      "type": "integer",
                      "minimum": -9007199254740991,
                      "maximum": 9007199254740991
                    },
                    "currency": {
                      "type": "string",
                      "pattern": "^[a-z]{3}$"
                    },
                    "exponent": {
                      "type": "integer",
                      "enum": [
                        0,
                        2
                      ]
                    }
                  }
                },
                "settlement": {
                  "type": "object",
                  "nullable": true,
                  "additionalProperties": false,
                  "required": [
                    "amount",
                    "currency",
                    "exponent",
                    "fee",
                    "net",
                    "exchangeRate"
                  ],
                  "properties": {
                    "amount": {
                      "type": "integer",
                      "minimum": -9007199254740991,
                      "maximum": 9007199254740991
                    },
                    "currency": {
                      "type": "string",
                      "pattern": "^[a-z]{3}$"
                    },
                    "exponent": {
                      "type": "integer",
                      "enum": [
                        0,
                        2
                      ]
                    },
                    "fee": {
                      "type": "integer",
                      "minimum": -9007199254740991,
                      "maximum": 9007199254740991
                    },
                    "net": {
                      "type": "integer",
                      "minimum": -9007199254740991,
                      "maximum": 9007199254740991
                    },
                    "exchangeRate": {
                      "type": "number",
                      "nullable": true,
                      "minimum": 0,
                      "exclusiveMinimum": true
                    }
                  }
                },
                "captured": {
                  "type": "boolean",
                  "nullable": true
                },
                "amountRefunded": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991,
                  "nullable": true
                },
                "disputed": {
                  "type": "boolean",
                  "nullable": true
                },
                "maturity": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "state",
                    "availableOn"
                  ],
                  "properties": {
                    "state": {
                      "type": "string",
                      "enum": [
                        "PENDING",
                        "AVAILABLE",
                        "NOT_CREATED",
                        "NOT_CAPTURED",
                        "UNKNOWN"
                      ]
                    },
                    "availableOn": {
                      "type": "string",
                      "nullable": true,
                      "format": "date-time"
                    }
                  }
                },
                "observedAt": {
                  "type": "string",
                  "nullable": true,
                  "format": "date-time"
                },
                "stale": {
                  "type": "boolean"
                }
              }
            }
          }
        }
      },
      "PaymentTreasuryCorrectionPageResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/PaymentTreasuryCorrectionPage"
          }
        }
      },
      "PaymentTreasuryCorrectionPage": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "paymentId",
          "coverage",
          "data",
          "total",
          "pagination",
          "providerRefreshed",
          "bankVerified"
        ],
        "properties": {
          "paymentId": {
            "type": "string",
            "format": "uuid"
          },
          "providerRefreshed": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "bankVerified": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "coverage": {
            "type": "string",
            "enum": [
              "PERSISTED_RELATIONS"
            ]
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000
          },
          "pagination": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "current",
              "pageSize"
            ],
            "properties": {
              "current": {
                "type": "integer",
                "minimum": 1,
                "maximum": 100000
              },
              "pageSize": {
                "type": "integer",
                "minimum": 1,
                "maximum": 100
              }
            }
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "accountKey",
                "id",
                "type",
                "status",
                "presentment",
                "reason",
                "createdAt",
                "observedAt",
                "stale"
              ],
              "properties": {
                "accountKey": {
                  "type": "string"
                },
                "id": {
                  "type": "string"
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "refund",
                    "dispute"
                  ]
                },
                "status": {
                  "type": "string",
                  "nullable": true
                },
                "presentment": {
                  "type": "object",
                  "nullable": true,
                  "additionalProperties": false,
                  "required": [
                    "amount",
                    "currency",
                    "exponent"
                  ],
                  "properties": {
                    "amount": {
                      "type": "integer",
                      "minimum": -9007199254740991,
                      "maximum": 9007199254740991
                    },
                    "currency": {
                      "type": "string",
                      "pattern": "^[a-z]{3}$"
                    },
                    "exponent": {
                      "type": "integer",
                      "enum": [
                        0,
                        2
                      ]
                    }
                  }
                },
                "reason": {
                  "type": "string",
                  "nullable": true,
                  "enum": [
                    null
                  ]
                },
                "createdAt": {
                  "type": "string",
                  "nullable": true,
                  "format": "date-time"
                },
                "observedAt": {
                  "type": "string",
                  "nullable": true,
                  "format": "date-time"
                },
                "stale": {
                  "type": "boolean"
                }
              }
            }
          }
        }
      },
      "PaymentTreasuryPayoutPageResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/PaymentTreasuryPayoutPage"
          }
        }
      },
      "PaymentTreasuryPayoutPage": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "paymentId",
          "coverage",
          "data",
          "total",
          "pagination",
          "providerRefreshed",
          "bankVerified"
        ],
        "properties": {
          "paymentId": {
            "type": "string",
            "format": "uuid"
          },
          "providerRefreshed": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "bankVerified": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "coverage": {
            "type": "string",
            "enum": [
              "PERSISTED_RELATIONS"
            ]
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000
          },
          "pagination": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "current",
              "pageSize"
            ],
            "properties": {
              "current": {
                "type": "integer",
                "minimum": 1,
                "maximum": 100000
              },
              "pageSize": {
                "type": "integer",
                "minimum": 1,
                "maximum": 100
              }
            }
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "accountKey",
                "id",
                "role",
                "transactionId",
                "net",
                "currency",
                "exponent",
                "compositionState",
                "status",
                "createdAt",
                "arrivalDate",
                "observedAt",
                "stale",
                "bank"
              ],
              "properties": {
                "accountKey": {
                  "type": "string"
                },
                "id": {
                  "type": "string"
                },
                "role": {
                  "type": "string",
                  "enum": [
                    "PAYMENT",
                    "REFUND",
                    "DISPUTE",
                    "FEES",
                    "OTHER"
                  ]
                },
                "transactionId": {
                  "type": "string",
                  "nullable": true
                },
                "net": {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                },
                "currency": {
                  "type": "string",
                  "pattern": "^[a-z]{3}$"
                },
                "exponent": {
                  "type": "integer",
                  "enum": [
                    0,
                    2
                  ]
                },
                "compositionState": {
                  "type": "string",
                  "enum": [
                    "VERIFIED"
                  ]
                },
                "status": {
                  "type": "string",
                  "nullable": true
                },
                "createdAt": {
                  "type": "string",
                  "nullable": true,
                  "format": "date-time"
                },
                "arrivalDate": {
                  "type": "string",
                  "nullable": true,
                  "format": "date-time"
                },
                "observedAt": {
                  "type": "string",
                  "nullable": true,
                  "format": "date-time"
                },
                "stale": {
                  "type": "boolean"
                },
                "bank": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "state",
                    "matchedAt"
                  ],
                  "properties": {
                    "state": {
                      "type": "string",
                      "enum": [
                        "UNMATCHED",
                        "CONFLICT",
                        "CONFIRMED",
                        "UNKNOWN"
                      ]
                    },
                    "matchedAt": {
                      "type": "string",
                      "nullable": true,
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "PaymentAllocationPreviewResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/PaymentAllocationPreview"
          }
        }
      },
      "PaymentAllocationPreview": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "paymentId",
          "expectedRevision",
          "amount",
          "devise",
          "assoc",
          "contactId",
          "beforeContactId",
          "contactChanged",
          "dettes",
          "balances",
          "unallocatedAmount",
          "fiscal",
          "receiptSnapshotChanged",
          "bankVerified"
        ],
        "properties": {
          "paymentId": {
            "type": "string",
            "format": "uuid"
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "amount": {
            "type": "integer",
            "minimum": 1
          },
          "devise": {
            "type": "string",
            "pattern": "^[a-z]{3}$"
          },
          "assoc": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "pattern": "^\\S(?:.*\\S)?$"
          },
          "contactId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "pattern": "^\\S(?:.*\\S)?$"
          },
          "beforeContactId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "pattern": "^\\S(?:.*\\S)?$"
          },
          "contactChanged": {
            "type": "boolean"
          },
          "dettes": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "id",
                "montant"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "montant": {
                  "type": "number",
                  "minimum": 0,
                  "exclusiveMinimum": true,
                  "description": "Positive major units, exactly two decimals; response amounts use integer minor units."
                }
              }
            }
          },
          "balances": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "id",
                "amount",
                "remainingBefore",
                "remainingAfter"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 255,
                  "pattern": "^\\S(?:.*\\S)?$"
                },
                "amount": {
                  "type": "integer",
                  "minimum": 1
                },
                "remainingBefore": {
                  "type": "integer",
                  "minimum": 0
                },
                "remainingAfter": {
                  "type": "integer",
                  "minimum": 0
                }
              }
            }
          },
          "unallocatedAmount": {
            "type": "integer",
            "minimum": 0
          },
          "fiscal": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "recordedAmount",
              "expectedForNewAllocation",
              "exception",
              "snapshotChanged"
            ],
            "properties": {
              "recordedAmount": {
                "type": "integer",
                "minimum": 0
              },
              "expectedForNewAllocation": {
                "type": "integer",
                "minimum": 0
              },
              "exception": {
                "type": "boolean"
              },
              "snapshotChanged": {
                "type": "boolean",
                "enum": [
                  false
                ]
              }
            }
          },
          "receiptSnapshotChanged": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "bankVerified": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      },
      "PaymentAllocationCommandResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/PaymentAllocationCommand"
          }
        }
      },
      "PaymentAllocationCommand": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "requestId",
          "paymentId",
          "status",
          "outcome",
          "error",
          "retryable",
          "warnings",
          "receiptSnapshotChanged",
          "bankVerified"
        ],
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "paymentId": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "SUCCEEDED",
              "REFUSED",
              "UNCERTAIN"
            ]
          },
          "outcome": {
            "type": "string",
            "nullable": true,
            "enum": [
              "ACCOUNTING_UPDATED",
              null
            ]
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "retryable": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "CACHE_REFRESH_PENDING",
                "CONTACT_TAG_PENDING"
              ]
            }
          },
          "receiptSnapshotChanged": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "bankVerified": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      },
      "UnisoftRequest_882f91996439f2ac9d1f": {
        "type": "object",
        "properties": {
          "dettes": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "montant": {
                  "type": "number",
                  "description": "Positive major units, exactly two decimals; response amounts use integer minor units.",
                  "minimum": 0,
                  "exclusiveMinimum": true
                }
              },
              "required": [
                "id",
                "montant"
              ],
              "additionalProperties": false
            }
          },
          "contactId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "pattern": "^\\S(?:.*\\S)?$"
          },
          "idempotencyKey": {
            "type": "string",
            "format": "uuid"
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "confirmFiscalException": {
            "type": "boolean",
            "description": "Explicit acknowledgment of the preview fiscal exception. Required true only when recorded historical fiscal amount differs from the policy for the proposed allocation. It authorizes an accounting move, never fiscal document rewriting."
          }
        },
        "required": [
          "dettes",
          "idempotencyKey",
          "expectedRevision",
          "confirmFiscalException"
        ],
        "additionalProperties": false
      },
      "PaymentManualResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/PaymentManualResult"
          }
        }
      },
      "PaymentManualResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "requestId",
          "status",
          "paymentId",
          "outcome",
          "error",
          "bankVerified",
          "retryable",
          "requestedAt",
          "completedAt"
        ],
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "SUCCEEDED",
              "REFUSED",
              "UNCERTAIN"
            ]
          },
          "paymentId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "outcome": {
            "type": "string",
            "enum": [
              "MANUALLY_RECORDED",
              null
            ],
            "nullable": true
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "bankVerified": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "retryable": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "requestedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "completedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "UnisoftRequest_1d110747a2ca9004259d": {
        "type": "object",
        "properties": {
          "idempotencyKey": {
            "type": "string",
            "format": "uuid",
            "description": "Stable UUID for one manual recording intent; reuse exactly the same body after a lost response. A different key can duplicate funds already recorded."
          },
          "confirmation": {
            "type": "string",
            "enum": [
              "FUNDS_OBSERVED"
            ],
            "description": "Explicit caller assertion that the funds have been observed outside this API. This operation performs no bank verification, debit, transfer, mandate or card charge."
          },
          "type": {
            "type": "string",
            "enum": [
              "GENERAL",
              "CAISSE",
              "CAMPAGNE"
            ]
          },
          "typeId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "pattern": "^\\S(?:.*\\S)?$",
            "nullable": true
          },
          "contactId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "pattern": "^\\S(?:.*\\S)?$"
          },
          "montant": {
            "type": "number",
            "maximum": 1000000,
            "description": "Positive major units, exactly representable with two decimals: 125.5 becomes amount 12550.",
            "minimum": 0,
            "exclusiveMinimum": true
          },
          "datetime": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T.*)?$",
            "description": "Explicit real YYYY-MM-DD date interpreted at UTC midnight, or RFC3339 timestamp with offset. The recorded historical payment day is retained; no more than 24 hours into the future."
          },
          "assoc": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "pattern": "^\\S(?:.*\\S)?$"
          },
          "devise": {
            "type": "string",
            "pattern": "^[a-z]{3}$",
            "description": "Explicit lower-case currency matching the legal association and target. For MAIN only, a missing or null association currency inherits the organisation currency, as returned by GET /associations. An explicit association currency remains authoritative. Missing or invalid effective currency, mismatches and secondary associations without their own currency are refused; country never determines currency."
          },
          "method": {
            "type": "string",
            "enum": [
              "CASH",
              "CHEQUE",
              "VIREMENT",
              "PRELEVEMENT",
              "CB",
              "NATURE"
            ]
          },
          "info": {
            "type": "object",
            "properties": {
              "nom": {
                "type": "string",
                "maxLength": 255
              },
              "prenom": {
                "type": "string",
                "maxLength": 255
              },
              "email": {
                "type": "string",
                "maxLength": 320,
                "pattern": "^(?:$|[^\\s@]+@[^\\s@]+\\.[^\\s@]+)$"
              },
              "tel": {
                "type": "string",
                "maxLength": 255
              }
            },
            "required": [
              "nom",
              "prenom",
              "email",
              "tel"
            ],
            "additionalProperties": false
          },
          "facturation": {
            "type": "object",
            "properties": {
              "perso": {
                "type": "boolean"
              },
              "nom": {
                "type": "string",
                "maxLength": 500
              },
              "prenom": {
                "type": "string",
                "maxLength": 500
              },
              "civilite": {
                "type": "string",
                "maxLength": 500
              },
              "raison": {
                "type": "string",
                "maxLength": 500
              },
              "siren": {
                "type": "string",
                "maxLength": 500
              },
              "adresse": {
                "type": "string",
                "maxLength": 500
              },
              "postal": {
                "type": "string",
                "maxLength": 500
              },
              "ville": {
                "type": "string",
                "maxLength": 500
              },
              "etat": {
                "type": "string",
                "maxLength": 500
              },
              "pays": {
                "type": "string",
                "maxLength": 500
              },
              "social_id": {
                "type": "string",
                "maxLength": 500
              },
              "giftAid": {
                "type": "boolean"
              }
            },
            "required": [
              "perso",
              "nom",
              "prenom",
              "civilite",
              "raison",
              "siren",
              "adresse",
              "postal",
              "ville",
              "etat",
              "pays",
              "social_id"
            ],
            "additionalProperties": false
          },
          "cerfa": {
            "type": "boolean",
            "description": "Explicit fiscal document request, subject to the native legal issuer policy. Refused when the association forbids fiscal receipts. No document number or delivery is acknowledged here."
          },
          "dontSendReceipt": {
            "type": "boolean",
            "description": "true suppresses the native receipt email; false enables its normal asynchronous path and requires a valid donor email. It does not suppress document generation or guarantee delivery."
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "commentaire": {
            "type": "string",
            "maxLength": 4000
          }
        },
        "required": [
          "idempotencyKey",
          "confirmation",
          "type",
          "contactId",
          "montant",
          "datetime",
          "assoc",
          "devise",
          "method",
          "info",
          "facturation",
          "cerfa",
          "dontSendReceipt"
        ],
        "additionalProperties": false
      },
      "PaymentCommandResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/PaymentCommandResult"
          }
        }
      },
      "PaymentCommandResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "requestId",
          "action",
          "status",
          "paymentId",
          "url",
          "outcome",
          "error",
          "retryable",
          "requestedAt",
          "completedAt"
        ],
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "action": {
            "type": "string",
            "enum": [
              "CREATE",
              "REVOKE"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "SUCCEEDED",
              "REFUSED",
              "UNCERTAIN"
            ],
            "description": "Command journal status, not the payment financial state. PENDING and UNCERTAIN never permit automatic replay with another key. SUCCEEDED acknowledges the documented owner result only."
          },
          "paymentId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "url": {
            "type": "string",
            "nullable": true,
            "format": "uri"
          },
          "outcome": {
            "type": "string",
            "nullable": true,
            "enum": [
              "REQUEST_CREATED",
              "CANCELED",
              "RECORDED_COMPLETED",
              null
            ]
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "retryable": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "requestedAt": {
            "type": "string",
            "nullable": true,
            "format": "date-time"
          },
          "completedAt": {
            "type": "string",
            "nullable": true,
            "format": "date-time"
          }
        }
      },
      "UnisoftRequest_c6721c5be3f91d5f9f68": {
        "allOf": [
          {
            "$ref": "#/components/schemas/UnisoftRequest_28438f371d8fbf6a8149"
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "GENERAL",
                  "FORM",
                  "DETTE",
                  "CAISSE",
                  "CAMPAGNE"
                ]
              },
              "abo": {
                "type": "boolean",
                "enum": [
                  false
                ]
              },
              "update": {
                "type": "boolean",
                "enum": [
                  false
                ]
              }
            },
            "not": {
              "anyOf": [
                {
                  "required": [
                    "nbMonth"
                  ]
                },
                {
                  "required": [
                    "maxAmount"
                  ]
                },
                {
                  "required": [
                    "id"
                  ]
                }
              ]
            }
          }
        ],
        "type": "object",
        "properties": {
          "externalRef": {},
          "externalMetadata": {},
          "type": {},
          "typeId": {},
          "montant": {},
          "devise": {},
          "name": {},
          "info": {},
          "facturation": {},
          "returnUrl": {},
          "platform": {},
          "abo": {},
          "nbMonth": {},
          "maxAmount": {},
          "assoc": {},
          "cerfa": {},
          "update": {},
          "id": {},
          "service": {},
          "dettes": {}
        },
        "additionalProperties": false,
        "description": "The existing payment-request config, restricted to a new one-off request. montant is in major units, exactly convertible to minor units. Recurring, identity-update and legacy SERVICE intents are excluded. Target, association, currency and billing admission are delegated to the existing strict payment facade."
      },
      "UnisoftRequest_28438f371d8fbf6a8149": {
        "type": "object",
        "properties": {
          "externalRef": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "pattern": "\\S",
            "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.",
            "example": "commande-1234"
          },
          "externalMetadata": {
            "type": "object",
            "maxProperties": 50,
            "additionalProperties": {
              "type": "string",
              "maxLength": 500
            },
            "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.",
            "example": {
              "registrationId": "inscription-567",
              "eventId": "chabbat-890"
            }
          },
          "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",
            "minimum": 0.01,
            "maximum": 1000000,
            "multipleOf": 0.01,
            "description": "Amount in major units (e.g. euros)."
          },
          "devise": {
            "type": "string",
            "nullable": true
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "info": {
            "$ref": "#/components/schemas/UnisoftRequest_b6eaf8c17ece06a2ed03"
          },
          "facturation": {
            "$ref": "#/components/schemas/UnisoftRequest_ef522362195300ba7557"
          },
          "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",
            "enum": [
              false
            ],
            "description": "Only a one-time request is supported here. For a supported subscription use prepare_subscription."
          },
          "nbMonth": {
            "type": "integer",
            "nullable": true
          },
          "maxAmount": {
            "type": "integer",
            "nullable": true
          },
          "assoc": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "Explicit beneficiary association for a GENERAL donation, resolved from list_associations. Omission keeps the owner selection, which may use defaultAssoc and is not guaranteed to be MAIN. Target-linked payment associations are derived by their business owner."
          },
          "cerfa": {
            "type": "boolean"
          },
          "update": {
            "type": "boolean",
            "enum": [
              false
            ],
            "description": "Existing payment updates, including identity completion, are unavailable through this operation. Omit this field or pass false."
          },
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "Historical payment identifier. Supplying it does not authorise updating an existing payment; update and UPDATE mode are unavailable."
          },
          "service": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              }
            },
            "required": [
              "id"
            ],
            "additionalProperties": false,
            "description": "Historical SERVICE target reference. It is not accepted for other payment types."
          },
          "dettes": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 200
                },
                "montant": {
                  "type": "number",
                  "minimum": 0.01,
                  "maximum": 90071992547409,
                  "multipleOf": 0.01
                }
              },
              "required": [
                "id",
                "montant"
              ],
              "additionalProperties": false
            },
            "description": "Authorised pledge allocations in major units; for a recurring request these are contractual allocation budgets, not one instalment."
          }
        },
        "required": [
          "type",
          "montant"
        ],
        "description": "Payment intent for the authenticated organisation. Organisation context is supplied by the server; config.organisation is not an admitted input field."
      },
      "PaymentExistingLinkResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/PaymentExistingLink"
          }
        }
      },
      "PaymentExistingLink": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "paymentId",
          "state",
          "url",
          "source",
          "expiresAt",
          "validity",
          "reason",
          "revocation",
          "providerVerified",
          "notificationSent"
        ],
        "properties": {
          "paymentId": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "nullable": true
          },
          "url": {
            "type": "string",
            "nullable": true,
            "format": "uri"
          },
          "source": {
            "type": "string",
            "nullable": true,
            "enum": [
              "EXTERNAL_COMMAND_JOURNAL",
              "PAYGREEN_NATIVE_GATEWAY",
              null
            ]
          },
          "expiresAt": {
            "type": "string",
            "nullable": true,
            "format": "date-time"
          },
          "validity": {
            "type": "string",
            "enum": [
              "UNAVAILABLE",
              "RECORDED_UNEXPIRED",
              "UNKNOWN"
            ]
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "revocation": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "supported",
              "expectedRevision",
              "reason"
            ],
            "properties": {
              "supported": {
                "type": "boolean"
              },
              "expectedRevision": {
                "type": "string",
                "nullable": true,
                "pattern": "^[a-f0-9]{64}$"
              },
              "reason": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "providerVerified": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "notificationSent": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format: `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
