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 /user/paymethods.

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.

Read the client's stored payment methods from GET /user/paymethods.

For example:

const { data: methods } = await api('/user/paymethods');

curl -X GET --location "https://example.com/api/v2/user/paymethods"
  -H "X-Api-State: <your latest state token>"

The list paginates on the page and page_size values, and the client's default method comes first. An empty array indicates that the client has stored no payment methods.

• Pass the id value as the payment.paymethod_id value at checkout.
• The gateway_is_active value indicates whether the gateway behind the method is still usable.

GET /user/paymethods/{paymethod_id} returns one method. DELETE /user/paymethods/{paymethod_id} removes one.

The following failure responses require different handling:

• A 422 response indicates a merchant setting. It recurs until the merchant enables Allow Client Pay Method Removal in the WHMCS Admin Area, on the Security tab at Configuration > System Settings > General Settings.
• A 409 response indicates a passing condition, so a later retry can succeed.
• A 429 response indicates that the request exceeded the rate limit, so WHMCS did not remove the payment method.

Naming a stored payment method at checkout does not guarantee a charge. If the gateway declines the stored payment method, the payment.status value is failed and the API does not return an error response.

A headless checkout then returns a new payment_session value. Use that value to collect a different payment method.