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 | A charge was successfully processed |
charge.failed | A charge attempt failed |
charge.refunded | 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
{
"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": "[email protected]",
"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": "[email protected]",
"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
{
"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": "[email protected]",
"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
{
"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": "[email protected]",
"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": "[email protected]",
"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 - Setup, signatures, and configuration
Updated about 23 hours ago