Customer Payment Method Errors
The following error codes and messages appear in REST responses when an error prevents completion of the request.
Error Code | Description |
|---|---|
CREATE_CARD_TYPE_REQUIRES_ONLY_ONE_OF_FIELDS_OR_TOKEN | Message: The request tried to add a payment method to a customer, but both the Explanation: You provided both a payment method type and a payment token in the same request, or you omitted both. You must provide only one of these fields to identify the payment method. Error Example: Correct Example: post /v1/customers/cus_4e25112ac20e144ad073a614dc46934b/payment_methods
{
"type": "ug_visa_card",
"fields": {
"number": "4111111111111111",
"expiration_month": "12",
"expiration_year": "2026",
"cvv": "123",
"name": "John Doe"
}
} |
ERROR_CREATE_PAYMENT_METHOD | Message: The request attempted an operation that requires specific fields for payment method, but a required field was missing, or an extra, unallowed field was included. Corrective action: Run Get Payment Method Required Fields and check all input fields. Explanation: The payment method object contains invalid fields or is missing mandatory parameters for the specified type. Verify the required fields for the specific payment method type and try again. Correct Example: post /v1/customers/cus_4e25112ac20e144ad073a614dc46934b/payment_methods
{
"type": "ug_visa_card",
"fields": {
"number": "4111111111111111",
"expiration_month": "12",
"expiration_year": "2025",
"cvv": "123",
"name": "John Doe"
}
} |
ERROR_CUSTOMER_PAYMENT_METHOD_NOT_FOUND | Message: The request attempted an operation that requires the default payment method of a customer, but the customer does not have a default payment method. The request was rejected. Corrective action: Use Update Customer to select a default payment method, or use Add Payment Method to Customer. Explanation: You tried to process a payment using the customer's stored credentials, but no default payment method is assigned to that customer. Add a payment method to the customer profile and set it as the default. See |
ERROR_DELETE_DEFAULT_PAYMENT_METHOD_IN_USE | Message: The request tried to delete a customer's default payment method, but the payment method was in use. The request was rejected. Corrective action: Use List Subscriptions, filtered by the customer's ID, then use Cancel Subscription to remove all subscriptions that use the customer's ID or the payment method that you want to delete. Explanation: The default payment method cannot be deleted because it is currently linked to one or more active subscriptions. Before attempting to delete the payment method, do the following to each subscription: ssign a new payment method using Update Subscription, or alternatively, delete the subscription using Cancel Subscription. You must also use Update Customer to assign a new default payment method. |
ERROR_DELETE_PAYMENT_METHOD_FROM_WRONG_CUSTOMER | Message: The request tried to delete a payment method from a customer, but the payment method was not assigned to the customer that was specified in the request. The request was rejected. Corrective action: Indicate a payment method that is on the current list of payment methods for the designated customer. Explanation: The payment method ID provided does not belong to the customer ID specified in the URL path. Use List Payment Methods of Customer to verify that the payment method is correctly associated with the customer before sending the delete payment request. |
ERROR_DELETE_PAYMENT_METHOD_IN_USE | Message: The request tried to delete a customer's payment method, but the payment method was in use. The request was rejected. Corrective action: Use List Subscriptions, filtered by the customer's ID, then use Cancel Subscription to remove all subscriptions that use the customer's ID or the payment method that you want to delete. Explanation: The payment method cannot be deleted because it is currently linked to one or more active subscriptions. Before attempting to delete the payment method, do the following to each subscription: Assign a new payment method using Update Subscription, or alternatively, delete the subscription using Cancel Subscription. |
ERROR_GET_CUSTOMER_DEFAULT_PAYMENT_METHOD | Message: The request attempted an operation that requires a customer's default payment method, but the default payment method was not found. The request was rejected. Corrective action: Use Update Customer to set the default payment method. Explanation: The system could not retrieve a default payment method for the specified customer. Assign a payment method to the customer or set an existing one as the default. |
ERROR_GET_PAYMENT_METHOD_TYPE | Message: The request attempted an operation that requires a payment method, but the payment method type was not recognized or is not available for this merchant. Corrective action: For the Explanation: The payment method type specified is either misspelled or not enabled for your merchant account. Ensure that the type is correct and that you have the necessary permissions to use it. |
PAYMENT_METHOD_FIELD_NOT_UPDATABLE | Message: The request tried to update a payment method of a customer, but it tried to set a new value for a field that does not exist or is not modifiable. The request was rejected. Corrective action: Do not change the value of the field named at the end of the error code. Explanation: You attempted to modify a field that is immutable once the payment method is created, such as the payment method type. Only update fields that are explicitly marked as modifiable in the API Reference. |
PAYMENT_METHOD_REQUIRES_ONLY_ONE_OF_TYPE_OR_TOKEN | Message: The request tried to add a payment method to a customer, but both the Explanation: The request requires either a payment method type for a new card or a token for a saved one, but not both at once. Select one identification method and remove the other one from your request. |