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.
