Payments API Reference

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

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 (e.g. PAID, DRAFT, PENDING, REFUNDED, LOST, FAILED).
setter	string	Optional	Filter by assigned setter email.
closer	string	Optional	Filter by assigned closer email.
triage	string	Optional	Filter by assigned triager email.
lead_id	string (UUID)	Optional	Filter by associated lead UUID.
contract_id	string (UUID)	Optional	Filter by associated contract UUID.

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&triage=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

{
  "status": "success",
  "message": "Payments fetched successfully",
  "data": [
    {
      "id": "0174f917-e7c2-4a27-9aca-2626724c04d5",
      "lead": {
        "id": "308589ca-1e21-4173-96ad-63fff112c864",
        "first_name": "New",
        "last_name": "Lead",
        "email": "new.lead+1@mailinator.com"
      },
      "program": {
        "name": "Large Transactions"
      },
      "amount": 100,
      "payment_date": "2026-03-07T04:30:00.000Z",
      "status": "PAID",
      "provider": "MANUAL",
      "type": "FIRST_PAYMENT",
      "note": "",
      "currency": "eur",
      "created_at": "2026-03-06T12:53:54.181Z",
      "closer": {
        "id": "user_39mYQippFnDajQq1Tgev2QJ2M4o",
        "first_name": "hermon",
        "last_name": "2",
        "profile_image_url": "https://img.clerk.com/eyJ0eXBlIjoiZGVmYXVsdCIsImlpZCI6Imluc18zN0lDNG9PRFg5cEdnYzdHOEdZa3ZObXJXRloiLCJyaWQiOiJ1c2VyXzM5bVlRaXBwRm5EYWpRcTFUZ2V2MlFKMk00byIsImluaXRpYWxzIjoiSDIifQ"
      },
      "setter": null,
      "triager": null
    }
  ],
  "totals": {
    "amount": 0,
    "currency": null,
    "by_currency": [
      {
        "currency": "EUR",
        "amount": 273739.67
      },
      {
        "currency": "USD",
        "amount": 226187.36
      }
    ]
  },
  "totals_page": {
    "amount": 0,
    "currency": null,
    "by_currency": [
      {
        "currency": "EUR",
        "amount": 4897
      },
      {
        "currency": "USD",
        "amount": 1099.9
      }
    ]
  },
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 351,
    "totalPages": 36,
    "hasNext": true,
    "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 record.
lead	object	Associated lead summary details (id, first_name, last_name, email, and optionally sales_status).
program	object	Associated program summary details (name).
amount	number	Transaction amount.
payment_date	string \| null	ISO 8601 timestamp of payment date [List API Only].
due_date	string \| null	ISO 8601 timestamp of payment due date [Details API Only].
status	string	State of transaction (e.g. PAID, DRAFT, PENDING, REFUNDED).
provider	string	Gateway/origin provider name (e.g. MANUAL, STRIPE, WHOP, MOLLIE) [List API Only].
payment_provider	string	Gateway/origin provider name (e.g. MANUAL, STRIPE, WHOP, MOLLIE) [Details API Only].
type	string	Billing type identifier (e.g. FIRST_PAYMENT, INSTALMENT, DEPOSIT).
note	string \| null	Internal notes associated with the payment.
currency	string	ISO 4217 currency code (e.g. usd, eur).
created_at	string	ISO 8601 timestamp of payment creation.
closer	object \| null	Closer profile details (id, first_name, last_name, profile_image_url) [List API Only].
setter	object \| null	Setter profile details [List API Only].
triager	object \| null	Triager profile details [List API Only].
contract	object	Linked contract information (id, status, program: { name }) [Details API Only].
paid_at	string \| null	ISO 8601 timestamp when successful transaction settled [Details API Only].
failure_reason	string \| null	Reason for transaction failure if applicable [Details API Only].
is_mandate_payment	boolean	Whether payment was triggered automatically [Details API Only].
refunds	array	Array of refunds associated with the payment [Details API Only].
payment_links	array	Shared secure payment gateway sessions [Details API Only].
payment_proofs	array	Uploaded receipt and billing file summaries (id, file_name, mime_type, file_size_bytes, uploaded_by, created_at, url) [Details API Only].
unmatched_payment	object \| null	Reference payload if payment is unlinked [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

{
  "status": "success",
  "message": "Payment fetched successfully",
  "data": {
    "id": "0174f917-e7c2-4a27-9aca-2626724c04d5",
    "lead": {
      "id": "308589ca-1e21-4173-96ad-63fff112c864",
      "first_name": "New",
      "last_name": "Lead",
      "email": "new.lead+1@mailinator.com",
      "sales_status": {
        "id": "4974210a-0c10-4f9a-897b-dd2527b1c374",
        "name": "Rescheduled",
        "text_color": "#0095B9",
        "bg_color": "#ECFEFF"
      }
    },
    "contract": {
      "id": "f82d8745-6c0c-47c7-9e16-075b51a45c80",
      "status": "SENT",
      "program": {
        "name": "Large Transactions"
      }
    },
    "amount": 100,
    "currency": "eur",
    "note": "",
    "due_date": "2026-03-07T04:30:00.000Z",
    "status": "PAID",
    "payment_provider": "MANUAL",
    "type": "FIRST_PAYMENT",
    "paid_at": "2026-03-06T12:54:22.564Z",
    "created_at": "2026-03-06T12:53:54.181Z",
    "failure_reason": null,
    "is_mandate_payment": false,
    "refunds": [],
    "payment_links": [],
    "payment_proofs": [
      {
        "id": "20749184-8027-47a6-8491-0ae327fd2adf",
        "file_name": "accents.png",
        "mime_type": "image/png",
        "file_size_bytes": 1433369,
        "uploaded_by": "user_39btCx7wm2Vwgr2eHmhRLxNanxI",
        "created_at": "2026-03-06T12:54:22.594Z",
        "url": "https://hermon-dv.ams3.digitaloceanspaces.com/org_39btEvzPIhOBFQQF831vmVqsTry/payment_proofs/0174f917-e7c2-4a27-9aca-2626724c04d5/06ffd387-45b5-4248-9725-d8a49084b17d.png"
      }
    ],
    "unmatched_payment": null
  }
}

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"
}