Payments API Reference

Query payment transactions, deposits, installment logs, and refund status for payments managed by Hermon.

Date & Timezone Handling: All timestamps in responses are UTC, formatted as ISO 8601 (2026-01-15T10:30:00.000Z). Date-range filters accept either date-only YYYY-MM-DD (which expands to UTC day boundaries) or full ISO 8601 timestamps.
Amounts: All monetary values are in major currency units (e.g. 997.50 for $997.50). The currency field is returned as an ISO 4217 code (e.g. USD, EUR).
VAT Calculation: VAT details are computed based on provider-reported data and org configuration. vat_exempt indicates whether the payment was exempted from VAT.

List Payments

Retrieve a paginated list of payments. Results can be filtered by status, lead, contract, and assigned setter, closer, or triager.

GET/api/external/payments

Query Parameters

Parameter	Type	Required	Description
page	integer	Optional	Page number for pagination. Default: 1
limit	integer	Optional	Number of items per page. Default: 10, Max: 100
status	string	Optional	Filter by payment status. See Payment Status Values.
lead_id	string (UUID)	Optional	UUID of the lead to filter payments by.
contract_id	string (UUID)	Optional	UUID of the contract to filter payments by.
setter	string	Optional	Email address of the setter to filter by.
triager	string	Optional	Email address of the triager to filter by.
closer	string	Optional	Email address of the closer to filter by.
due_date_from	string	Optional	Lower bound for due_date. Accepts YYYY-MM-DD or ISO 8601.
due_date_to	string	Optional	Upper bound for due_date. Accepts YYYY-MM-DD or ISO 8601.
paid_date_from	string	Optional	Lower bound for paid_at. Same format rules as due_date_from.
paid_date_to	string	Optional	Upper bound for paid_at. Same format rules as due_date_to.
created_from	string	Optional	Lower bound for created_at.
created_to	string	Optional	Upper bound for created_at.

Totals Information:

totals aggregates net amounts across all pages matching filters.
totals_page aggregates net amounts for the current page only.
If payments span multiple currencies, the root amount defaults to null and aggregates are listed in a by_currency array.

Code Examples

curl -X GET "https://api.hermon.io/api/external/payments?page=1&limit=10&status=REFUNDED&setter=sales-setter@mailinator.com&closer=hermon@mailinator.com&triager=triager@mailinator.com&lead_id=e799c30f-9da7-4fd7-9552-83b96a9bfac2&contract_id=d5e0fb5d-5b14-45cf-81d8-2a0eb7a49224" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_your_key_here"

Response Example

json

{
  "success": true,
  "message": "Payments fetched successfully",
  "data": [
    {
      "id": "pay_d4e5f6a7-b8c9-0123-defg-234567890123",
      "lead": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com"
      },
      "is_mandate_payment": false,
      "amount": 997.0,
      "vat_rate": 0.21,
      "vat_amount": 209.37,
      "gross_amount": 1206.37,
      "vat_exempt": false,
      "currency": "USD",
      "due_date": "2026-02-10T00:00:00.000Z",
      "status": "PAID",
      "payment_provider": "STRIPE",
      "type": "DEPOSIT",
      "paid_at": "2026-02-10T14:30:00.000Z",
      "created_at": "2026-02-08T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

Get Payment Details

Fetch detailed information for a single payment transaction by its unique UUID.

GET/api/external/payments/:id

Path Parameters

:idRequired. The unique payment UUID.

Payment Object Fields

Field	Type	Description
id	string (UUID)	Unique identifier for the payment.
lead	object	Lead linked to this payment (id, first_name, last_name, email). See Payment Lead Object.
first_source	object \| null	Lead's first attribution source [Details API Only].
last_source	object \| null	Lead's last attribution source [Details API Only].
custom_fields	array	Custom field values [Details API Only].
is_mandate_payment	boolean	Whether the payment was charged automatically via a mandate.
payment_proofs	array	List of uploaded payment proofs. See Payment Proof Object [Details API Only].
amount	number	Amount in major currency units.
vat_rate	number	VAT rate applied (e.g. 0.21 for 21%).
vat_amount	number	VAT portion of the payment in major currency units.
gross_amount	number	Total payment including VAT (amount + vat_amount).
vat_exempt	boolean	Whether this payment is VAT exempt.
processor_fee_amount	number \| null	Payment processor fee in major units of processor fee currency [Details API Only].
cycle_gross_amount	number \| null	Per-cycle gross amount [Details API Only].
pause_credit_applied	number \| null	Amount of pause credit applied to this payment [Details API Only].
pause_credit_for_id	string \| null	UUID of the payment that generated the pause credit [Details API Only].
is_pause_credit	boolean	Whether this payment represents a pause credit adjustment [Details API Only].
contract	object \| null	Contract linked to this payment. See Payment Contract Object [Details API Only].
currency	string	ISO 4217 currency code (e.g. USD, EUR).
due_date	string (ISO 8601)	Due date of the payment.
status	string (enum)	Current status (DRAFT, PENDING, PAID, FAILED, LOST, REFUNDED).
payment_provider	string (enum)	Payment gateway (STRIPE, WHOP, MOLLIE, MANUAL).
type	string (enum)	Payment type (DEPOSIT, FIRST_PAYMENT, INSTALMENT, SUBSCRIPTION_CYCLE).
paid_at	string (ISO 8601) \| null	UTC timestamp when successfully paid. null if unpaid.
created_at	string (ISO 8601)	UTC timestamp when the payment was created.
failure_reason	string \| null	Detailed reason if the payment failed [Details API Only].
card_last4	string \| null	Last 4 digits of the payment card (Stripe/Whop only) [Details API Only].
card_brand	string \| null	Brand of the payment card (e.g. visa, mastercard) [Details API Only].
customer_email	string \| null	Customer email registered with the payment provider [Details API Only].
processor_fee_currency	string \| null	Currency of the processor fee [Details API Only].
refunds	array	List of refunds processed against this payment. See Payment Refund Object [Details API Only].
payment_links	array	Stripe/Mollie payment links generated for this invoice. See Payment Link Object [Details API Only].
unmatched_payment	object \| null	Unmatched transaction details if manually reconciled [Details API Only].

Code Examples

curl -X GET "https://api.hermon.io/api/external/payments/0174f917-e7c2-4a27-9aca-2626724c04d5" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_your_key_here"

Response Example

json

{
  "success": true,
  "message": "Payment fetched successfully",
  "data": {
    "id": "pay_d4e5f6a7-b8c9-0123-defg-234567890123",
    "lead": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "sales_status": {
        "id": "status_xyz789",
        "name": "Closed Won",
        "text_color": "#14532D",
        "bg_color": "#DCFCE7"
      }
    },
    "first_source": {
      "id": "src_abc",
      "name": "Facebook Ad"
    },
    "last_source": {
      "id": "src_def",
      "name": "Referral"
    },
    "custom_fields": [],
    "is_mandate_payment": false,
    "payment_proofs": [],
    "amount": 997.0,
    "vat_rate": 0.21,
    "vat_amount": 209.37,
    "gross_amount": 1206.37,
    "vat_exempt": false,
    "processor_fee_amount": 30.5,
    "cycle_gross_amount": null,
    "pause_credit_applied": null,
    "pause_credit_for_id": null,
    "is_pause_credit": false,
    "contract": {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "status": "SIGNED",
      "type": "PP",
      "program": {
        "name": "12-Week Coaching Program"
      },
      "payment_mandate": {
        "status": "VALID",
        "payment_provider": "STRIPE"
      },
      "subscription": null
    },
    "currency": "USD",
    "due_date": "2026-02-10T00:00:00.000Z",
    "status": "PAID",
    "payment_provider": "STRIPE",
    "type": "DEPOSIT",
    "paid_at": "2026-02-10T14:30:00.000Z",
    "created_at": "2026-02-08T10:00:00.000Z",
    "failure_reason": null,
    "card_last4": "4242",
    "card_brand": "visa",
    "customer_email": "john.doe@example.com",
    "processor_fee_currency": "USD",
    "refunds": [],
    "payment_links": [
      {
        "id": "link_abc123",
        "note": null,
        "status": "USED",
        "url": "https://pay.stripe.com/xyz",
        "provider_link_id": "pi_abc123",
        "created_at": "2026-02-08T10:00:00.000Z"
      }
    ],
    "unmatched_payment": null
  }
}

Values Reference

Payment Status Values

Value	Description
DRAFT	Created but not yet sent/due
PENDING	Awaiting payment from client
PAID	Successfully paid
FAILED	Payment attempt failed
LOST	Payment deemed uncollectable
REFUNDED	Payment refunded to client

Payment Type Values

Value	Description
FIRST_PAYMENT	Initial payment (often used with subscriptions)
DEPOSIT	Deposit/down payment
INSTALMENT	Payment plan instalment
SUBSCRIPTION_CYCLE	Recurring subscription charge

Payment Provider Values

Value	Description
STRIPE	Stripe
WHOP	Whop
MOLLIE	Mollie
MANUAL	Manual / offline payment

Nested Objects Reference

Payment Lead Object (List API)

Field	Type	Description
id	string	Lead ID
first_name	string	First name
last_name	string	Last name
email	string	Email address

Payment Lead Object (Detail API)

Field	Type	Description
id	string	Lead ID
first_name	string	First name
last_name	string	Last name
email	string	Email address
sales_status	object	Current lead status with id, name, text_color, bg_color

User Details Object

Field	Type	Description
first_name	string	First name
last_name	string	Last name
profile_image_url	string	Profile image URL (null if none)
id	string	Clerk user ID
role	string	Organization role

Payment Contract Object

Field	Type	Description
id	string	Contract ID
status	string	Contract status
type	string	Contract type enum
program	object	Program with name
payment_mandate	object	Mandate info with status and payment_provider (null if no mandate)
subscription	object	Subscription info (null for non-subscription contracts)

Refund Object

Field	Type	Description
id	string	Refund ID
amount	number	Refund amount in major units
reason	string	Reason for refund
status	string (enum)	Refund status (INITIATED, SUCCEEDED, FAILED)
currency	string	Currency code
refunded_at	string (ISO 8601)	When refund was processed
failure_reason	string	Failure reason (if status is FAILED)
created_at	string (ISO 8601)	When refund was initiated

Payment Link Object

Field	Type	Description
id	string	Link ID
note	string	Optional note about the link
status	string (enum)	Link status (ACTIVE, USED, INVALID)
url	string	Payment link URL
provider_link_id	string	Provider's link identifier
created_at	string (ISO 8601)	When the link was created

Payment Proof Object

Field	Type	Description
id	string	Proof ID
file_name	string	Original file name
mime_type	string	MIME type (e.g. "image/jpeg")
file_size_bytes	integer	File size in bytes
uploaded_by	string	Clerk user ID who uploaded
created_at	string (ISO 8601)	When uploaded
url	string	Pre-signed download URL (expires in 1 hour)

Error Responses

401Missing or invalid API key

json

{
  "status": "error",
  "message": "Invalid or revoked API key"
}

404Resource not found

json

{
  "status": "error",
  "message": "Resource not found"
}

429Rate limit exceeded

json

{
  "status": "error",
  "message": "Too many requests"
}