A Ruby library for interacting with v1 of the Pin Payments API.

Installation

Add this line to your application's Gemfile:

gem 'pin-ruby'

And then execute:

$ bundle

Or install it yourself as:

$ gem install pin-ruby

Configuration

Rails application

The Pin library includes a generator to create a config file and initializer for you:

$ rails g pin:install --publishable-key your_key_here --secret-key your_secret_here

The generator adds two files for your rails project:

config/pin.yml
config/initializers/pin.rb

Customise the config/pin.yml config file if you wish to use different publishable keys per environment (by default it uses the same token in development, test and production).

The Pin library is configured during rails initialization using the generated files, and no further configuration is necessary before use.

Non-rails application

When using the Pin library in a non-rails application, you must configure it to use your Pin publishable key manually:

Pin.configure do |config|
    config.publishable_key = 'YOUR_PUBLISHABLE_KEY'
    config.secret_key = 'YOUR_SECRET_KEY'
    config.endpoint = 'api.pin.net.au'
end

Usage

require 'pin/api'

client = Pin::API::Client.new()

Charges

List Charges

Return a paginated list of Pin::Models::Charge objects:

client.charges()

Optionally pass the page parameter to specify a different page of results:

client.charges(2)

Will get the second page of charges.

Fetch Charge

Get a specific customer by their token:

client.charge('ch_1234')

Returns a Pin::Models::Charge object, or raises a Pin::Error:

HTTP Error 404: not_found

Search charges

Search for charges by description, amount and date, as per Pin's Documentation:

client.charge_search({:query => 'Test Transaction'})

Returns a paginated list of Pin::Models::Charges.

Create Charge

Charges a customer or card, and returns the newly created charge object:

client.create_charge('[email protected]', 'Test Transaction', '1295', 'AUD', request.remote_ip, 'cus_1234')

The last parameter (token_or_card) can be either a customer token, a card token or a card hash.

Returns a Pin::Models::Charge of the charge, or a Pin::Error, as per Pin's Documentation.

Customers

List Customers

Return a paginated list of Pin::Models::Customer objects:

client.customers()

Optionally pass the page parameter to specify a different page of results:

client.customers(2)

Will get the second page of customers.

Fetch customer

Get a specific customer by their token:

client.customer('cus_1234')

Returns a Pin::Models::Customer object, or raises a Pin::Error:

HTTP Error 404: not_found

Customer's charges

Gets a paginated list of charges against a customer:

client.customer_charges('cus_1234')

Optionally pass a second parameter page to specify a different page of results:

client.customer_charges('cus_1234', 2)

Returns a list of Pin::Models::Charge object, or raises a Pin::Error:

HTTP Error 404: not_found

Create Customer

Create a new customer with either an existing card token, or a hash of card details):

client.create_customer('[email protected]', 'card_1234')

client.create_customer('[email protected]', {:number => '5520000000000000', ... })

Card hash should be supplied as per Pin's documentation:

{
  "token": "card_nytGw7koRg23EEp9NTmz9w",
  "display_number": "XXXX-XXXX-XXXX-0000",
  "scheme": "master",
  "address_line1": "42 Sevenoaks St",
  "address_line2": null,
  "address_city": "Lathlain",
  "address_postcode": "6454",
  "address_state": "WA",
  "address_country": "Australia"
}

Returns the newly created customer as a Pin::Models::Customer object.

Update customer

Update's a customer's card and/or email address:

client.update_customer('cus_1234', {:email => '[email protected]', :card => {:number => '5520000000000000', ... } })

Returns the updated customer as a Pin::Models::Customer object.

Refunds

List Refunds

Return a paginated list of Pin::Models::Refund objects for the specified charge token:

client.refunds('ch_1234')

Optionally pass the page parameter to specify a different page of results:

client.refunds('ch_1234', 2)

Will get the second page of refunds for the specified charge.

Refund a charge

Refunds the specified amount against an existing charge, and returns the refund object created, or a Pin::Error:

client.create_refund('ch_1234')

By default create_refund refunds the full amount of the original charge. To specify a different amount, pass the amount as cents to the optional second parameter:

client.create_refund('ch_1234', '1000')

Returns the refund object created, or a Pin::Error.

Tokens

Create a token for a card

Takes a card and stores it returning a reusable token for charges.

client.create_token('5520000000000000', '01', '2015', '123', 'John Appleseed', {
    :line1 => '1 Main Street', 
    :city => 'Melbourne', 
    :postcode => '3000', 
    :state => 'Victoria', 
    :country => 'Australia'
})

Returns a Pin::Models::Card containing the non-sensitive card details.

Contributing

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