This API is deprecated, see below for guidance on what to use instead.
Transactions API: Code Cookbook

Save Cards on File


Transactions API is deprecated. The API functionality is split into the new Payments API and a more robust Orders API. For more information, Payments and Refunds Overview and Orders: What it Does .

Customers API
In-App Payments SDK
Payment Form
Transactions API

PHP (5.x) (SDK)

Before you start Permalink Get a link to this section

  • You will need an access token . If you are using OAuth, you will need CUSTOMERS_WRITE permission to save a card on file and PAYMENTS_WRITE permission to process payments with the saved card. Cards on file are automatically updated on a monthly basis to confirm they are still valid and can be charged.

  • You need to have created a Customer object using the Customers API. You can follow the Customers API build guide to create your first Customer object.


Always ask customers for permission before saving their card information. For example, include a checkbox in your purchase flow that the customer can check to specify that they wish to save their card information for future purchases.

Linking cards on file without obtaining customer permission may result in your application being disabled without notice.

Step 1: Collect the card information Permalink Get a link to this section

Follow the steps in the Payment Form or In-App Payments SDK ( Android , iOS ) build guides to generate a valid card nonce.

Step 2: Save the customer card on file Permalink Get a link to this section

Use the Customers API to send the card nonce and the customer ID to the CreateCustomerCard endpoint.

It will return a customer card ID in the response field (customer_card_id).

$cardNonce = "{NONCE_FROM_STEP_1}";
$customerId = "{YOUR_CUSTOMER_ID}";  // Replace with an existing customer_id

// Create a CustomerCard request object
$body = new \SquareConnect\Model\CreateCustomerCardRequest();

// Set the card nonce value for your request object.

// Send the request to the CreateCustomerCard endpoint

try {
  $result = $customersApi->createCustomerCard($customerId, $body);
} catch (Exception $e) {
  echo 'Error when calling createCustomerCard: ', $e->getMessage(), PHP_EOL;