Retrieves a paginated data array of all non-deleted payment methods associated with a merchant by default.
Retrieve all payment methods associated with a merchant account. This includes active and inactive payment methods and provides merchants the ability to manage their stored payment methods effectively.
This endpoint supports filtering, sorting, and pagination for efficient data handling. It also includes integration with the Account Updater feature for merchants who have this capability enabled.
Key Features
Retrieves all non-deleted payment methods associated with the merchant account
Supports filtering by status, type, and creation date for precise data retrieval
Automatic payment method updates based on card brand notifications
Usage Guide
Filtering Options
Status Filtering
- Use the
statusparameter to filter payment methods byactiveordeletedstatus - To retrieve soft-deleted payment methods updated by the Account Updater, set
status=deleted
Additional Filters
- Filter by payment method type
- Filter by creation date range
- Combine multiple filters for precise results
Account Updater Events
If Account Updater is enabled on the merchant's account, the following events can trigger updates to payment methods:
ReplacePaymentMethod
Occurs when a payment method's number and/or expiration date is updated by the card issuer.
ContactCardHolder
Indicates the account needs to be updated, but the issuer didn't provide updated values.
ClosePaymentMethod
Marks a payment method as inactive and soft-deletes it when the card is no longer valid.
Re-enabling Closed Payment Methods
Payment methods closed by Account Updater's ClosePaymentMethod event can be re-enabled by setting the deleted_at property to null.
Important: Only re-enable a payment method if you have verified it is still valid and should not have been deleted.
Response Structure
| Code | Response | Reason |
|---|---|---|
| 200 | Success | Returns a paginated list of payment method objects. |
| 400 | Bad Request | Invalid query parameters. |
| 401 | Unauthorized | Authentication failed. |
| 500 | Internal Server Error | An unexpected error occurred on the server. |
Important Considerations
Account Updater Integration Details
Payment methods updated via the Account Updater feature may include additional metadata:
- Updated Reason: Explains why the update occurred (e.g., expiration date changed)
- Updated By: Indicates that the update was triggered by the Account Updater
- Update Timestamp: Shows when the automatic update was processed
Data Management
Soft-Deleted Methods
Payment methods marked as deleted by ClosePaymentMethod are not permanently erased and can be retrieved by filtering with status=deleted.
Default Sorting
Payment methods are ordered by created_at in descending order (newest first) unless specified otherwise.
Pagination
Large result sets are automatically paginated for optimal performance.
Security & Compliance
PCI DSS Compliance
Ensure your application complies with PCI DSS standards when handling or displaying payment method information.
Data Protection
Sensitive payment method data is tokenized and encrypted in transit and at rest.
Access Control
Only authenticated merchants can access their own payment method data.