CreateInvoice returns INVALID_CARD for a card created seconds earlier with CreateCard

Questions
, ,
1

We’re seeing intermittent INVALID_CARD errors from CreateInvoice in production, and we’d like to understand what causes them and how to avoid them.

Our flow (Web Payments SDK, then server-side calls)

  1. The browser calls card.tokenize(verificationDetails) with intent CHARGE_AND_STORE, the amount, currencyCode: 'USD' and a billingContact.
  2. Our server calls CreateCustomer if needed, then CreateCard with that cnon: token as source_id.
  3. About one second later, it calls CreateOrder and then CreateInvoice with automatic_payment_source: CARD_ON_FILE and the new card_id.

The error that CreateInvoice sometimes returns:

[{'code': 'INVALID_CARD', 'detail': 'The selected card on file is no longer available for this customer. Choose another payment method.', 'category': 'PAYMENT_METHOD_ERROR'}]

When this happens:

  • RetrieveCard shows the card as enabled: true, on the same customer as the invoice’s primary_recipient.
  • The same card can be invoiced successfully later.

What seems to predict it Across about 20 failures since 2026-09-01, the outcome tracks the last protobuf field (field 5) of the ccof: card id:

  • Every Visa/Mastercard card with field 5 = 1 (ids ending …oAQ) was rejected by CreateInvoice.
  • Every card with field 5 = 2 (ids ending …oAg) was accepted.

The token’s own field 5 doesn’t predict it: we’ve seen a token with 1 produce a card with 2, and a token with 2 produce a card with 1. Retrying with a fresh token 3 seconds later got another card with field 5 = 1 and was rejected again. A retry about 3 minutes later got 2 and worked.

Example from 2026-09-30 (UTC), one buyer:

Time Card id Field 5 Order Result
13:58:47 ccof:CA4SEFZO8TOvmdOmiQjkhMeGyeEoAQ 1 dXUwAdNkYbUnye0ZpPOgJkrmZ16YY INVALID_CARD
13:58:50 ccof:CA4SELOIrmyIFu-H3ZqI5MwqMQAoAQ 1 BtmEsmVDhC5uUclSQtzmUFvpuLSZY INVALID_CARD
14:01:46 ccof:CA4SEB68CpFcqFRgbNiVXXQO-IEoAg 2 (invoice created) success

Questions

  1. How long does that state last, and is there an API signal we can check before calling CreateInvoice, other than decoding the id?
  2. What’s the recommended way to take a first invoice payment and keep the card for recurring invoices?

Happy to provide more ids or logs.

3

Hi,

Welcome to the Square Developer Forums!

This looks consistent with a short-lived availability delay between creating a card on file and that card becoming usable by the Invoices payment flow.

There is not a supported public readiness field or preflight endpoint that confirms a newly-created card can be used with CreateInvoice.
Specifically:

  • RetrieveCard.enabled = true confirms the card record is enabled, but it is not an Invoices-readiness signal.
  • The encoded contents or suffix of a ccof: card ID are internal implementation details. They should not be decoded or used in production logic, even if they appear to correlate with this behavior.

For a card created immediately before invoicing, I’d recommend treating this specific “INVALID_CARD” as potentially transient.
Recommended handling:

  • Use an idempotency key for CreateInvoice.
  • Retry a small, bounded number of times with exponential backoff and jitter.
  • Retry only for this specific immediate-post-CreateCard error case.
  • If the error persists, present an alternate payment method or retry later.
  • Avoid creating duplicate cards or relying on decoded card ID patterns.

For the first payment, the right approach depends on whether the first charge must be collected as an invoice payment.
If the first payment does not need to be represented as an invoice payment, a safer flow is:

  1. Tokenize with the Web Payments SDK.
  2. Create or retrieve the customer.
  3. Create the initial payment using the token/customer-associated payment method.
  4. Save the card for future use, using the supported card-on-file flow for that payment method.
  5. Use the saved card on file for later recurring invoices.