Language:

Processing a card payment (Ruby)

After the SqPaymentForm generates a card nonce and you submit it to your server, you finish processing the payment by sending a request to the Charge endpoint with the details of the transaction.

If your server is implemented in Ruby, you can use the square_connect client library to simplify making requests to all Connect v2 endpoints.

Installing the square_connect gem

You install the square_connect gem the same way you install any other gem:

gem install square_connect

Retrieving your location IDs

Every Square merchant's business consists of one or more locations. Every payment a merchant processes is associated with one of these locations (even online payments). In order to process a payment with Connect v2, you need to know which location you want to associate the payment with.

The square_connect library has an easy method for obtaining a business' location IDs: the list_locations method.

Paste the following into a locations-test.rb file and run it with ruby locations-test.rb. Be sure to specify your personal access token where indicated. The details of your business' locations will appear in the console.

require 'square_connect'

access_token = 'REPLACE_WITH_YOUR_ACCESS_TOKEN'

SquareConnect.configure do |config|
  config.access_token = access_token
end

locations_api = SquareConnect::LocationsApi.new

begin
  locations_response = locations_api.list_locations
  puts locations_response
rescue SquareConnect::ApiError => e
  raise "Error encountered while listing locations: #{e.message}"
end

# Get a location able to process transaction
location = locations_response.locations.detect do |l|
  l.capabilities.include?("CREDIT_CARD_PROCESSING")
end

if location.nil?
  raise "Activation required.
  Visit https://squareup.com/activate to activate and begin taking payments."
end

puts location

Charging the card nonce

Now that you've generated a card nonce with the SqPaymentForm and you have a way to retrieve a business' location IDs, you can charge a buyer's card, like so:

require 'square_connect'
require 'securerandom'

# Assume you have correct values assigned to the following variables:
#   NONCE
#   LOCATION_ID
#   ACCESS_TOKEN

# Setup authorization
SquareConnect.configure do |config|
  config.access_token = 'YOUR ACCESS TOKEN'
end

transactions_api = SquareConnect::TransactionsApi.new

request_body = {

  :card_nonce => NONCE,

  # 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'
  },

  # Every payment you process for a given business have 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
}


# 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
  resp = transactions_api.charge(LOCATION_ID, request_body)
rescue SquareConnect::ApiError => e
  raise "Error encountered while charging card: #{e.message}"
end

puts resp

The value of resp is a hash that contains all of the details of the processed transaction.

Trying it out

A full sample that uses the SqPaymentForm is available on GitHub. See the sample's README for information on running the sample.

If you want to test out charging cards without actually moving any money, you can configure the sample to communicate with Connect v2 sandbox endpoints. For more information, see Using the API sandbox.

Learn about OAuth

So far in this tutorial, you've used your personal access token, which gives you full access to your own business' data. If you are developing an application for other businesses to use as well, you use the OAuth API to generate access tokens for those businesses.

The OAuth flow in Connect v2 is identical to the flow in v1. Learn more about the OAuth flow. Code samples for the OAuth flow are available on GitHub.

Important: In order for your app to process payments on behalf of another merchant, the merchant must authorize your application with the PAYMENTS_WRITE OAuth permission.

Ask for help on Stack Overflow or join our Slack channel