--- updatedAt: 2026-02-24T20:12:49.000Z agentTools: projectIndex: https://docs.pelcro.com/llms.txt --- # 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`](#sourcecreated) | A new payment method was added | | [`source.updated`](#sourceupdated) | A payment method was modified | | [`source.expiring`](#sourceexpiring) | A payment method is approaching its expiration date | | [`source.expired`](#sourceexpired) | 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 ```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": "customer@example.com" } } } } ``` *** ## 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. ```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": "customer@example.com" } }, "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 ```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": "customer@example.com" } } } } ``` *** ## source.expired ### Triggered When * A payment method has passed its expiration date (typically triggered by a scheduled job) ### Payload ```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": "customer@example.com" } } } } ``` *** ## 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`, 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. *** ## Related * [Webhooks Overview](webhooks) - Setup, signatures, and configuration * [Customer Webhooks](https://docs.pelcro.com/docs/webhooks-customers) - Customer events that may include payment method details * [Charge Webhooks](https://docs.pelcro.com/docs/webhooks-charges) - Charge events that reference payment methods # Sibling pages * [Email Templates](https://docs.pelcro.com/docs/e-mail-templates-for-webhooks.md) * [Addresses](https://docs.pelcro.com/docs/webhooks-addresses.md) * [Bills](https://docs.pelcro.com/docs/webhooks-bills.md) * [Campaigns](https://docs.pelcro.com/docs/webhooks-campaigns.md) * [Charges](https://docs.pelcro.com/docs/webhooks-charges.md) * [Customers](https://docs.pelcro.com/docs/webhooks-customers.md) * [Exports](https://docs.pelcro.com/docs/webhooks-exports.md) * [Fraud Prevention](https://docs.pelcro.com/docs/webhooks-fraud-prevention.md) * [Invoices](https://docs.pelcro.com/docs/webhooks-invoices.md) * [Members](https://docs.pelcro.com/docs/webhooks-members.md) * [Newsletters](https://docs.pelcro.com/docs/webhooks-newsletters.md) * [Orders](https://docs.pelcro.com/docs/webhooks-orders.md) * [Plans](https://docs.pelcro.com/docs/webhooks-plans.md) * [Products](https://docs.pelcro.com/docs/webhooks-products.md) * [Subscriptions](https://docs.pelcro.com/docs/webhooks-subscriptions.md) * [Vendors](https://docs.pelcro.com/docs/webhooks-vendors.md)