Project

pin_pays

0.0
No commit activity in last 3 years
No release in over 3 years
pin_paysmlilley/pin_paysHomepageDocumentationSource CodeBug TrackerWiki
Provides an implementation of the Pin Payments API (pin.com.au) for Ruby and Rails projects
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Popularity
Downloads
5,919
Stars
0
Forks
0
Watchers
1
 Releases
Current version
0.3.0
Total releases
2
First release
2014-04-26
Latest release
2014-05-09
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2014-04-30
Reverse Dependencies
0

 Dependencies

Development

rake
~> 10.3
turn
~> 0.9
vcr
~> 2.9
webmock
~> 1.17

Runtime

httparty
~> 0.13
 Project Readme

pin_pays

Super simple implementation of the Pin Payments API (pin.com.au) for Ruby and Rails projects.

Installation

PinPays is available as a gem:

$ gem install pin_pays

Setup

Configure your secret-key and whether to use the test or live modes:

# config/initializers/pin_pay.rb (for rails)
PinPays.configure do |config|
  config.key  = "your-secret-key" # NB: use the right one for the mode!
  config.mode = :test             # or :live
end

TIP: If you're using Rails 4+, I recommend using your secrets.yml file for the secret key.

Usage

PinPays replicates the PinPayments documented API closely. To understand the requirements for method inputs or return values refer to the PinPayments documentation, then refer to Responses section below to see how PinPays transforms the API json responses before giving them to you.

Examples:

# create a customer
customer = PinPays::Customers:create('moo@cow.com', 'card_token_xyz')
customer[:token] # => 'cust_token_xyz'

# issue a charge
charge = PinPays::Charges:create({ customer_token: customer[:token], email: 'moo@cow.com', description: 'Pants', amount: 4995, remote_ip: '127.0.0.1'})
charge[:token] # => 'charge_token_789'

# pay a refund
refund = PinPays::Refunds.create(charge[:token], 2500)
refund[:token] # => 'refund_token_123'

Cards

Create a card (ref)
PinPays::Cards.create(card)

where card is a hash of the card details

Customers

Create a customer (ref)
PinPays::Customers.create(email, card)

where card is either a card_token (of a previously created card) or a hash of card details.

List all customers (ref)
PinPays::Customers.list(page=nil)

where page is the results page number to return (optional)

Retrieve details of a specific customer (ref)
PinPays::Customers.show(customer_token)
Update a customer's details (ref)
PinPays::Customers.update(customer_token, options)

where options is a hash of one or more of: email:, card_token:, or card: (hash of card details).

List all charges for a customer (ref)
PinPays::Customers.charges(customer_token, page=nil)

where page is the results page number to return (optional)

Charges

Create a charge (ref)
PinPays::Charges.create(options)

where options contains:

  • (mandatory) email:, description:, amount:, and remote_ip:
  • (mandatory, one of) customer_token:, card_token:, or card: (hash of card details)
  • (optional) currency:, and capture:
Capture a charge (ref)
PinPays::Charges.capture(charge_token)
List all charges (ref)
PinPays::Charges.list(page=nil)

where page is the results page number to return (optional)

Search for a charge that matches one or more criteria (ref)
PinPays::Charges.search(criteria)

where criteria is a hash containing one or more criteria to search for.

Show details of a specific charge (ref)
PinPays::Charges.show(charge_token)

Refunds

Create a refund (ref)
PinPays::Refunds.create(charge_token, amount=nil)

where amount is the amount in cents of the original charge to refund (optional, otherwise the entire amount).

List all refunds for a given charge (ref)
PinPays::Refunds.list(charge_token)

Responses

Success Responses

All successful calls return a hash. Fields of the hash are the same as those documented in PinPayments documentation (with some small convenience tweaks):

Non-paginated style responses have the parent "response" field omitted. For example, this:

{
  "response": {
    "token": "rf_ERCQy--Ay6o-NKGiUVcKKA",
    "success": null,
    "amount": 400,
    "currency": "USD",
    "charge": "ch_bZ3RhJnIUZ8HhfvH8CCvfA",
    "created_at": "2012-10-27T13:00:00Z",
    "error_message": null,
    "status_message": "Pending"
  }
}

becomes this:

{
  token: "rf_ERCQy--Ay6o-NKGiUVcKKA",
  success: null,
  amount: 400,
  currency: "USD",
  charge: "ch_bZ3RhJnIUZ8HhfvH8CCvfA",
  created_at: "2012-10-27T13:00:00Z",
  error_message: null,
  status_message: "Pending"
}

Note:

  • the parent "response" field is omitted
  • the hash keys are symbols (not strings)

Additionally, paginated style responses like this:

{
  "response": [
    {
      "token": "ch_lfUYEBK14zotCTykezJkfg",
      "success": true,
      "amount": 400,
      "currency": "USD",
      "description": "test charge",
      "email": "roland@pin.net.au",
      "ip_address": "203.192.1.172",
      "created_at": "2012-06-20T03:10:49Z",
      "status_message": "Success!",
      "error_message": null,
      "card": {
        "token": "card_nytGw7koRg23EEp9NTmz9w",
        "display_number": "XXXX-XXXX-XXXX-0000",
        "expiry_month": 6,
        "expiry_year": 2020,
        "name": "Roland Robot",
        "address_line1": "42 Sevenoaks St",
        "address_line2": null,
        "address_city": "Lathlain",
        "address_postcode": "6454",
        "address_state": "WA",
        "address_country": "Australia",
        "scheme": "master"
      },
      "captured": true,
      "authorisation_expired": false,
      "transfer": null,
      "settlement_currency": "AUD"
    }
  ],
  "pagination": {
    "current": 1,
    "per_page": 25,
    "count": 1
  }
}

Become this:

{
  items: [
    {
      token: "ch_lfUYEBK14zotCTykezJkfg",
      success: true,
      amount: 400,
      currency: "USD",
      description: "test charge",
      email: "roland@pin.net.au",
      ip_address: "203.192.1.172",
      created_at: "2012-06-20T03:10:49Z",
      status_message: "Success!",
      error_message: null,
      card: {
        token: "card_nytGw7koRg23EEp9NTmz9w",
        display_number: "XXXX-XXXX-XXXX-0000",
        expiry_month: 6,
        expiry_year: 2020,
        name: "Roland Robot",
        address_line1: "42 Sevenoaks St",
        address_line2: null,
        address_city: "Lathlain",
        address_postcode: "6454",
        address_state: "WA",
        address_country: "Australia",
        scheme: "master"
      },
      captured: true,
      authorisation_expired: false,
      transfer: null,
      settlement_currency: "AUD"
    }
  ],
  pages: {
    current: 1,
    per_page: 25,
    count: 1
  }
}

Note that:

  • the "response" field becomes "items"
  • the "pagination" field becomes "pages"

The only exception to the above is the PinPays::Refunds.list call, which returns only an array of hashes.

Error Responses

All error responses result in an Exception of the type PinPays::ApiError. The exception contains details about the specific error as properties on it:

...
rescue PinPays::ApiError => e
  e.error               # -> error code (ie: "insufficient_funds")
  e.error_description   # -> error description (ie: "There are not enough funds available to process the requested amount")
  e.charge_token        # -> of the failed charge (for charge-related api calls)
  e.messages            # -> an array of error messages (useful for displaying to the user on failed form submissions)
  e.raw_response        # -> the raw json api response as a ruby hash
end
...

For a list of possible error codes, and example responses see https://pin.net.au/docs/api/test-cards and the remainder of the PinPayments documentation pages.

License

Released under the MIT license.