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.
- Provides integration with the Account Updater feature, which keeps payment methods updated automatically based on card brand updates.
Usage Notes
Filtering
- Use the
statusparameter to filter payment methods byactiveordeletedstatus. - To retrieve soft-deleted payment methods updated by the Account Updater, set
status=deleted.
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.
- 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.
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. Only re-enable a payment method if 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: Payment methods updated via the Account Updater feature may include additional metadata, such as:
- Updated Reason: Explains why the update occurred (e.g., expiration date changed).
- Updated By: Indicates that the update was triggered by the Account Updater.
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.
Compliance: Ensure your application complies with PCI DSS standards when handling or displaying payment method information.