Fiscal Classification API

Authentication

Every request must carry an API key in the Authorization header using the Bearer scheme. Keys are issued from the Gratias back-office and shown only once at creation. A key must hold the fiscal:classify scope to call the classification endpoint.

Authorization: Bearer grt_live_xxxxxxxxxxxx.xxxxxxxxxxxxxxxx

Each authenticated call counts against the key's daily quota. Once the quota is reached, further calls return 429 until the next UTC day.

POST /api/public/fiscal/classify

Send the situation to classify as a JSON body. All fields are inputs you provide; none are read from Gratias data.

Request body

Example request

curl -X POST https://your-domain.example/api/public/fiscal/classify \
  -H "Authorization: Bearer grt_live_xxxxxxxxxxxx.xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "FR",
    "year": 2027,
    "month": 3,
    "monthlyBaseCents": 200000,
    "tipsCents": 40000
  }'

Response

Example response

{
  "statusKind": "exempt",
  "ruleCode": "FR_EXO_2026_S2",
  "legalRef": "LF 2026 art. 5; revalorisation SMIC 1er juin 2026",
  "disclaimer": "This classification is derived solely from the inputs you provided. It is not tax advice and does not read any establishment or individual data. Confirm with a qualified local tax professional before relying on it."
}

Error codes

Errors return a JSON body with an error message and a stable code. Validation errors (400) also include an issues array describing the offending fields. No internal detail is ever disclosed.

Gratitude Kit (embedded thank-you journey)

The Gratitude Kit lets a chain application embed a house's thank-you journey directly inside its own experience (an overlay or an iframe). The guest chooses an amount and pays without leaving the host app.

The payment is always a direct debit from the guest to the employee's wallet through the Gratias PSP. The host application never touches the funds and never receives any individual data: no amount, no employee, no balance.

Requirements

• An API key holding the embed:tip scope.
• Each embedding origin (for example https://app.your-chain.example) registered in the key's allowlist. Origins are managed in the Gratias back-office, per key.

GET /api/public/embed/context

Called from your backend to discover the embedding configuration for your key. Authenticate with the key in the Authorization header (Bearer scheme) and pass the embedding origin in the Origin header (or an ?origin= query parameter). The response carries only technical embedding facts.

curl "https://your-domain.example/api/public/embed/context" \
  -H "Authorization: Bearer grt_live_xxxxxxxxxxxx.xxxxxxxxxxxxxxxx" \
  -H "Origin: https://app.your-chain.example"

Response

Error codes

Integration snippet

Paste the following web component in your host app. It defines a <tacitapay-thankyou> element that mounts the journey in an iframe on the Gratias origin, so the settlement happens on our PSP. Never paste your key secret: the snippet only references the key prefix.

<!-- Gratias: parcours de remerciement embarque. Cle: grt_live_xxxxxxxxxxxx -->
<!-- D49: le paiement est un debit DIRECT du client vers le wallet du salarie via -->
<!-- notre PSP. Cette app ne touche jamais les fonds. Ne collez jamais votre secret ici. -->
<script>
(function () {
  if (customElements.get("tacitapay-thankyou")) return;
  var BASE = "https://gratias.io";
  customElements.define(
    "tacitapay-thankyou",
    class extends HTMLElement {
      connectedCallback() {
        var token = this.getAttribute("token") || "";
        var frame = document.createElement("iframe");
        frame.src = BASE + "/embed/" + encodeURIComponent(token);
        frame.setAttribute("title", "Gratias");
        frame.setAttribute("allow", "payment " + BASE);
        frame.setAttribute("loading", "lazy");
        frame.style.border = "0";
        frame.style.width = "100%";
        frame.style.height = this.getAttribute("height") || "720px";
        this.replaceChildren(frame);
      }
    }
  );
})();
</script>
<!-- Usage: <tacitapay-thankyou token="LE_JETON_DU_SALARIE"></tacitapay-thankyou> -->

Usage: <tacitapay-thankyou token="THE_EMPLOYEE_TOKEN"></tacitapay-thankyou>. Only origins present in the key's allowlist are allowed to embed the journey; any other origin is refused.

OpenAPI specification

A machine-readable OpenAPI 3.0 document is served at /api/public/fiscal/openapi.json. It describes only caller-provided inputs and technical outputs, with no individual amounts from the platform.