Update Payment Method Error Codes

This document provides a comprehensive reference for validation errors related to payment method update operations in the Convenient Checkout API. These errors help identify issues with payment method update requests and guide you in resolving them.

tip

• For Payment Method object validation errors, see the Payment Object Error Codes Reference.
• For Agent Method object validation errors, see the Agent Object Error Codes Reference.

Error Codes Summary

Error Code Summary

Error Title Reference	Error & Status	Detail Message	Scenario	Resolution
Agent Validation	INVALID_REQUEST 400 BAD REQUEST	Agent is required to update manufacturer card	Agent object is missing when updating manufacturer card	Include a valid agent object when updating a manufacturer card
Manufacturer Card Validation	INVALID_REQUEST 400 BAD REQUEST	Manufacturer card cannot be default	Both manufacturerCard and default are set to true	Set either manufacturerCard=false or default=false; a manufacturer card cannot be the default payment method
Payment Method Type Validation	INVALID_REQUEST 400 BAD REQUEST	Payment method type in request does not match the existing payment method	Type mismatch between request and existing payment method	Ensure the payment method type in the request matches the existing payment method type
Payment Method Status Validation	FORBIDDEN 403 FORBIDDEN	Cannot update invalid payment method	Attempt to update a payment method with INVALIDATED status	Only update payment methods that are in a valid (non-invalidated) status
Payment Method ID Validation	INVALID_REQUEST 400 BAD REQUEST	Invalid paymentMethodId	Payment method ID does not exist or has invalid format	Provide a valid, existing paymentMethodId
Field Validation	PAYMENT_METHOD_ERROR 400 BAD REQUEST	Account type must not be blank.	Missing required account type field	Include a valid account type in the request
	PAYMENT_METHOD_ERROR 400 BAD REQUEST	ZipCode must be exactly 5 digits long.	Invalid zip code format	Provide a valid 5-digit zip code
Expiry Date Validation	PAYMENT_METHOD_ERROR 400 BAD REQUEST	invalid expiryMonth	Expiry month is invalid (zero, negative, or greater than 12)	Provide a valid expiry month (1-12)
	PAYMENT_METHOD_ERROR 400 BAD REQUEST	expiry month and year cannot be in the past	Expired date provided	Provide a valid expiry date that is not in the past
	PAYMENT_METHOD_ERROR 400 BAD REQUEST	expiryYear cannot be more than 50 years from current year	Expiry year too far in future	Provide an expiry year that is within 50 years from the current year
	PAYMENT_METHOD_ERROR 400 BAD REQUEST	expiryMonth is required when expiryYear is present	Incomplete expiry date	Provide both expiry month and year
	PAYMENT_METHOD_ERROR 400 BAD REQUEST	expiryYear is required when expiryMonth is present	Incomplete expiry date	Provide both expiry month and year

---

Error Codes Details

Agent Validation

Agent is required to update manufacturer card

The Update Payment Method API requires an agent object to update the manufacturerCard flag for any card payment method. If the agent is missing or null, the request will fail.

Sample Invalid Request:

{
    "agent": null
}

Sample Error Response:

{
    "title": "INVALID_REQUEST",
    "status": 400,
    "detail": "Agent is required to update manufacturer card"
}

Manufacturer Card Validation

Manufacturer card cannot be default

A manufacturer card cannot be designated as the default option, as manufacturer and default cards are mutually exclusive. If both manufacturerCard and default are set to true, the request will fail.

Sample Invalid Request:

{
    "default": true,
    "manufacturerCard" : true
}

Sample Error Response:

{
    "title": "INVALID_REQUEST",
    "status": 400,
    "detail": "Manufacturer card cannot be default"
}

Payment Method Type Validation

Payment method type mismatch

The payment method type in the update request must match the existing payment method type. For example, you cannot update a card payment method with bank account details or vice versa.

Sample Invalid Request:

{
    "paymentMethodDetails": {
        "type": "BANK_ACCOUNT",
        "nameOnAccount": "John Doe",
        "accountType": "checking"
    }
}

Sample Error Response:

{
    "title": "INVALID_REQUEST",
    "status": 400,
    "detail": "Payment method type in request does not match the existing payment method"
}

Payment Method Status Validation

Cannot update invalid payment method

Payment methods with an INVALIDATED status cannot be updated. This could happen if the payment method was previously invalidated by the system or an administrator.

Sample Error Response:

{
    "title": "INVALID_REQUEST",
    "status": 403,
    "detail": "Cannot update invalid payment method"
}

Payment Method ID Validation

Invalid payment method ID

The payment method ID provided in the request must exist in the system and be associated with the customer. If an invalid, non-existent, or improperly formatted ID is provided, this error occurs.

Sample Error Response:

{
    "title": "INVALID_REQUEST",
    "status": 400,
    "detail": "Invalid paymentMethodId"
}

Field Validation

Account type must not be blank

When updating a bank account payment method, the account type field is required and must have a value.

Sample Invalid Request:

{
    "paymentMethodDetails": {
        "type": "BANK_ACCOUNT",
        "nameOnAccount": "John Doe",
        "accountType": ""
    }
}

Sample Error Response:

{
    "title": "PAYMENT_METHOD_ERROR",
    "status": 400,
    "detail": "Account type must not be blank."
}

Invalid ZIP code format

When updating a card payment method, the ZIP code must be exactly 5 digits long.

Sample Invalid Request:

{
    "paymentMethodDetails": {
        "type": "CARD",
        "nameOnCard": "John Doe",
        "zipCode": "123"
    }
}

Sample Error Response:

{
    "title": "PAYMENT_METHOD_ERROR",
    "status": 400,
    "detail": "ZipCode must be exactly 5 digits long."
}

Expiry Date Validation

Invalid expiry month

The expiry month must be a number between 1 and 12.

Sample Invalid Request:

{
    "paymentMethodDetails": {
        "type": "CARD",
        "nameOnCard": "John Doe", 
        "expiryMonth": 13,
        "expiryYear": 2030
    }
}

Sample Error Response:

{
    "title": "PAYMENT_METHOD_ERROR",
    "status": 400,
    "detail": "invalid expiryMonth"
}

Expired card date

The expiry date (month and year) cannot be in the past.

Sample Invalid Request:

{
    "paymentMethodDetails": {
        "type": "CARD",
        "nameOnCard": "John Doe", 
        "expiryMonth": 6,
        "expiryYear": 2024
    }
}

Sample Error Response:

{
    "title": "PAYMENT_METHOD_ERROR",
    "status": 400,
    "detail": "expiry month and year cannot be in the past"
}

Expiry year too far in future

The expiry year cannot be more than 50 years from the current year.

Sample Invalid Request:

{
    "paymentMethodDetails": {
        "type": "CARD",
        "nameOnCard": "John Doe", 
        "expiryMonth": 6,
        "expiryYear": 2080
    }
}

Sample Error Response:

{
    "title": "PAYMENT_METHOD_ERROR", 
    "status": 400,
    "detail": "expiryYear cannot be more than 50 years from current year"
}

Missing expiry month with expiry year

When providing an expiry year, the expiry month is also required.

Sample Invalid Request:

{
    "paymentMethodDetails": {
        "type": "CARD",
        "nameOnCard": "John Doe",
        "expiryYear": 2030
    }
}

Sample Error Response:

{
    "title": "PAYMENT_METHOD_ERROR",
    "status": 400,
    "detail": "expiryMonth is required when expiryYear is present"
}

Missing expiry year with expiry month

When providing an expiry month, the expiry year is also required.

Sample Invalid Request:

{
    "paymentMethodDetails": {
        "type": "CARD",
        "nameOnCard": "John Doe", 
        "expiryMonth": 6
    }
}

Sample Error Response:

{
    "title": "PAYMENT_METHOD_ERROR",
    "status": 400,
    "detail": "expiryYear is required when expiryMonth is present"
}