Payment History

Retrieve the payment transaction history for the organization, including successful payments, failed payments, and pending charges.

Request

GET /billing/payments

Authentication

Requires an Admin Bearer JWT token.

Authorization: Bearer <access_token>

Query Parameters

None.

Response

Returns an array of payment transaction objects sorted by creation date (most recent first).

Success Response

Status Code: 200 OK

Response Body:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "planName": "Professional",
    "amountCents": 4900,
    "currency": "EUR",
    "status": "COMPLETED",
    "cardNumberMasked": "**** **** **** 4242",
    "failureReason": null,
    "createdAt": "2026-02-01T00:00:00Z"
  }
]

Response Fields

Field	Type	Description
id	UUID	Unique identifier for the payment transaction
planName	string	Human-readable name of the plan
amountCents	integer	Payment amount in cents
currency	string	Currency code (e.g., EUR, USD)
status	string	Payment status: COMPLETED, FAILED, or PENDING
cardNumberMasked	string	Masked card number used for payment
failureReason	string	Reason for failure if status is FAILED (null otherwise)
createdAt	string	ISO timestamp when the payment was initiated

Payment Status Values

Status	Description
COMPLETED	Payment was successfully processed
FAILED	Payment failed (see failureReason for details)
PENDING	Payment is being processed

Common Failure Reasons

• Insufficient funds
• Card expired
• Card declined
• Invalid card number
• Payment provider error

Errors

Status Code	Error Code	Description
401	UNAUTHORIZED	Missing or invalid JWT token
403	FORBIDDEN	User does not have admin privileges

Example

Request

curl -X GET https://api.entryguard.io/api/v1/billing/payments \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "planName": "Professional",
    "amountCents": 4900,
    "currency": "EUR",
    "status": "COMPLETED",
    "cardNumberMasked": "**** **** **** 4242",
    "failureReason": null,
    "createdAt": "2026-02-01T00:00:00Z"
  },
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "planName": "Professional",
    "amountCents": 4900,
    "currency": "EUR",
    "status": "COMPLETED",
    "cardNumberMasked": "**** **** **** 4242",
    "failureReason": null,
    "createdAt": "2026-01-01T00:00:00Z"
  },
  {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "planName": "Starter",
    "amountCents": 1900,
    "currency": "EUR",
    "status": "FAILED",
    "cardNumberMasked": "**** **** **** 5555",
    "failureReason": "Insufficient funds",
    "createdAt": "2025-12-15T00:00:00Z"
  }
]

Notes

• Payment history is retained indefinitely for compliance and auditing purposes.
• Failed payments trigger email notifications to the billing contact.
• After a failed payment, the account enters a grace period before being suspended.
• All payment transactions are logged in the audit trail.