Adding card on file details with Python

Attaching a customer’s card on file to their Square profile is an important part of setting up recurring payments. Here’s how to do it with Python.

In this post we’ll be using the CustomerCard endpoints to add a card on file to a customer that you could then use for subscription billing online or in-person. But remember, you should not link a card on file to a customer without the customer’s express permission. For example, you can include a checkbox in your purchase flow (unchecked by default) that the customer can check to specify that they wish to save their card information for future purchases.


To get started you’ll need a Square account, an application in the Square developer portal, and of course, at least one customer to attach the card to. You can create your Square account at, your developer application at and to create your customer you can either use the Square Point of Sale app or use the APIs to create a customer in your customer directory.

Attaching the card on file

Adding a card on file is very similar to charging a card for an e-commerce transaction. You’ll have to generate a card nonce using the sqpaymentform and then pass it to the CreateCustomerCard endpoint. Since the payment form will have to be embedded in a different client-facing page, and the REST request to attach the customer card will be hidden away on the server’s side, this example will just use a hardcoded testing nonce. Let’s look at the code:

# use Square's SDK to make your job easier
import squareconnect
from squareconnect.apis.customers_api import CustomersApi
from squareconnect.models.create_customer_card_request import CreateCustomerCardRequest

# setup authorization with your access token
squareconnect.configuration.access_token = 'sandbox-sq0atb-XXXXXXXX'

# using a hardcoded nonce, but in a production evironment you'll need to use the
# payment form: 
nonce = 'fake-card-nonce-ok'

# Your customer id will likely be dynimcally chosen, but again we will use a 
# hard coded example
customer_id = 'CBASEBW5Mh0hBis1BAGMoXamePwgAQ'

# create an instance of the Location API class
api_instance = CustomersApi()
customer_card = CreateCustomerCardRequest()
customer_card.card_nonce = nonce
customer_card.cardholder_name = 'Sam Smith'

# call the API to create the employee and print the results
api_response = api_instance.create_customer_card(customer_id,customer_card)
print (api_response)

Here you can see the code first initializes the Square Python SDK and imports a couple of useful tidbits, such as the CustomersAPI and the model for creating the customer card request. Then you’ll need to set the access token. I recommend using a sandbox access token so that you can use the fake card nonce also hard coded in this example.

When it comes to actually creating the CustomerCard, the code uses the model that was imported above, and attaches the card nonce, as well as made up cardholder_name. You also have the option to add a billing_address but it is not required.

The result

You can run this code snippet directly from your command line with a command link python (or whatever you decided to name the file). If everything goes well, you should see something like the below as your customer card details are printed on the screen.

Now you can use the card to make card-on-file purchases in person or online to meet your billing needs!

Thanks for reading. If you have any questions, comments, concerns, or excitements, feel free to comment on this post below, or reach out to us on Twitter.

Table Of Contents
View More Articles ›