Recurring charges with PHP and Card on File

Whether you have a subscription service, or regular clients that you want to charge repeatedly, you can use Square’s e-commerce APIs and Card on File.

Keeping a customer’s card on file is almost identical to charging it with Square’s e-commerce APIs. The key difference is that instead of submitting a card nonce to a the charge endpoint, you attach it to a customer and then submit that customer’s attached card to be charged.

High level diagram of storing a card on file vs charging directly.

Now let’s dive into what this looks like from a code perspective. First, end users will need to input their card information into the SqPaymentForm. This is required the first time you store a user’s credit card; you cannot send us a previously recorded credit card number (or PAN) and attach it to a customer. For the most part we’ll copy & paste the sample form from the documentation site, with one important addition. We also must add a checkbox notifying the buyer that their card will be stored for future purchases. As noted in our documentation, linking cards without obtaining permission from the buyer may result in your app being disabled.

Next, we’ll add inputs to specify information about the customer that we want to attach the card to. In a production situation where you would be charging recurring payments, or subscription billing, you would likely want your customers to log in to your app or website and use the information from their logged in state to identify them as a specific customer. Since this is an example, I added a first and last name when the form is filled out, and create a new customer to attach the card on file for each time.

Always ask to keep a card on file!

With the modified card form up and running, we can start writing the code to process the payment. The form on our webpage will generate a card nonce, and then post it along with the customer information to a different php script process-card.php. This page will use Square’s PHP SDK to create a new customer, use the card nonce to attach the card to the customer for future subscription billing charges, and then charge the card. Lets dive in:

Creating a customer

Since we are using the PHP SDK, most of the hard work for creating a customer is hidden inside some useful functions. All we need to do is to pass the details of the customer (in our case a first and last name) to the createCustomer() method and voila — we’ve created a customer.

try {
 $result = $api_instance->createCustomer(
  array(
   'given_name'=> $first_name,
   'family_name'=> $last_name
   )
  );
 $customer = $result->getCustomer(); 
} catch (Exception $e) {
 echo 'Exception when calling CustomersApi->createCustomer: ', $e->getMessage(), PHP_EOL;
}

With our customer in place, the next step is to add the card (represented by the generated nonce) to the customer. Again, the PHP SDK will be doing much of the heavy lifting:

try {
 $result = $api_instance->createCustomerCard(
  $customer_id,
  array(
   "card_nonce"=>$_POST['nonce'],
   "billing_address"=>array(
    'postalCode' => $postal_code
    )
   )
  );
 $customer_card = $result->getCard();

Now that we have attached the card to the customer, we can use that information to make the charge. This is just like making the charge with directly with a card nonce, but instead of the card nonce we will be providing the charge endpoint with the customer_id and customer_card_id that we want to charge:

$transaction_api = new SquareConnect\Api\TransactionsApi();

try {
 $result = $transaction_api->charge(
  $location_id,
  array(
   'idempotency_key' => uniqid(),
   'amount_money' => array(
    'amount' => 200, 'currency' => 'USD'
    ),
   'customer_id' => $customer->getId(),
   'customer_card_id' => $customer_card->getId(),
   'note' => 'Subscription Billing'
   ));
 print_r($result);
} catch (Exception $e) {
 echo 'Exception when calling TransactionsApi->charge: ', $e->getMessage(), PHP_EOL;
}

ta-da! That’s all there is to charging a card on file. At the beginning of the month, or next time you want to charge a recurring fee, you only need to do the last step and charge the customer (since the customer, and their card, already exist).

If you want to learn more about recurring payments with Square, check out the official documentation, as well as the API reference for the relevant endpoints. As always, follow this blog and @SquareDev on twitter to keep up to date with new product releases and more tips & tricks.