SetUp Payment Method Error Codes

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

tip

• For customer object validation error, see the Customer Object Error Codes Reference.
• For PaymentMethod object validation error, see the Payment Method Object Error Codes Reference.
• For Agent object validation error, see the Agent Object Error Codes Reference.
• For checkout session authorization errors, see the Session Authorization Error Codes Reference.

Error Codes Summary

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Reusing Vendor Payment Method	PAYMENT_METHOD_ERROR	400 BAD REQUEST	VendorPaymentMethodId cannot be reused	Attempting to save a payment method with a vendor payment method ID that's already in use	Use a unique vendor payment method ID that hasn't been used before
Manufacturer Card Validation	PAYMENT_METHOD_ERROR	400 BAD REQUEST	Manufacturer card cannot be default	Attempting to set a manufacturer card as default	Set either manufacturerCard=false or default=false, a manufacturer card cannot be the default payment method
	PAYMENT_METHOD_ERROR	400 BAD REQUEST	Agent is required to add manufacturer card	Missing agent information for manufacturer card (applicable only when using manufacturerCard=true)	Include complete agent information when setting up a manufacturer card
	PAYMENT_METHOD_ERROR	400 BAD REQUEST	Medication is required to add manufacturer card	Missing medication in cardCategories for manufacturer card	Include medication details in the cardCategories object for manufacturer cards
	PAYMENT_METHOD_ERROR	400 BAD REQUEST	Only one medication can be associated per manufacturer card	More than one medication added to cardCategories	Limit medication entries to one per manufacturer card
	PAYMENT_METHOD_ERROR	400 BAD REQUEST	MANUFACTURER_CARD category type is not enabled	If merchant request for Manufacturer card catgories when not configured in merchant settings	Contact support to enable manufacturer card category types for your merchant account
Maximum Retries Reached	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	Maximum number of retries reached.	When the maximum number of payment setup retry attempts has been reached	Create a new payment setup attempt or contact support for assistance

---

Error Codes Details

Reusing Vendor Payment Method

Duplicate vendor payment method

VendorPaymentMethodId Cannot Be Reused

The system prevents duplicate vendor payment method IDs in the database through a unique constraint.

Sample Invalid Request:

{
  "paymentMethod": {
    "vendorPaymentMethodId": "pm_already_exists_123",
    "paymentMethodDetails": {
      "type": "CARD",
      "nameOnCard": "John Doe",
      "manufacturerCard": false
    }
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 400,
  "detail": "VendorPaymentMethodId cannot be reused"
}

Manufacturer Card Validation

Default Payment Method Restriction

Manufacturer card cannot be default.

Sample Invalid Request using manufacturer flag:

{
  "paymentMethod": {
    "paymentMethodDetails": {
      "type": "CARD",
      "nameOnCard": "John Doe",
      "manufacturerCard": true
    },
    "isDefault": true
  }
}

Sample Invalid Request using card categories object:

{
  "paymentMethod": {
    "paymentMethodDetails": {
      "type": "CARD",
      "nameOnCard": "John Doe",
      "cardCategories": [
        {
          "type" : "MANUFACTURER_CARD",
          "medications" : [ {
            "label" : "DrugName",
            "value" : "24mg"
        }]
        }
      ]
    },
    "isDefault": true
  }
}

Sample Error Response:

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

Agent Information Required

Agent Information Required

Agent is required to add manufacturer card. This validation applies only when using the legacy manufacturerCard: true approach and is not required when using the new cardCategories object.

Sample Invalid Request:

{
  "paymentMethod": {
    "paymentMethodDetails": {
      "type": "CARD",
      "nameOnCard": "John Doe",
      "manufacturerCard": true
    },
    "isDefault": false
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 400,
  "detail": "Agent is required to add manufacturer card"
}

Missing Medication

Missing Medication

When setting up a manufacturer card using cardCategories, at least one medication must be specified.

Sample Invalid Request:

{
  "paymentMethod": {
    "paymentMethodDetails": {
      "type": "CARD",
      "nameOnCard": "John Doe",
      "cardCategories": [
        {
          "type": "MANUFACTURER_CARD",
          "medications": []
        }
      ]
    },
    "isDefault": false
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 400,
  "detail": "Medication is required to add manufacturer card"
}

Multiple Medication

Multiple Medications

Only one medication can be associated with a manufacturer card.

Sample Invalid Request:

{
  "paymentMethod": {
    "paymentMethodDetails": {
      "type": "CARD",
      "nameOnCard": "John Doe",
      "cardCategories": [
        {
          "type": "MANUFACTURER_CARD",
          "medications": [
            {
              "label": "Acetaminophen",
              "value": "125mg"
            },
            {
              "label": "Ibuprofen",
              "value": "200mg"
            }
          ]
        }
      ]
    },
    "isDefault": false
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 400,
  "detail": "Only one medication can be associated per manufacturer card"
}

Manufacturer Card not Configured

Manufacturer Card not Configured

When manufacturer card categories is requested and merchant is not configured

Sample Invalid Request:

{
  "paymentMethod": {
    "paymentMethodDetails": {
      "type": "CARD",
      "cardCategories": [
        {
          "type": "MANUFACTURER_CARD",
          "medications": [
            {
              // medication list
            }
          ]
        }
      ]
    },
    "isDefault": false
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 400,
  "detail": "MANUFACTURER_CARD category type is not enabled"
}

Maximum Retries Reached

Maximum number of retries reached.

The system limits the number of retry attempts when setting up a payment method using requestId. This error occurs when the maximum allowed number of retry attempts has been reached.

Sample Response:

{
  "title": "NOT_ACCEPTABLE",
  "status": 406,
  "detail": "Maximum number of retries reached."
}