Code Cookbook

Charge Cards on File

Create a seamless purchase experience for returning customers and enable recurring payments.

Customers API
Transactions API
PHP (Connect SDK)
Connect SDK
Save

Before you start

  • 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 Setup Guide to create your first Customer object.

Charge a saved card

Once you have saved a card on file, you can use the Transactions API and call the Charge endpoint to process the saved card. If you are using OAuth, you will need the PAYMENTS_WRITE permission.

To charge a saved card, use the Transactions API and set the customer_card_id and customer_id fields in the ChargeRequest object instead of the card_nonce field.

$customerId = "{YOUR_CUSTOMER_ID}"; // Replace with an existing customer_id
$customerCardId = "{SAVED_CARD_ID}";  // Replace with an existing customer_id

// The ID of the location to associate the created transaction with.
$locationId = '{LOCATION_TO_CREDIT_FOR_THE_TRANSACTION}';

// An object object from the PHP SDK with the fields to POST for the request.
$body = new \SquareConnect\Model\ChargeRequest();

// Set the customer card ID.
$body->setCustomerCardId($customerCardId);

// Set the customer ID.
$body->setCustomerId($customerId);

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

Once you have saved a card on file, you can use the Transactions API and call the Charge endpoint to process the saved card. If you are using OAuth, you will need the PAYMENTS_WRITE permission.

To charge a saved card, use the Transactions API and set the customer_card_id and customer_id fields in the ChargeRequest object instead of the card_nonce field.

# Assume you have correct values assigned to the following variables:
#   location
#   customer
#   customer_card

require 'square_connect'
require 'securerandom'

access_token = 'REPLACE_WITH_YOUR_ACCESS_TOKEN'

transaction_api = SquareConnect::TransactionApi.new

# Every payment you process for a given business hae a unique idempotency key.
# If you're unsure whether a particular payment succeeded, you can reattempt
# it with the same idempotency key without worrying about double charging
# the buyer.

idempotency_key = SecureRandom.uuid

# Monetary amounts are specified in the smallest unit of the applicable currency.
# This amount is in cents. It's also hard-coded for $1, which is not very useful.

amount_money = { :amount => 100, :currency => 'USD' }

transaction_request = {
  :customer_id => customer.id,
  :customer_card_id => customer_card.id,
  :amount_money => amount_money,
  :idempotency_key => idempotency_key
}

# The SDK throws an exception if a Connect endpoint responds with anything besides 200 (success).
# This block catches any exceptions that occur from the request.
begin
  transaction_response = transaction_api.charge(access_token, location.id, transaction_request)
rescue SquareConnect::ApiError => e
  raise "Error encountered while charging card: #{e.message}"
end

puts transaction_response

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow