{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-rest-api/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Stored Payment Methods","description":"Developer documentation for the WHMCS API — the","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"stored-payment-methods","__idx":0},"children":["Stored Payment Methods"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A stored payment method is a credit or debit card, bank account, or wallet that the client has saved for reuse. WHMCS calls these pay methods in the Admin Area and the Client Area, and the API route is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/user/paymethods"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The gateway stores the card number or account details. These endpoints return an identifier that you pass to other endpoints, not a value that you can charge directly."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These endpoints apply to any integration that collects payment, headless or not. For more information, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.whmcs.com/payments/pay-methods","target":"_blank"},"children":["Pay Methods"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"listing-a-clients-methods","__idx":1},"children":["Listing a Client's Methods"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Read the client's stored payment methods from ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/rest-api/reference/whmcs-rest-api/paths/~1user~1paymethods/get"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /user/paymethods"]}]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"using-javascript","__idx":2},"children":["Using JavaScript"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"const { data: methods } = await api('/user/paymethods');\n","lang":"js"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"using-curl","__idx":3},"children":["Using cURL"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"curl -X GET --location \"https://example.com/api/v2/user/paymethods\"\n  -H \"X-Api-State: <your latest state token>\"\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The list paginates on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page_size"]}," values, and the client's default method comes first. An empty array indicates that the client has stored no payment methods."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Pass the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," value as the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment.paymethod_id"]}," value at checkout."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["gateway_is_active"]}," value indicates whether the gateway behind the method is still usable."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api()"]}," wrapper above is the one that ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/rest-api/headless-stripe-payments"},"children":["Headless Stripe Payments"]}," defines. For more information about the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Api-State"]}," header that these endpoints require, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/rest-api/authentication"},"children":["Authentication"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"reading-and-removing-a-method","__idx":4},"children":["Reading and Removing a Method"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/rest-api/reference/whmcs-rest-api/paths/~1user~1paymethods~1%7Bpaymethod_id%7D/get"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /user/paymethods/{paymethod_id}"]}]}," returns one method. ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/rest-api/reference/whmcs-rest-api/paths/~1user~1paymethods~1%7Bpaymethod_id%7D/delete"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /user/paymethods/{paymethod_id}"]}]}," removes one."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following failure responses require different handling:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}," response indicates a merchant setting. It recurs until the merchant enables ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Allow Client Pay Method Removal"]}," in the WHMCS Admin Area, on the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.whmcs.com/system/general-settings/general-settings-security","target":"_blank"},"children":["Security"]}]}," tab at ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Configuration > System Settings > ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.whmcs.com/system/general-settings","target":"_blank"},"children":["General Settings"]}]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]}," response indicates a passing condition, so a later retry can succeed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}," response indicates that the request exceeded the rate limit, so WHMCS did not remove the payment method."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/rest-api/rate-limits"},"children":["Rate Limits"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"declines-at-checkout","__idx":5},"children":["Declines at Checkout"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Naming a stored payment method at checkout does not guarantee a charge. If the gateway declines the stored payment method, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment.status"]}," value is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]}," and the API does not return an error response."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A headless checkout then returns a new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_session"]}," value. Use that value to collect a different payment method."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/rest-api/headless-stripe-payments"},"children":["Headless Stripe Payments"]},"."]}]}]},"headings":[{"value":"Stored Payment Methods","id":"stored-payment-methods","depth":2},{"value":"Listing a Client's Methods","id":"listing-a-clients-methods","depth":2},{"value":"Using JavaScript","id":"using-javascript","depth":5},{"value":"Using cURL","id":"using-curl","depth":5},{"value":"Reading and Removing a Method","id":"reading-and-removing-a-method","depth":2},{"value":"Declines at Checkout","id":"declines-at-checkout","depth":2}],"frontmatter":{"title":"Stored Payment Methods","seo":{"title":"Stored Payment Methods"}},"lastModified":"2026-10-19T18:21:39.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/rest-api/stored-payment-methods","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}