Payment Methods
Overview
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.
Use Cases
- 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
Events
| Event | Description |
|---|---|
source.created | A new payment method was added |
source.updated | A payment method was modified |
source.expiring | A payment method is approaching its expiration date |
source.expired | A payment method has expired |
source.created
Triggered When
- A customer adds a new payment method via the SDK
- A payment method is created via the Core API
Payload
{
"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]"
}
}
}
}source.updated
Triggered When
- A payment method is updated via the Core API
- Card details are updated by the payment gateway (e.g., automatic card updater)
Payload
The payload includes a previous_attributes object containing only the fields that changed.
{
"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
}
}
}
}source.expiring
Triggered When
- A payment method is approaching its expiration date (typically triggered by a scheduled job)
Payload
{
"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]"
}
}
}
}source.expired
Triggered When
- A payment method has passed its expiration date (typically triggered by a scheduled job)
Payload
{
"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]"
}
}
}
}Payload Fields
Source Object
| Field | Type | Description |
|---|---|---|
object | string | Object type identifier, always source |
id | integer | Unique identifier for the payment method |
object_id | string | External gateway identifier (e.g., Stripe payment method ID) |
object_gateway | string | Payment gateway: "stripe", "braintree", "vantiv", "tap", or "cybersource" |
address_line1_check | string | null | Address line 1 verification result (e.g., "pass", "fail", "unavailable") |
address_zip_check | string | null | ZIP/postal code verification result |
brand | string | null | Card brand: "visa", "mastercard", "amex", "discover", etc. |
country | string | null | Two-letter ISO country code of the card issuer |
cvc_check | string | null | CVC verification result (e.g., "pass", "fail", "unavailable") |
dynamic_last4 | string | null | Last 4 digits of the device account number (for tokenized cards) |
exp_month | integer | null | Card expiration month (1-12) |
exp_year | integer | null | Card expiration year (4-digit) |
funding | string | null | Card funding type: "credit", "debit", or "prepaid" |
last4 | string | null | Last 4 digits of the card number |
name | string | null | Cardholder name |
three_d_secure | string | null | 3D Secure status |
tokenization_method | string | null | Tokenization method (e.g., "apple_pay", "google_pay") |
site_ids | array | Array of site IDs the customer belongs to |
customer | object | Simplified customer object (see below) |
Customer Object (Nested)
| Field | Type | Description |
|---|---|---|
id | integer | Customer ID |
name | string | null | Customer full name |
email | string | Customer email address |
Previous Attributes (updated events only)
| Field | Type | Description |
|---|---|---|
previous_attributes | object | 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). |
Notes
- The payload only includes a whitelisted subset of card properties. Sensitive fields like
fingerprint,iin, andissuerare excluded. - The
customerobject in source webhooks is a simplified version containing onlyid,name, andemail— not the full customer object used in other webhooks. - For
source.updated, theprevious_attributesnests changed values under apropertieskey, reflecting the internal storage structure. source.expiringis typically fired before the card's expiration month, giving you time to prompt the customer to update their payment method.
Related
- Webhooks Overview - Setup, signatures, and configuration
- Customer Webhooks - Customer events that may include payment method details
- Charge Webhooks - Charge events that reference payment methods
Updated 5 months ago
Did this page help you?