Payment method webhooks notify your application when a customer's payment method (source) is created, updated, approaching expiration, or has expired. Use these events to prompt customers to update their payment details and prevent failed charges.
Alert customers when their card is about to expire
Update your records when a customer adds or changes a payment method
Trigger dunning flows when a payment method expires
Sync payment method details to external billing systems
A customer adds a new payment method via the SDK
A payment method is created via the Core API
JSON
{
"type": "source.created",
"id": "evt_a1B2c3D4e5F6g7H8i9J0k1L2",
"created": 1704067200,
"data": {
"object": {
"object": "source",
"id": 100001,
"object_id": "pm_XXXXXXXXXXXXXXXXXXXX",
"object_gateway": "stripe",
"address_line1_check": null,
"address_zip_check": null,
"brand": "visa",
"country": "US",
"cvc_check": "pass",
"dynamic_last4": null,
"exp_month": 12,
"exp_year": 2028,
"funding": "credit",
"last4": "4242",
"name": null,
"three_d_secure": null,
"tokenization_method": null,
"site_ids": [1],
"customer": {
"id": 200001,
"name": "Jane Doe",
"email": "[email protected] "
}
}
}
}
A payment method is updated via the Core API
Card details are updated by the payment gateway (e.g., automatic card updater)
The payload includes a previous_attributes object containing only the fields that changed.
JSON
{
"type": "source.updated",
"id": "evt_b2C3d4E5f6G7h8I9j0K1l2M3",
"created": 1704153600,
"data": {
"object": {
"object": "source",
"id": 100001,
"object_id": "pm_XXXXXXXXXXXXXXXXXXXX",
"object_gateway": "stripe",
"address_line1_check": null,
"address_zip_check": null,
"brand": "visa",
"country": "US",
"cvc_check": "pass",
"dynamic_last4": null,
"exp_month": 6,
"exp_year": 2029,
"funding": "credit",
"last4": "4242",
"name": null,
"three_d_secure": null,
"tokenization_method": null,
"site_ids": [1],
"customer": {
"id": 200001,
"name": "Jane Doe",
"email": "[email protected] "
}
},
"previous_attributes": {
"properties": {
"exp_month": 12,
"exp_year": 2028
}
}
}
}
A payment method is approaching its expiration date (typically triggered by a scheduled job)
JSON
{
"type": "source.expiring",
"id": "evt_d4E5f6G7h8I9j0K1l2M3n4O5",
"created": 1704326400,
"data": {
"object": {
"object": "source",
"id": 100001,
"object_id": "pm_XXXXXXXXXXXXXXXXXXXX",
"object_gateway": "stripe",
"address_line1_check": null,
"address_zip_check": null,
"brand": "visa",
"country": "US",
"cvc_check": "pass",
"dynamic_last4": null,
"exp_month": 1,
"exp_year": 2026,
"funding": "credit",
"last4": "4242",
"name": null,
"three_d_secure": null,
"tokenization_method": null,
"site_ids": [1],
"customer": {
"id": 200001,
"name": "Jane Doe",
"email": "[email protected] "
}
}
}
}
A payment method has passed its expiration date (typically triggered by a scheduled job)
JSON
{
"type": "source.expired",
"id": "evt_e5F6g7H8i9J0k1L2m3N4o5P6",
"created": 1704412800,
"data": {
"object": {
"object": "source",
"id": 100001,
"object_id": "pm_XXXXXXXXXXXXXXXXXXXX",
"object_gateway": "stripe",
"address_line1_check": null,
"address_zip_check": null,
"brand": "visa",
"country": "US",
"cvc_check": "pass",
"dynamic_last4": null,
"exp_month": 12,
"exp_year": 2025,
"funding": "credit",
"last4": "4242",
"name": null,
"three_d_secure": null,
"tokenization_method": null,
"site_ids": [1],
"customer": {
"id": 200001,
"name": "Jane Doe",
"email": "[email protected] "
}
}
}
}Field Type Description objectstring Object type identifier, always source idinteger Unique identifier for the payment method object_idstring External gateway identifier (e.g., Stripe payment method ID) object_gatewaystring Payment gateway: "stripe", "braintree", "vantiv", "tap", or "cybersource" address_line1_checkstring | null Address line 1 verification result (e.g., "pass", "fail", "unavailable") address_zip_checkstring | null ZIP/postal code verification result brandstring | null Card brand: "visa", "mastercard", "amex", "discover", etc. countrystring | null Two-letter ISO country code of the card issuer cvc_checkstring | null CVC verification result (e.g., "pass", "fail", "unavailable") dynamic_last4string | null Last 4 digits of the device account number (for tokenized cards) exp_monthinteger | null Card expiration month (1-12) exp_yearinteger | null Card expiration year (4-digit) fundingstring | null Card funding type: "credit", "debit", or "prepaid" last4string | null Last 4 digits of the card number namestring | null Cardholder name three_d_securestring | null 3D Secure status tokenization_methodstring | null Tokenization method (e.g., "apple_pay", "google_pay") site_idsarray Array of site IDs the customer belongs to customerobject Simplified customer object (see below)
Field Type Description idinteger Customer ID namestring | null Customer full name emailstring Customer email address
Field Type Description previous_attributesobject Contains only the fields that changed, with their previous values. For source updates, changes are nested under properties (e.g., previous_attributes.properties.exp_month).
The payload only includes a whitelisted subset of card properties. Sensitive fields like fingerprint, iin, and issuer are excluded.
The customer object in source webhooks is a simplified version containing only id, name, and email — not the full customer object used in other webhooks.
For source.updated, the previous_attributes nests changed values under a properties key, reflecting the internal storage structure.
source.expiring is typically fired before the card's expiration month, giving you time to prompt the customer to update their payment method.
