Version: v2

Payment Error Codes

This page documents all Split Tender–specific error codes for the Payment API (v2). These errors occur when processing payments that involve multiple payment methods. Each error includes the code name, HTTP status, description, recommended developer action, and notes where applicable.

Quick Reference to Related Error Codes

For customer object validation error, see the Customer Object Error Codes
For Payment object validation error, see the Payment Object Error Codes
For Agent object validation error, see the Agent Object Error Codes
For Consent object validation error, see the Consent Object Error Codes
For Payment Details object validation error, see the Payment Details Object Error Codes

Error Codes Summary

Error Code Summary

Error Category	Error Title Reference	Error Title	HTTP Status	Error Message
CCG Schema Validation	Consent Requirement	INVALID_REQUEST	`400 BAD REQUEST`	Consent is required!
CCG Business Validation	Payment Method Not Found	PAYMENT_METHOD_ERROR	`406 NOT_ACCEPTABLE`	paymentAllocations[n].paymentMethodId not found. Please provide a valid payment method
CCG Business Validation	Payment Method Type Not Configured	PAYMENT_METHOD_ERROR	`406 NOT_ACCEPTABLE`	Payment method ending with `{last4}` is not configured. Please provide a valid payment method.
CCG Business Validation	Manufacturer Card Type Not Configured	PAYMENT_METHOD_ERROR	`406 NOT_ACCEPTABLE`	Manufacturer card ending with `{last4}` not enabled for this merchant. Please use a different payment method
CCG Business Validation	Invalid Payment Methods	PAYMENT_METHOD_ERROR	`406 NOT_ACCEPTABLE`	Payment method ending with `{last4}` is invalid. Please provide a valid payment method
Payment Processor Validation	Vendor Processing Error	PAYMENT_METHOD_ERROR	`406 NOT_ACCEPTABLE`	One of the split tender card payments failed during processing.
CCG Business Validation	Card Requires 3D Secure Authentication	PAYMENT_METHOD_ERROR	`406 NOT ACCEPTABLE`	This card requires an additional security step to be performed by the customer. Please have the customer enter the card via text or email; otherwise, have the customer provide a different payment method.
CCG Business Validation	Payment Method Requires Authentication	PAYMENT_METHOD_ERROR	`406 NOT ACCEPTABLE`	Payment method could not be authorized. This payment method requires authentication from a customer.

Error Codes Details

Consent is required! (needs review)

Details:

Scenario: Payment processing requires appropriate consent information when Bank Account Payment Method is used. Refer Consent Object Error Codes for consent specific error codes
Resolution: Include a valid consent object with all required fields for ACH Payments. Refer ACH Consent for more details
API Endpoints: /v2/payments
Scopes: user, merchant

Sample Request

{
  "paymentAllocations": [
    {
      "paymentMethodId": "bank-account-pm-id",
      "amount": 123
    }
  ],
  "consent": null
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Consent is required!"
}

Payment Method Not Found

Payment Method not found

Details:

Scenario: This error occurs when the requested payment method cannot be found in the system
- Payment method id is a valid UUID, but doesn’t exist in the system
- Payment method was deleted by the customer
- Payment method belongs to a different customer

Sample Request

{
  "paymentAllocations": [
    {
      "paymentMethodId": "uuid",
      "amount": 123
    }
  ]
}

Sample Response

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 406,
  "detail": "paymentAllocations[n].paymentMethodId not found. Please provide a valid payment method"
}

Invalid Payment Methods

One or more payment methods are invalid

Details:

Scenario: This error occurs when one or more payment methods provided in the request is invalid.
- Payment method not associated to Customer
- Payment Method is not in valid Status (eg: CARD is expired or ACH is invalidated)
API Endpoints: /v2/payments
Scopes: merchant

Sample Request

{
  "paymentAllocations": [
    {
      "paymentMethodId": "uuid",
      "amount": 123
    }
  ]
}

Sample Response

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 406,
  "detail": "Payment method ending with {last4} is invalid. Please provide a valid payment method"
}

Payment Method Type Not Configured

Payment method type is not configured.

Details:

Scenario: This error occurs when attempting to use a payment method type that is not configured for the merchant account.
API Endpoints: /v2/payments
Scopes: merchant

Sample Request

{
  "paymentAllocations": [
    {
      "paymentMethodId": "uuid",
      "amount": 123
    }
  ]
}

Sample Response

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 406,
  "detail": "Payment method ending with {last4} is not configured. Please use a configured payment method type"
}

Manufacturer Card Type Not Configured

Manufacturer Card type is not configured.

Details:

Scenario: This error occurs when attempting to use a manufacturer card payment method that is not configured for the merchant account.
API Endpoints: /v2/payments
Scopes: merchant

Sample Request

{
  "paymentAllocations": [
    {
      "paymentMethodId": "uuid",
      "amount": 123
    }
  ]
}

Sample Response

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 406,
  "detail": "Manufacturer card ending with {last4} not enabled for this merchant. Please use a different payment method"
}

Card Requires 3D Secure Authentication

This card requires an additional security step to be performed by the customer. (needs review)

Details:

Scenario: This error occurs when a card requires 3D Secure authentication in an agent session. The agent cannot complete the authentication on behalf of the customer.
Resolution: Guide the customer to complete the card entry via SMS or email where 3D Secure can be handled, or request an alternative payment method.
API Endpoints: /v2/payments
Scopes: merchant

Sample Response

{
  "title": "NOT_ACCEPTABLE",
  "status": 406,
  "detail": "This card requires an additional security step to be performed by the customer. Please have the customer enter the card via text or email; otherwise, have the customer provide a different payment method."
}

Payment Method Requires Authentication

Payment method could not be authorized. (needs review)

Details:

Scenario: This error occurs when a card requires 3D Secure authentication from a customer in an agent session. The payment method cannot be authorized without customer authentication.
Resolution: Guide the customer to complete the card entry via SMS or email where 3D Secure can be handled, or request an alternative payment method.
API Endpoints: /v2/payments
Scopes: merchant

Sample Response

{
  "title": "NOT_ACCEPTABLE",
  "status": 406,
  "detail": "Payment method could not be authorized. This payment method requires authentication from a customer."
}

Vendor Processing Error

One of the split tender card payments failed during processing. (needs review)

Details:

Scenario: One or more card payment allocations failed at the vendor during processing; the API returns the allocation-level statuses and errors.
Resolution: Inspect the paymentAllocations array in the response to identify which allocations failed; retry or prompt the user to use an alternate payment method.
API Endpoints: /v2/payments
Scopes: merchant, user

Sample Response

{
  "title": "PAYMENT_METHOD_ERROR",
  "detail": "One of the split tender card payments failed during processing.",
  "status": 406,
  "paymentAllocations": [
    {
      "id": "d3f8a2b4-7c9e-4a1e-9f2d-8e6b3c1a2f45",
      "paymentMethod": {
        "id": "9e1e48cc-0185-4513-a41b-2daf6be91102",
        "paymentMethodDetails": {
          "type": "CARD",
          "last4": "4444",
          "expiryMonth": 8,
          "expiryYear": 2030,
          "nameOnCard": "card1",
          "status": "ACTIVE",
          "cardBrand": "MASTERCARD"
        },
        "default": false
      },
      "status": "FAILED",
      "error": {
        "title": "PAYMENT_METHOD_ERROR",
        "detail": "The card number is incorrect.",
        "errorDetails": {
          "code": "incorrect_number",
          "message": "Your card number is incorrect.",
          "declineCode": "incorrect_number",
          "networkAdviceCode": "03",
          "networkDeclineCode": "79"
        }
      }
    },
    {
      "id": "e3f8a2b4-7c9e-4a1e-9f2d-8e6b3c1a2f45",
      "paymentMethod": {
        "id": "0e1e48cc-0185-4513-a41b-2daf6be91102",
        "paymentMethodDetails": {
          "type": "CARD",
          "last4": "4444",
          "expiryMonth": 8,
          "expiryYear": 2030,
          "nameOnCard": "card1",
          "status": "ACTIVE",
          "cardBrand": "MASTERCARD"
        },
        "default": false
      },
      "status": "FAILED",
      "error": {
        "title": "PAYMENT_METHOD_ERROR",
        "detail": "The card was declined for an unknown reason. Contact issuer for more information.",
        "errorDetails": {
          "code": "card_declined",
          "message": "Your card was declined.",
          "declineCode": "generic_decline",
          "networkDeclineCode": "01",
          "networkAdviceCode": null
      }
    }
  ]
}

Error Codes Summary​

Error Codes Details​

Consent Requirement​

Payment Method Not Found​

Invalid Payment Methods​

Payment Method Type Not Configured​

Manufacturer Card Type Not Configured​

Card Requires 3D Secure Authentication​

Payment Method Requires Authentication​

Vendor Processing Error​

Error Codes Summary

Error Codes Details

Consent Requirement

Payment Method Not Found

Invalid Payment Methods

Payment Method Type Not Configured

Manufacturer Card Type Not Configured

Card Requires 3D Secure Authentication

Payment Method Requires Authentication

Vendor Processing Error