Hi team,
I’m encountering an issue while trying to save a card on file via the Cards API after a successful payment.
Here’s the flow:
A customer makes a payment using a Square-hosted payment link (Checkout API).
- The payment is successful — confirmed via the
payment.created webhook.
- In the webhook handler, I attempt to save the card on file using:
payment['id'] as the card tokencustomer_id from the same webhook payload
Here’s the code I use:
$card = new \Square\Models\Card();
$card->setCustomerId($customer_id);
$body = new \Square\Models\CreateCardRequest(
uniqid(), // idempotency key
$payment[‘id’], // payment ID used as token
$card
);
$response = $cardsApi->createCard($body);
The issue:
- This works fine for most users — card is saved on file successfully.
- But for one specific client , the same logic throws an
INVALID_CARD_DATA error.
- The payment still goes through successfully for that user.
Any insights or guidance would be appreciated — thanks in advance! Please try to repond as soon as possible.
I’m Square Dev AI, here to help answer your question!
Based on the information you’ve provided, the following documentation will help answer your question:
Additional Documentation
Cards API
Create a Card on File and a Payment
Create a Shared Card on File and Make a Payment
If this documentation helped you find a solution, please check the box indicating that this reply solves the problem.
Otherwise one of our Developer Advocates will provide additional assistance shortly.
Was the payment_id that you used to store the card on file a digital wallet payment? Currently, we don’t support storing a digital wallet on file which will cause this error. 
The payment was not made using a digital wallet. I have restricted the payment option to only allow standard card payments.
What was the payment_id that failed?
Here is the payment id PvYmOS3m8tQcZnR2xK3LmpQJ4c8YY
This is a Square Online Store payment that was made with a stored card on file. Storing an already stored card on file isn’t possible with the Cards API.
Hello Team,
I’m a bit confused about the behavior I’m seeing. When I try to fetch the card details using the customer_id received in the payment response, I’m getting an empty result — no cards are returned.
However, the Square support response mentioned that the payment was made using a stored card on file. If the card is indeed stored, why doesn’t it appear when I retrieve cards for that customer ID?
Could you please clarify this behavior? I’ve attached a screenshot for reference.
Did your application store the card on file? If not and this was a Square pay payment with the stored card on file for the customer the card isn’t available with the Cards API.
I use the Checkout API to create a payment link and send it to customers.
The customer opens the link and completes the payment.
After the payment, I receive the payment.created webhook.
And then using Card API I’m stoing the card on file. This is how my simple scenario.
And now for above payment_id I’m seeing “entry_method”: “ON_FILE”.
My questions are
1)How is it possible that a card is “on file” for my application if the user has never transacted with my system before?
2)What’s the proper way to store a card under my own application so that I can later charge it for recurring payments?
I want to ensure that any card used during a payment can be stored securely and be available for future charges through the Cards API
Any clarification you can provide on how this works and the best practice for storing cards in this scenario would be greatly appreciated.
And please, it’s very urgent for me to resolve this problem.
This is possible if the customer used Square Pay which is a globally stored card on file. Unfortunately, applications don’t have access to these stored cards on file.
Your are storing the card correctly however for this scenario you can’t store a card on file when the payment was made through Square pay.
