Charges
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 5 months ago