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.
- Prerequisite: A customer wallet with a saved
BANK_ACCOUNTpayment method. - Endpoint:
GET /v2/payment-methods/{id}βmerchant-wallet-managementscope - 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 Code | Description |
|---|---|
| R02 | Account Closed |
| R03 | No Account/Unable to locate account |
| R04 | Invalid account |
| R07 | Authorization revoked |
| R10 | Customer advises not authorized |
| R11 | Check truncation entry return |
| R12 | Branch sold to another DFI |
| R13 | Invalid ACH Routing number |
| R14 | Representative Payee deceased |
| R15 | Beneficiary or account holder deceased |
| R16 | Account frozen |
| R20 | Non-Transaction Account |
| R29 | Corporate Customer Advises Not Authorized |
| R30 | RDFI Not participant in Check Truncation Program |
| R31 | Permissible Return entry, a non-consumer related return code |
| R34 | Limited participation DFI |
| R35 | Return of improper Debit Entry |
| R36 | Return of improper Credit Entry |
| R37 | Source document presented for Payment |
| R38 | Stop payment on source document |
| R39 | Improper source document |
| R40 | Return of ENR entry by a Federal Government agency |
| R41 | Invalid transaction code ENR |
| R42 | Routing No/ Check Digit Error ENR |
| R43 | Invalid DFI Account No. ENR |
| R44 | Invalid Individual ID No. ENR |
| R45 | Invalid Individual / Company Name ENR |
| R46 | Invalid representative Payee indicator ENR |
| R47 | Duplicate enrollment of ENR Entry by a Federal Government agency |
| R50 | State law affecting RCK acceptance |
| R51 | Item related to RCK entry is ineligible or RCK entry is improper |
| R52 | Stop payment on RCK Item (adjustment entries) |
| R53 | Item and RCK entry presented for payment |
| R81 | Non-Participant in Cross-Border program 2 Banking days |
| R82 | Invalid Foreign receiving DFI identification |
| R84 | Entry 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β
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.statusbefore 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
Related Documentationβ
- Payment Methods β business capability overview
- Bank Account β bank account payment method overview
- Duplicate Payment Method
- Replaced Payment Method