Charges

Overview

Charges represent payment transactions against invoices. They record the amount collected, payment method used, and transaction status. Charges can be created automatically when invoices are paid online or manually for offline payments.

How It Works

Invoice created - A customer receives an invoice for a subscription or one-time charge
Payment attempted - The system charges the customer's payment method
Charge recorded - A charge record is created with the transaction details
Status updated - The charge status reflects whether payment succeeded or failed

Example: A customer's subscription renews, creating a $99 invoice. The system charges their credit card and creates a charge record showing the $99 amount, "succeeded" status, and the last 4 digits of the card used.

API Endpoints

Method	Endpoint	Description
`GET`	`/charges`	List charges
`POST`	`/charges`	Create offline charge
`GET`	`/charges/{id}`	Get charge

Important Behaviors

Offline only: The Core API only supports creating offline charges (check, wire, transfer, external, cash). Online charges are handled by Stripe.
Auto-defaults on create: Multiple fields are set automatically — created (now), offline (true), paid (true), status (succeeded).
Currency normalization: The currency field is automatically lowercased.
Balance credit: If no invoice_id is provided, the charge amount is credited to the customer's balance.
Invoice link: If invoice_id is provided, the charge is linked to that invoice.
Customer currency update: The customer's currency is updated to match the charge currency on creation.
Metadata filtering: Keys starting with pelcro are stripped from metadata in responses.
Events: A ChargeSucceeded event is fired after creation.

Charge Statuses

Status	Description
`succeeded`	Payment was successfully collected
`failed`	Payment attempt failed
`pending`	Payment is being processed

Offline Charges

Use the POST endpoint to record payments received outside of Pelcro (cash, check, wire transfer). Offline charges require:

amount — Payment amount in cents
reference — Your reference number (check number, wire reference, etc.)
currency — Three-letter currency code
customer_id — The customer being charged

Optionally provide invoice_id to link the charge to a specific invoice. Without it, the amount is credited to the customer's balance.

Charge Object

Attribute	Type	Description
`id`	integer	Unique identifier for the charge
`invoice_id`	integer	ID of the invoice this charge is applied to
`amount`	integer	Amount charged in cents
`amount_refunded`	integer	Amount refunded in cents
`description`	string	Description of the charge
`paid`	boolean	Whether the charge has been paid
`refunded`	boolean	Whether the charge has been refunded
`status`	string	Charge status: `succeeded`, `failed`, or `pending`
`statement_descriptor`	string	Text that appears on customer's statement
`offline`	boolean	Whether this is an offline payment
`reference`	string	Reference number for offline payments
`payment_category`	string	Category: `2`=check, `3`=wire, `4`=transfer, `5`=external, `6`=cash
`offline_entered_by`	integer	ID of staff member who entered offline payment
`metadata`	object	Key-value pairs (keys starting with `pelcro` are filtered out)
`created_at`	integer	Unix timestamp of creation
`updated_at`	integer	Unix timestamp of last update
`deleted_at`	integer	Unix timestamp of deletion (if soft-deleted)