nov / square

Square API Client

Square

Square API Client

https://connect.squareup.com

Installation

Add this line to your application's Gemfile:

gem 'square'

And then execute:

$ bundle

Or install it yourself as:

$ gem install square

Usage

OAuth 2.0

client = Square::OAuth2::Client.new(
  '<your-client-id>',
  '<your-client-secret>',
  redirect_uri: 'https://client.example.com/callback'
)

## Authorization Request
redirect_to client.authorization_uri

## Token Request
client.authorization_code = '<your-authorization-code>'
access_token = client.access_token!

Connect API

me = Square::Connect::Merchant.me access_token

## Merchant API
me = me.fetch

## Payments API
payments = me.payments

## Payment API
payment = me.payment '<payment-id>'

## Refunds API
refunds = me.refunds

## Settlements API
settlements = me.settlements

## Settlement API
settlement = me.settlement '<settlement-id>'

## Bank Account API
bank_account = me.bank_account '<bank-accout-id>'

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

square's Issues

Client requires a Redirect URL to use OAuth

hi guys when I tried to run the url that returns this code

client = Square::OAuth2::Client.new(
  '<your-client-id>',
  '<your-client-secret>',
  redirect_uri: 'https://client.example.com/callback'
)

I get the error

Client requires a Redirect URL to use OAuth

the url that I get is

https://squareup.com/oauth2/authorize?client_id=CLIENTID&redirect_uri=redirect_url&response_type=code

anyone knows why?

TODO: setup travis

Error processing payment with refunds?

I have tried everything I can think of, but whenever I ask for a payment that also happens to have a refund on it, I end up getting runtime errors. Other payments seem to be working fine.

def get_payment_from_api(squarePaymentID)
      # logger.debug "@me attributes hash: #{@me.inspect}"
      # logger.debug "the square payment id is: #{squarePaymentID}"
      # logger.debug "the id data type is: #{squarePaymentID.inspect}"
      @me.payment squarePaymentID
      # logger.debug "the request to the api was completed"
    end

Again, this code works for other individual payments.

Poor documentation, bad practices

Your documentation is creating problems in using your gem. Even worse, we have a developer learning the Rails framework who thinks it is terrible because his first experience has been chasing down problems in your code and documentation. Here are a few issues we have uncovered:

Your docs

client = Square::OAuth2::Client.new(
  '<your-client-id>',
  '<your-client-secret>',
  redirect_uri: 'https://example.client.com/callback'
)

This works with the Square API if you are mapped to localhost. However, when on Heroku (production) it does not work unless you remove the last argument.

Your docs

client.authorization_code = '<your-authorization-code>'
access_token = client.access_token!

This does not work without adding a symbol argument to the access_token! method call.

What actually worked

client.authorization_code = '<your-authorization-code>'
access_token = client.access_token! :client_auth_body

I am not sure if this is your gem not working, issues in the doc, or changes elsewhere. Either way, the documentation is so short and exclusive of useful information, we had to find this answer on stackoverflow questions about the Facebook gem.

Square API docs

Here is what Square shows as an example of what is returned from listing payments:

You will note that the id is called id. Instead, for some reason, you have chosen to call it identifier and not documented that anywhere.

Chasing down all of these little issues costs us time. Worse, these are all insanely easily avoidable with better documentation and respecting the convention to maintain naming conventions in API documentation.