How to Process Payments with Square API in Ruby

Install Required Gems

• Add the Square SDK gem to your `Gemfile`:

gem 'square'

• Run `bundle install` to install the gem.

Set Up Authentication

• Retrieve your Access Token from your Square Developer Account.

 

• Configure the Square client with your access token. It’s best practice to store such sensitive information in environment variables:

require 'square'

Square.configure do |config|
  config.access_token = ENV['SQUARE_ACCESS_TOKEN']
end

Create a Payment

• To process a payment, you’ll need to build a `CreatePaymentRequest` object with necessary details. This includes the source ID, amount, and location ID. The source ID is typically generated by a Square payment form or sourced from a saved card on file.

client = Square::Client.new

request_body = {
  :source_id => 'cnon:card-nonce-ok',
  :idempotency_key => SecureRandom.uuid,
  :amount_money => {
    :amount => 100, # example amount in cents
    :currency => 'USD'
  },
  :location_id => 'LOCATION_ID'
}

response = client.payments.create_payment(request_body)
if response.success?
  puts "Payment successful: #{response.data[:payment]}"
else
  puts "Error processing payment: #{response.errors}"
end

Handle Errors and Responses

• Always check the response for errors and log them appropriately. Square API might return error messages that give insight into what went wrong during the payment processing.

 

• Inspect both `response.success?` and `response.errors` to manage payment success and failure cases:

if response.success?
  puts "Payment was successful."
else
  response.errors.each do |error|
    puts "Error: #{error[:category]} - #{error[:code]}: #{error[:detail]}"
  end
end

Store Payment Details

• After a successful payment, you might want to store transaction details in your database for records and future reference.

if response.success?
  payment = response.data[:payment]
  
  # Example: saving to a hash or ORM database model
  payment_details = {
    id: payment[:id],
    amount: payment[:amount_money][:amount],
    status: payment[:status],
    created_at: payment[:created_at]
  }
  
  # Save payment_details to your preferred data store or log it appropriately
end

Implement Webhooks for Asynchronous Responses

• Square can send asynchronous notifications about payment status changes. Set up webhooks in your developer dashboard, and implement a public endpoint to handle these notifications in your Ruby app.

 

• Process the payment event data to update your system state accordingly:

post '/webhooks/square' do
  request.body.rewind
  payload = JSON.parse(request.body.read)
  
  if payload["type"] == "payment.updated"
    payment_id = payload["data"]["object"]["payment"]["id"]
    puts "Payment updated: #{payment_id}"
    # Update your local database records as needed
  end
  
  status 200 # Respond with 200 to acknowledge receipt
end

Security Best Practices

• Always verify the origin of webhook events received using the `Square-Signature` header to ensure they are genuinely from Square.

 

• Avoid hardcoding sensitive information such as API keys and tokens; use secure environment variables instead.