Checking access…

Skip to main content
Version: v2

Invalidated Payment Method

When a bank's ACH network returns a transaction with a return code indicating the account can no longer be used (closed, invalid, frozen, etc.), CCG marks that bank account payment method as INVALIDATED. An invalidated payment method can no longer be used for payments or updated β€” the only action available on it is deletion.

Integration Details
  • Prerequisite: A customer wallet with a saved BANK_ACCOUNT payment method.
  • Endpoint: GET /v2/payment-methods/{id} β€” merchant-wallet-management scope
  • Use: Detecting and handling bank accounts that can no longer be used for payments

What Happens When a Payment Method Is Invalidated?​

  • Payments cannot be processed using that payment method.
  • Updating the payment method is prohibited.
  • The only permitted action is deleting the payment method.

List of Return Codes That Result in Invalidation​

Return CodeDescription
R02Account Closed
R03No Account/Unable to locate account
R04Invalid account
R07Authorization revoked
R10Customer advises not authorized
R11Check truncation entry return
R12Branch sold to another DFI
R13Invalid ACH Routing number
R14Representative Payee deceased
R15Beneficiary or account holder deceased
R16Account frozen
R20Non-Transaction Account
R29Corporate Customer Advises Not Authorized
R30RDFI Not participant in Check Truncation Program
R31Permissible Return entry, a non-consumer related return code
R34Limited participation DFI
R35Return of improper Debit Entry
R36Return of improper Credit Entry
R37Source document presented for Payment
R38Stop payment on source document
R39Improper source document
R40Return of ENR entry by a Federal Government agency
R41Invalid transaction code ENR
R42Routing No/ Check Digit Error ENR
R43Invalid DFI Account No. ENR
R44Invalid Individual ID No. ENR
R45Invalid Individual / Company Name ENR
R46Invalid representative Payee indicator ENR
R47Duplicate enrollment of ENR Entry by a Federal Government agency
R50State law affecting RCK acceptance
R51Item related to RCK entry is ineligible or RCK entry is improper
R52Stop payment on RCK Item (adjustment entries)
R53Item and RCK entry presented for payment
R81Non-Participant in Cross-Border program 2 Banking days
R82Invalid Foreign receiving DFI identification
R84Entry not processed by gateway

API Request​

There is no request that causes invalidation directly β€” it results from an ACH return on a prior payment. To check whether a payment method is currently invalidated before attempting a payment, request its current state:

GET /v2/payment-methods/{id}
X-Merchant-Id: {merchantId}

API Response​

The endpoint wraps the payment method in a { url, data } envelope β€” status is read from data.paymentMethodDetails.status, not from the top level:

{
"url": "/v2/payment-methods/497f6eca-6276-4993-bfeb-53cbbbba6f08",
"data": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"paymentMethodType": "BANK_ACCOUNT",
"paymentMethodDetails": {
"type": "BANK_ACCOUNT",
"accountType": "checking",
"status": "INVALIDATED",
"bankName": "STRIPE TEST BANK"
}
}
}

data.paymentMethodDetails.status is a read-only field with possible values ACTIVE or INVALIDATED (see the USBankAccountDetailsSummaryResponse schema). Attempting to pay with or update a payment method in INVALIDATED status returns an error β€” see Error Handling below.

Status Handling​

Check data.paymentMethodDetails.status before attempting a payment or an update against a saved bank account. There is no polling involved β€” invalidation happens asynchronously (driven by the ACH return) and is reflected the next time the payment method is read.

Webhooks​

Not yet in the webhooks-v2 OpenAPI spec

A status change to INVALIDATED is expected to surface via PAYMENT_METHOD_UPDATED, but payment-method lifecycle events are not currently modeled in /webhooks-v2/ (only Payment, Refund, and Dispute are). Confirm current webhook behavior with your CCG integration contact rather than relying on this as a versioned contract.

Error Handling​

Payment and update requests against an INVALIDATED payment method fail β€” see the Payment Error Codes reference for the relevant error response shape. There is no error code specific to this use case beyond the standard validation failure for the attempted operation.

FAQ​

Can an invalidated payment method be reactivated?​

No. The only permitted action is deletion β€” add a new payment method instead.

How do I know which return code caused the invalidation?​

The return code itself is not currently exposed on the payment method resource. Contact CCG support if you need the originating return code for reconciliation.

What should my integration do when it encounters an invalidated payment method?​

Stop attempting payments against it, prompt the customer to add a new payment method, and allow deletion of the invalidated one.

Integration Checklist​

  • Check data.paymentMethodDetails.status before attempting a payment against a saved bank account
  • Handle payment/update failures against invalidated payment methods distinctly from other validation errors
  • Prompt customers to add a replacement payment method rather than retrying the invalidated one
  • Allow deletion of invalidated payment methods in your UI