Trying to understand the Customers API

So, assuming I have the checkbox for “Allow us to save your information for next time”, and we create the Customer record, and then we have the checkbox for “Allow us to save your credit card info for next time” and we create a Customer Card. I’m assuming that’s all stored nice and securely on Square’s servers. My confusion comes the next time the user comes to our site and we say at the beginning of the checkout process “Sign in to use your previously-saved info and credit card!” - I ask them for … their e-mail address I’m guessing, and then using the Customer API I can search for that e-mail address and get the Customer record from there, and charge their card on file … but isn’t that completely insecure? All I have to do is know the email address of my friend and know that he shops at our store, and I can begin charging things to his card… What am I missing here? I would have expected some level of security around this customer information, and there are things in the documentation about customer records being merged automatically, I’m not sure I understand that aspect of it either … please point me in the right direction!


1 Like

Hi Steve, thanks for posting. Good Qs!

As for the first question about secure Customer Card flows, I believe the expectation and standard integration flow would be that you would, in addition to collecting email for return visit login and card use, tie that email to a password and account. That is, the user would have to return and enter their email along with a password to access the account and stored card. Additionally, you could require verification of ownership of the email via one time codes or similar methods for added protection. Customer Cards enable you to stash a card with a Customer Record, but you still need to wrap that functionality in standard, appropriate login and verification mechanisms. @sjosey – does that sound right to you?

re: Automatic customer profile merging – I can speak to that part (I’m the Product Manager for Customers API):
(1) our predictive duplicate detection methods will NOT merge profiles that contain cards on file.
(2) our deterministic duplicate detection methods are primarily based on identifying duplicate profiles based on the same phone or email appearing on multiple profile. It is possible we would merge customers with Customer Cards that have matching phones or emails, but only if there was no conflicts in either field. As a result, there should not be situations where a profile with a Customer Card is merged and the resulting merged profile has any destructive changes to an email or phone field. So, if you were using either identifier for account login tied to a card, it would not be modified in a merging operation. I believe this would address the concern your envisioning.

Please let us know what follow up Qs you have. Thanks!

Thanks for the response. I will look into building our own username/password system as you suggest, but I would like to provide a little bit of feedback on this point:

Building this out is going to require that I pay very close attention to things like storing the passwords in salted and encrypted form, and be vigilant about building our small business website in a manner which is secure from attack, and cannot be hacked because now we are storing sensitive user-identifying information. As a small company with a limited development budget, this is an onerous requirement, especially given that all I’m going to be storing is email & password & the Square Customer ID, because you guys already have all the information that I need. The Customer API as it stands currently, while it looks really useful at first glance, actually is kinda like building a barn and not putting a door on it. It feels like without the protection we’re talking about, the Customer API is of very limited use - can you describe for me a prospective workflow where it would not be necessary for the merchant (i.e. me) to write a security wrapper around access to the Customer API? I honestly would like to know, because I was just basing my original question on the standard sort of “sign in for simplified checkout” functionality I’ve seen in other e-commerce sites. I suppose I could use LocalStorage to store the customer ID in the user’s browser, but that seems less than secure, though I suppose since it’s only accessible by our application having someone discover the customer’s Square customer id wouldn’t be a big deal. Some advice in this regard would be greatly appreciated!

Valid questions and feedback, thanks for sharing! I think there is some confusion here (and maybe therefore something we can better communicate in our docs) about the scope of the Customers API and Customer Card endpoints. The Customers API is intended to be lean customer resource ‘primitive’ enabling you to sync customer profiles btw. Square Customer Directory ( and third party applications and systems. This is typically used to sync data in and out of Square’s CRM to power customer programs across channels (analytics, marketing, loyalty, personalization, etc.) either using Square first party tools (e.g. Square Marketing, Loyalty) or third party tools (data warehouse, marketing, CRM, etc.), or both. These use cases don’t generally require or have a log-in/auth component on top.

The Customer Card endpoints then enable linking a customer record to a card for repeat use. However, the Cards functionality here in these endpoints is not intended to solve for auth and log-in. For that, I believe you could either (1) Use Square Online Store (2) use a 3rd party plug in or integrated e-com platform from the partner App Marketplace ( to help power parts (or all) of the e-com flow , or (3) you could build this custom as we’re discussing here on top of the Square APIs. More info and comparison on those approaches can be found here: In other words, Customers API and the Customer Card endpoints are intended to be flexible lean components that can then be built on and integrated into e-com and other experiences using any of these various approaches. I should have suggested these other approaches in my initial reply, apologies for that!

@sjosey or @Bryan-Square – does that sound right to you, anything you’d add? what would you recommend here given the need that is being solved for and the context that they are a small business with limited budget? Is there an App Marketplace plug-in you’d suggest? Or is there API or SDK utilities I’m not aware of that Square provides that could help here?

cc @keenan-square @heisel-square for visibility and any further input as well

@Steve Both Auth0 and Google’s Firebase provide drop in integration of authentication services. The free tier of either is enough for the needs of most small businesses.

Thank you @jcelias!!

This makes stored CCs a gaping hole in the benefits of the square API. The beauty of Square API’s CC processing is never having anything in my APP or database that could compromise CC data. If we choose to store CC info in Square, but have to code our own authentication, the security benefits of Square are completely lost. If my authentication routine allows someone to the gain access to a CC stored at Square, my site, database, server, facility and code likely now fall under PCI DSS requirements. We love Square for removing the PCI DSS requirements from our development and hosting. Stored CC numbers can’t be worth that level of effort. Without stored CC info, even if we get hacked, our compromised data exposure is Name, email, phone number and order history.

Thanks for the feedback @SeanD. To be clear, even stored cards would never return enough details to actually know the full card number (thus you would still not need to be PCI compliant).

Also, just to point out, even if you do not store the cards, you can see the exact same card information on the Payments API (last 4, expiration, brand, etc). The storing of the card just allows you to charge it again at the later time, but it doesn’t reveal extra information.

@sjosey Thanks, very true and an important distinction. Accessing someone else’s stored CC would only give you access to charge it from this Square App or Account, not anywhere else.

I’ve been pondering this at length since I originally asked the question, and I can see your point, and understand that the Customers and Customer Card API’s are intended to be fairly small footprint, but I keep coming back to this idea that without somehow limiting access to the stored card data, it opens us (and by “us” I mean my client merchant and myself) up to unintended mis-use of the stored cards - as I mentioned up front, all I need to know is my friend’s e-mail address and phone number, and the fact that he shops at this online store, to successfully start charging things on the store to his card. Going down that road leads to fraudulent use of the stored card, and all kinds of unpleasantness. I realize that it’s my responsibility to ensure that doesn’t happen, by building some password protection around access to the Customers API, and you’ve given me some good food for thought on how to do this, but if I were Square, it would give me some heartburn at night knowing that my API could be (fairly easily) misused in that way by some dumb web developer who doesn’t think things through properly…

Just my 2cents for what it’s worth… :slight_smile:

1 Like