Charge Cards on File
Create a seamless purchase experience for returning customers and enable recurring payments.
Process Overview
Before you start
- You will need an access token. If you are using OAuth, you will need
CUSTOMERS_WRITEpermission to save a card on file andPAYMENTS_WRITEpermission to process payments with the saved card. - You need to have created a
Customerobject using the Customers API. You can follow The Customers API Setup Guide to create your firstCustomerobject.
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