The Cards API allows you to store, retrieve, and manage payment cards associated with customers. Cards on file enable faster checkout experiences and recurring payments.
Client Methods List Cards Retrieves a list of cards owned by the account making the request. A maximum of 25 cards will be returned.
client . Cards . List ( ctx context . Context , request * square . ListCardsRequest ) ( * square . ListCardsResponse , error )
Request parameters for listing cards A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results.
Limit results to cards associated with the customer supplied. By default, all cards owned by the merchant are returned.
Includes disabled cards. By default, all enabled cards owned by the merchant are returned.
Limit results to cards associated with the reference_id supplied.
Sorts the returned list by when the card was created with the specified order. This field defaults to ASC.
response
*square.ListCardsResponse
The list of cards
request := & square . ListCardsRequest { CustomerID : square . String ( "customer_id" ), IncludeDisabled : square . Bool ( false ), SortOrder : square . SortOrderDesc . Ptr (), } response , err := client . Cards . List ( context . TODO (), request ) if err != nil { log . Fatal ( err ) } // Iterate through cards for _ , card := range response . Cards { fmt . Printf ( "Card ID: %s , Last 4: %s \n " , card . ID , card . Last4 ) }
Create Card Adds a card on file to an existing merchant.
client . Cards . Create ( ctx context . Context , request * square . CreateCardRequest ) ( * square . CreateCardResponse , error )
request
*square.CreateCardRequest
required
Request parameters for creating a card A unique string that identifies this CreateCard request. Keys can be any valid string and must be unique for every request. Max: 45 characters.
The ID of the source which represents the card information to be stored. This can be a card nonce or a payment id.
An identifying token generated by Payments.verifyBuyer(). Verification tokens encapsulate customer device information and 3-D Secure challenge results.
Payment details associated with the card to be stored, including cardholder name, billing address, customer ID, and reference ID.
response
*square.CreateCardResponse
The created card details
request := & square . CreateCardRequest { IdempotencyKey : "4935a656-a929-4792-b97c-8848be85c27c" , SourceID : "cnon:uIbfJXhXETSP197M3GB" , Card : & square . Card { CardholderName : square . String ( "Amelia Earhart" ), BillingAddress : & square . Address { AddressLine1 : square . String ( "500 Electric Ave" ), AddressLine2 : square . String ( "Suite 600" ), Locality : square . String ( "New York" ), AdministrativeDistrictLevel1 : square . String ( "NY" ), PostalCode : square . String ( "10003" ), Country : square . CountryUs . Ptr (), }, CustomerID : square . String ( "VDKXEEKPJN48QDG3BGGFAK05P8" ), ReferenceID : square . String ( "user-id-1" ), }, } response , err := client . Cards . Create ( context . TODO (), request ) if err != nil { log . Fatal ( err ) } fmt . Printf ( "Card created with ID: %s \n " , response . Card . ID )
Get Card Retrieves details for a specific Card.
client . Cards . Get ( ctx context . Context , request * square . GetCardsRequest ) ( * square . GetCardResponse , error )
Unique ID for the desired Card.
request := & square . GetCardsRequest { CardID : "card_id" , } response , err := client . Cards . Get ( context . TODO (), request ) if err != nil { log . Fatal ( err ) } if response . Card != nil { fmt . Printf ( "Card Brand: %s , Last 4: %s \n " , response . Card . CardBrand , response . Card . Last4 ) }
Disable Card Disables the card, preventing any further updates or charges. Disabling an already disabled card is allowed but has no effect.
client . Cards . Disable ( ctx context . Context , request * square . DisableCardsRequest ) ( * square . DisableCardResponse , error )
Unique ID for the desired Card.
response
*square.DisableCardResponse
The disabled card details
request := & square . DisableCardsRequest { CardID : "card_id" , } response , err := client . Cards . Disable ( context . TODO (), request ) if err != nil { log . Fatal ( err ) } fmt . Println ( "Card disabled successfully" )
Key Concepts Card Nonces Card nonces are single-use tokens generated by the Square Web Payments SDK that represent card details. You use a card nonce as the SourceID when creating a card on file.
Card on File A card on file is a saved payment method associated with a customer. Benefits include:
Faster checkout for repeat customers
Support for recurring payments
Reduced PCI compliance scope
Card Security Square handles PCI compliance for stored cards. Card details are securely stored and tokenized. You never have access to the full card number after it’s saved.
SCA and 3D Secure For European customers, Strong Customer Authentication (SCA) may be required. Use the VerificationToken parameter to include 3-D Secure verification results when creating a card.
Card Object Fields The Card object includes:
ID: Unique identifier for the cardCardBrand: The card brand (e.g., VISA, MASTERCARD)Last4: Last 4 digits of the card numberExpMonth: Card expiration monthExpYear: Card expiration yearCardholderName: Name on the cardBillingAddress: Billing address for the cardCustomerID: Associated customer IDReferenceID: Optional external referenceEnabled: Whether the card is active
Learn More 