List a Customer's PaymentMethods
GET / v1 / customers /:id / payment_methods
Returns a list of PaymentMethods for a given Customer
Parameters
- type enum An optional filter on the list, based on the object
typefield. Without the filter, the list includes all current and future payment method types. If your integration expects only one type of payment method in the response, make sure to provide a type value in the request.
More parameters
- allow _ redisplay enum
- ending _ before string
- limit integer
- starting _ after string
Returns
A dictionary with a data property that contains an array of up to limit PaymentMethods of type type, starting after PaymentMethods starting_after. Each entry in the array is a separate PaymentMethod object. If no more PaymentMethods are available, the resulting array will be empty.
Response
Attach a PaymentMethod to a Customer
POST / v1 / payment_methods /:id / attach
Attaches a PaymentMethod object to a Customer.
To attach a new PaymentMethod to a customer for future payments, we recommend you use a SetupIntent or a PaymentIntent with setup_future_usage. These approaches will perform any necessary steps to set up the PaymentMethod for future payments. Using the /v1/payment_methods/:id/attach endpoint without first using a SetupIntent or PaymentIntent with setup_future_usage does not optimize the PaymentMethod for future use, which makes later declines and payment friction more likely. See Optimizing cards for future payments for more information about setting up future payments.
To use this PaymentMethod as the default for invoice or subscription payments, set invoice_settings.default_payment_method, on the Customer to the PaymentMethod’s ID.
Parameters
- customer string The ID of the customer to which to attach the PaymentMethod.
- customer _ account string The ID of the Account representing the customer to which to attach the PaymentMethod.
Returns
Returns a PaymentMethod object.
Response
{ "id": "pm_1MqM05LkdIwHu7ixlDxxO6Mc", "object": "payment_method", "billing_details": { "address": { "city": null, "country": null, "line1": null, "line2": null, "postal_code": null, "state": null }, "email": null, "name": null, "phone": null }, "card": { "brand": "visa", "checks": { "address_line1_check": null, "address_postal_code_check": null, "cvc_check": "pass" }, "country": "US", "exp_month": 8, "exp_year": 2026, "fingerprint": "mToisGZ01V71BCos", "funding": "credit", "generated_from": null, "last4": "4242", "networks": { "available": [ "visa" ], "preferred": null }, "three_d_secure_usage": { "supported": true }, "wallet": null }, "created": 1679946402, "customer": "cus_NbZ8Ki3f322LNn", "livemode": false, "metadata": {}, "type": "card"}
Detach a PaymentMethod from a Customer
POST / v1 / payment_methods /:id / detach
Detaches a PaymentMethod object from a Customer. Detachment is permanent and irreversible — once detached, a PaymentMethod can no longer be used for payments or re-attached to a Customer.
Parameters
No parameters.
Returns
Returns a PaymentMethod object.
Response
{ "id": "pm_1MqLiJLkdIwHu7ixUEgbFdYF", "object": "payment_method", "billing_details": { "address": { "city": null, "country": null, "line1": null, "line2": null, "postal_code": null, "state": null }, "email": null, "name": null, "phone": null }, "card": { "brand": "visa", "checks": { "address_line1_check": null, "address_postal_code_check": null, "cvc_check": "unchecked" }, "country": "US", "exp_month": 8, "exp_year": 2026, "fingerprint": "mToisGZ01V71BCos", "funding": "credit", "generated_from": null, "last4": "4242", "networks": { "available": [ "visa" ], "preferred": null }, "three_d_secure_usage": { "supported": true }, "wallet": null }, "created": 1679945299, "customer": null, "livemode": false, "metadata": {}, "type": "card"}