Introducing the Calmony Pay API Docs

Release: v1.0.19

Calmony Pay now ships a built-in /docs page — a complete API reference baked directly into the platform. Whether you're integrating for the first time or looking up a webhook payload shape, everything you need is in one place.

---

What's included

Endpoint reference

Every public API endpoint is documented with:

• HTTP method and path
• A plain-English description of what the endpoint does
• All accepted parameters (required and optional) with their types
• Full JSON request body shapes
• Full JSON response shapes, including error envelopes

cURL examples

Each endpoint ships with a copy-paste curl command so you can hit the API in seconds without writing any code:

curl -X POST https://api.calmonypay.com/v1/payments \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500,
    "currency": "GBP",
    "customer_id": "cus_abc123",
    "description": "Invoice #1042"
  }'

Authentication guide

The authentication section covers:

• How to generate and rotate API keys from the dashboard
• Passing your key as a Bearer token in the Authorization header
• Key scoping — the difference between live and test keys
• Security best practices (never exposing secret keys client-side, environment variable storage)

Webhook setup

The webhook documentation walks through:

• Registering a webhook endpoint URL
• The full list of event types Calmony Pay emits (e.g. payment.succeeded, payment.failed, invoice.created, subscription.renewed)
• How to verify the Calmony-Signature header to authenticate incoming events
• Example event payloads in JSON

{
  "id": "evt_01J4XZ...",
  "type": "payment.succeeded",
  "created_at": "2025-06-01T10:32:00Z",
  "data": {
    "payment_id": "pay_01J4XY...",
    "amount": 2500,
    "currency": "GBP",
    "status": "succeeded"
  }
}

SDK installation

The SDK section covers installing and initialising Calmony Pay in your project:

# npm
npm install @calmonypay/sdk

# yarn
yarn add @calmonypay/sdk

import { CalmonyPay } from '@calmonypay/sdk';

const client = new CalmonyPay({
  apiKey: process.env.CALMONY_PAY_SECRET_KEY,
});

MDX-powered documentation components

The /docs page is built with MDX and a set of reusable documentation components:

Component	Purpose
<CodeBlock>	Syntax-highlighted code with language label and copy button
<ParamTable>	Structured table of parameters with type and required badges
<Callout>	Info, warning, and danger callout boxes
<EndpointBadge>	Coloured HTTP method badge (GET, POST, DELETE, etc.)

These components are consistent across every endpoint page, making it easy to scan and compare endpoints.

---

Accessing the docs

Navigate to /docs in your Calmony Pay dashboard or visit the public documentation URL. No login is required to read the reference — authentication is only needed to run live API calls.

---

Feedback

If you spot a missing endpoint, an incorrect example, or want to request a new SDK language binding, open an issue or reach out via the support channel.