3. Application and webhook

The individual merchant has a personal application. Its id must be sent in the X-Application-ID header of every API-key call. Then configure the address that will receive webhooks.

Get your personal application

GET/applicationsSession token

Response 200

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1,
        "name": "Nom Prénom",
        "webhook_url": null,
        "has_webhook": false,
        "is_active": true,
        "created_at": "2026-11-02T08:00:00Z"
      }
    ],
    "pagination": {
      "...": "..."
    }
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}

Code	When
401	Missing or expired token.

Configure the webhook (recommended)

PATCH/applications/{id}Session token

Sets the HTTPS address of your server that will receive status-change notifications (see the Webhooks appendix).

Request body

{
  "webhook_url": "https://mon-site.cm/webhooks/kratospay"
}

Response 200

{
  "success": true,
  "data": {
    "id": 1,
    "webhook_url": "https://mon-site.cm/webhooks/kratospay",
    "has_webhook": true,
    "updated_at": "..."
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}

Code	When
404	Application not found.
422	Invalid URL.

Get the webhook signing secret

POST/applications/{id}/webhook/rotate-secretSession token

Generates a signing secret, shown only once. It is used to check that each webhook really comes from Kratos Pay. Calling it again immediately invalidates the previous secret.

Response 200

{
  "success": true,
  "data": {
    "application": {
      "id": 1,
      "webhook_url": "https://mon-site.cm/webhooks/kratospay",
      "has_webhook": true
    },
    "webhook_secret": "whsec_<secret>"
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}

Code	When
404	Application not found.