pin_up

A Ruby gem wrapper for the pin-payments (pin.net.au) API, all of it.

Support for Ruby 1.9.x & Ruby 2.0.0

Build Status

Installation

gem install pin_up

or add:

gem 'pin_up'

to your Gemfile.

Usage

If using rails add an initializer to your app:

Pin::Base.new("your key")

An option second paramater can be passed in to set the environment (:live or :test). The default is :live.

Charges

List All Charges
Pin::Charges.all

Show charges on a particular page:

Pin::Charges.all(6)

With Pagination:

Pin::Charges.all(6,true)
# request = Pin::Charges.all(6,true)
# request[:response] => response hash
# request[:pagination] => "pagination":{"current":6,"previous":5,"next":7,"per_page":25,"pages":1,"count":15}
Find A Charge
Pin::Charges.find("token")
Search For A Charge
Pin::Charges.search({query: "foo", end_date: "Mar 25, 2013"})

See https://pin.net.au/docs/api/charges#search-charges for a full list of options.

Create A Charge
charge = {email: "[email protected]", description: "Description", amount: "400", currency: "AUD", ip_address: "127.0.0.1", customer_token: "cus_token"   }

Pin::Charges.create(charge)

Customers

List All Customers
Pin::Customer.all

Show customers on a particular page:

Pin::Customer.all(3)

With Pagination:

Pin::Customer.all(3,true)
Find A Customer
Pin::Customer.find('token')
List Charges For A Customer
Pin::Customer.charges('cus_token')

Show customers on a particular page:

Pin::Customer.charges(6)

With Pagination:

Pin::Customer.all(6,true)
# request = Pin::Customer.all(6,true)
# request[:response] => response hash
# request[:pagination] => "pagination":{"current":6,"previous":5,"next":7,"per_page":25,"pages":1,"count":15}
Create A Customer
Pin::Customer.create(email, hash_of_customer_details)

customer_details = {number: '5520000000000000', expiry_month: "12", expiry_year: "2014", cvc: "123", name: 'Roland Robot', address_line1: '123 fake street', address_city: 'Melbourne', address_postcode: '1234', address_state: 'Vic', address_country: 'Australia'}

Pin::Customer.create('[email protected]', customer_details)
Update A Customer
Update Card details
Pin::Customer.update('cus_token', hash_of_details)

If passing a hash of details, it must be the full list of details of the credit card to be stored. (https://pin.net.au/docs/api/customers#put-customer)

Update only an email
hash_of_details = {email: '[email protected]'}
Pin::Customer.update('cus_token', hash_of_details)
Update card by token
hash_of_details = {card_token: 'new_card_token'}
Pin::Customer.update('cus_token', hash_of_details)
Creat A Customer Given a Card Token and Email
card_details = {number: "5520000000000000", expiry_month: "12", expiry_year: "2018", cvc: "123", name: "Roland TestRobot", address_line1: "123 Fake Road", address_line2: "", address_city: "Melbourne", address_postcode: "1223", address_state: "Vic", address_country: "AU"}

card = Pin::Card.create(card_details)
Pin::Customer.create('[email protected]',card['token'])

Refunds

Find A Refund
Pin::Refund.find('charge_token')

This will list all refunds for a particular charge (will return an empty hash if nothing is found)

Create A Refund Specifying An Amount
Pin::Refund.create('charge_token', '400')
Create A Refund For Entire Charge Amount
Pin::Refund.create('charge_token')

Cards

Create A Card Without Pins Form
card_details = {number: "5520000000000000", expiry_month: "12", expiry_year: "2018", cvc: "123", name: "Roland Robot", address_line1: "123 Fake Road", address_line2: "", address_city: "Melbourne", address_postcode: "1223", address_state: "Vic", address_country: "AU"}

Pin::Card.create(card_details)

Will return a card_token that can be stored against a customer.

Only use this method if you're comfortable sending card details to your server - otherwise you can use a form that Pin provides (https://pin.net.au/docs/guides/payment-forms) and get the card_token that way.

Receipts

One of the things I've found lacking with Pin is the ability to generate a receipt for a sale. So I've added this functionality into pin_up.

At the moment basic receipt creation from a succesful charge is supported, however, I'd like to build out this feature and include failed transactions and refunds.

There are two ways to go about creating and viewing / sharing a receipt.

Rendering a receipt as HTML

Basic Usage:

The following will return a HTML receipt for you to do with as you wish.

@charge = Pin::Charges.find("token")
@company_details = ["ABC Widgets","123 Fake Street Melbourne","VIC 3000","ABN: 12 345 678 910"]
@receipt = Pin::Receipt.new(@charge, @company_details)
@receipt.render()

Your "comapny_details" can be replaced with whatever information you wish to be displayed at the top right hand side (see tmp/receipt.html).

Advanced Usage:

There are four additional options that can be passed to Pin::Receipt.new.

The first is the path to your logo should you wish to include it in the footer.

The second is some additional payment information you might want to add (such as tax, fee or discount information). This can be done by passing a hash in as argument 4 eg:

payment_options = {}
payment_options["fee"] = {"name" => "late fee", "amount" => "$10.00"}
payment_options["tax"] = {"name" => "GST", "amount" => "$10.00"}
payment_options["discount"] = {"name" => "Member Discount", "amount" => "$10.00"}

A path to a custom receipt template can be passed in as the 5th argument, while a path that you would like the receipt to be saved to can be passed in as the 6th argument.

Saving a receipt

To save a receipt it's exactky the same as above, just call save instead of render. By default, a receipt will be saved into tmp/receipt.html unless a path is specified.

If you would like a PDF receipt, you should be able to "print as PDF" from a browser dialog.

Custom receipt template

If you would like you can use a custom receipt template to suit your branding or design needs. To get an idea of which variables are available, take a look at /views/receit.html.erb

Testing localy

Create a YAML file under 'spec' called 'test_data.yml' and add in:

PIN_SECRET: "your pin test secret"

uncomment line 13 in spec_helper.rb and

run

rspec spec/*.rb

To do

  • Flesh out receipts - handle failed transactions and refunds
  • Validate a response before it gets sent to Pin (eg. Update customer)

Contributing to pin_up

  • Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
  • Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
  • Fork the project.
  • Start a feature/bugfix branch.
  • Commit and push until you are happy with your contribution.
  • Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
  • Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Copyright (c) 2013 Daniel Nitsikopoulos. See LICENSE.txt for further details.