--- updatedAt: 2026-01-08T20:31:45.000Z agentTools: projectIndex: https://docs.pelcro.com/v2.4/llms.txt --- # Charges Receive notifications when charges succeed, fail, or are refunded. ## Overview Charge webhooks notify your application when payment transactions occur. Use these events to track successful payments, handle failed charges, and process refunds. *** ## Use Cases * Update order status when payment succeeds * Trigger dunning workflows when charges fail * Sync payment data to your accounting system * Send payment confirmation emails * Track refund requests and completions * Monitor payment failure rates *** ## Events | Event | Description | | -------------------------------------- | ------------------------------------------ | | [`charge.succeeded`](#chargesucceeded) | A charge was successfully processed | | [`charge.failed`](#chargefailed) | A charge attempt failed | | [`charge.refunded`](#chargerefunded) | A charge was refunded (fully or partially) | *** ## charge.succeeded ### Triggered When * A customer's payment method is successfully charged * A subscription payment is processed * An invoice is paid * A one-time purchase is completed ### Payload ```json { "type": "charge.succeeded", "id": "evt_a1b2C3d4E5f6g7H8i9J0k1L2", "created": 1704067200, "data": { "charge": { "object": "charge", "id": 12345, "amount": 10000, "amount_refunded": 0, "by_agency": false, "created": "2024-01-01T00:00:00.000000Z", "created_at": "2024-01-01T00:00:00.000000Z", "currency": "usd", "customer": { "object": "customer", "id": 67890, "email": "customer@example.com", "first_name": "John", "last_name": "Doe" }, "description": "Subscription payment", "disputed": false, "failure_code": null, "failure_message": null, "invoice": { "object": "invoice", "id": 11111 }, "invoice_id": 11111, "object_id": "ch_1234567890abcdef", "offline": false, "origin": 1, "paid": true, "receipt_email": "customer@example.com", "receipt_number": "1234-5678", "receipt_url": "https://pay.stripe.com/receipts/...", "reference": "REF-001", "refunded": false, "refunded_at": null, "remit_rate": null, "remit_rate_amount": null, "site_id": 1, "source_id": 99999, "statement_descriptor": "ACME INC", "status": "succeeded", "updated_at": "2024-01-01T00:00:00.000000Z", "user_id": 67890 } } } ``` *** ## charge.failed ### Triggered When * A customer's payment method is declined * Insufficient funds on the payment method * Card expired or invalid * Payment gateway error occurs ### Payload ```json { "type": "charge.failed", "id": "evt_b2C3d4E5f6g7H8i9J0k1L2m3", "created": 1704067200, "data": { "charge": { "object": "charge", "id": 12346, "amount": 10000, "amount_refunded": 0, "by_agency": false, "created": "2024-01-01T00:00:00.000000Z", "created_at": "2024-01-01T00:00:00.000000Z", "currency": "usd", "customer": { "object": "customer", "id": 67890, "email": "customer@example.com", "first_name": "John", "last_name": "Doe" }, "description": "Subscription payment", "disputed": false, "failure_code": "card_declined", "failure_message": "Your card was declined.", "invoice": { "object": "invoice", "id": 11112 }, "invoice_id": 11112, "object_id": "ch_failed_1234567890", "offline": false, "origin": 1, "paid": false, "receipt_email": null, "receipt_number": null, "receipt_url": null, "reference": null, "refunded": false, "refunded_at": null, "remit_rate": null, "remit_rate_amount": null, "site_id": 1, "source_id": 99999, "statement_descriptor": null, "status": "failed", "updated_at": "2024-01-01T00:00:00.000000Z", "user_id": 67890 } } } ``` ### Common Failure Codes | Code | Description | | -------------------- | ---------------------------------------- | | `card_declined` | The card was declined by the issuer | | `insufficient_funds` | The card has insufficient funds | | `expired_card` | The card has expired | | `incorrect_cvc` | The CVC code is incorrect | | `processing_error` | An error occurred while processing | | `do_not_honor` | The card issuer declined the transaction | *** ## charge.refunded ### Triggered When * A full refund is issued for a charge * A partial refund is issued for a charge * A subscription is canceled with proration ### Payload ```json { "type": "charge.refunded", "id": "evt_c3D4e5F6g7H8i9J0k1L2m3N4", "created": 1704153600, "data": { "charge": { "object": "charge", "id": 12345, "amount": 10000, "amount_refunded": 10000, "by_agency": false, "created": "2024-01-01T00:00:00.000000Z", "created_at": "2024-01-01T00:00:00.000000Z", "currency": "usd", "customer": { "object": "customer", "id": 67890, "email": "customer@example.com", "first_name": "John", "last_name": "Doe" }, "description": "Subscription payment", "disputed": false, "failure_code": null, "failure_message": null, "invoice": { "object": "invoice", "id": 11111 }, "invoice_id": 11111, "object_id": "ch_1234567890abcdef", "offline": false, "origin": 1, "paid": true, "receipt_email": "customer@example.com", "receipt_number": "1234-5678", "receipt_url": "https://pay.stripe.com/receipts/...", "reference": "REF-001", "refund": { "object": "refund", "id": 55555, "amount": 10000, "currency": "usd", "reason": "requested_by_customer", "status": "succeeded" }, "refunded": true, "refunded_at": "2024-01-02T00:00:00.000000Z", "remit_rate": null, "remit_rate_amount": null, "site_id": 1, "source_id": 99999, "statement_descriptor": "ACME INC", "status": "refunded", "updated_at": "2024-01-02T00:00:00.000000Z", "user_id": 67890 } } } ``` *** ## Payload Fields ### Charge Object | Field | Type | Description | | ---------------------- | ------- | ------------------------------------------------------- | | `object` | string | Object type identifier, always `charge` | | `id` | integer | Unique identifier for the charge | | `amount` | integer | Charge amount in cents | | `amount_refunded` | integer | Total refunded amount in cents | | `by_agency` | boolean | Whether charged through an agency | | `created` | string | ISO 8601 timestamp when charge was initiated | | `created_at` | string | ISO 8601 timestamp when record was created | | `currency` | string | Three-letter ISO currency code (lowercase) | | `customer` | object | Customer details (see Customer Object) | | `description` | string | Description of the charge | | `disputed` | boolean | Whether the charge is disputed | | `failure_code` | string | Error code if charge failed | | `failure_message` | string | Human-readable failure description | | `invoice` | object | Associated invoice (see Invoice Object) | | `invoice_id` | integer | Associated invoice ID | | `object_id` | string | External payment gateway identifier | | `offline` | boolean | Whether this was an offline payment | | `origin` | integer | Payment origin: `1` (Stripe), `4` (Offline), etc. | | `paid` | boolean | Whether the charge succeeded | | `receipt_email` | string | Email address for receipt | | `receipt_number` | string | Receipt reference number | | `receipt_url` | string | URL to view payment receipt | | `reference` | string | Custom reference identifier | | `refund` | object | Refund details when charge.refunded (see Refund Object) | | `refunded` | boolean | Whether the charge has been refunded | | `refunded_at` | string | ISO 8601 timestamp when refunded | | `remit_rate` | float | Remittance rate percentage | | `remit_rate_amount` | integer | Remittance amount in cents | | `site_id` | integer | Associated site ID | | `source_id` | integer | Payment source ID | | `statement_descriptor` | string | Text appearing on customer's statement | | `status` | string | Charge status (see Status Values) | | `updated_at` | string | ISO 8601 timestamp when last modified | | `user_id` | integer | Customer user ID | ### Status Values | Status | Description | | ------------------------ | ----------------------------- | | `succeeded` | Charge completed successfully | | `failed` | Charge attempt failed | | `pending` | Charge is being processed | | `refunded` | Charge was fully refunded | | `partially refunded` | Charge was partially refunded | | `credited` | Amount was credited back | | `partially credited` | Amount was partially credited | | `pending offline refund` | Offline refund is pending | ### Customer Object (Nested) | Field | Type | Description | | ------------ | ------- | ------------------- | | `object` | string | Always `customer` | | `id` | integer | Customer ID | | `email` | string | Customer email | | `first_name` | string | Customer first name | | `last_name` | string | Customer last name | ### Invoice Object (Nested) | Field | Type | Description | | -------- | ------- | ---------------- | | `object` | string | Always `invoice` | | `id` | integer | Invoice ID | ### Refund Object (Nested, charge.refunded only) | Field | Type | Description | | ---------- | ------- | ---------------------- | | `object` | string | Always `refund` | | `id` | integer | Refund ID | | `amount` | integer | Refund amount in cents | | `currency` | string | Currency code | | `reason` | string | Refund reason | | `status` | string | Refund status | *** ## Related * [Webhooks Overview](webhooks) - Setup, signatures, and configuration # Sibling pages * [Email Templates](https://docs.pelcro.com/v2.4/docs/e-mail-templates-for-webhooks.md) * [Addresses](https://docs.pelcro.com/v2.4/docs/webhooks-addresses.md) * [Bills](https://docs.pelcro.com/v2.4/docs/webhooks-bills.md) * [Campaigns](https://docs.pelcro.com/v2.4/docs/webhooks-campaigns.md) * [Customers](https://docs.pelcro.com/v2.4/docs/webhooks-customers.md) * [Exports](https://docs.pelcro.com/v2.4/docs/webhooks-exports.md) * [Fraud Prevention](https://docs.pelcro.com/v2.4/docs/webhooks-fraud-prevention.md) * [Invoices](https://docs.pelcro.com/v2.4/docs/webhooks-invoices.md) * [Members](https://docs.pelcro.com/v2.4/docs/webhooks-members.md) * [Newsletters](https://docs.pelcro.com/v2.4/docs/webhooks-newsletters.md) * [Orders](https://docs.pelcro.com/v2.4/docs/webhooks-orders.md) * [Payment Methods](https://docs.pelcro.com/v2.4/docs/webhooks-payment-methods.md) * [Plans](https://docs.pelcro.com/v2.4/docs/webhooks-plans.md) * [Products](https://docs.pelcro.com/v2.4/docs/webhooks-products.md) * [Subscriptions](https://docs.pelcro.com/v2.4/docs/webhooks-subscriptions.md) * [Vendors](https://docs.pelcro.com/v2.4/docs/webhooks-vendors.md)