https://github.com/zipmark/zipmark-ruby
Official Ruby Client for the Zipmark API
https://github.com/zipmark/zipmark-ruby
Last synced: 11 months ago
JSON representation
Official Ruby Client for the Zipmark API
- Host: GitHub
- URL: https://github.com/zipmark/zipmark-ruby
- Owner: zipmark
- License: mit
- Created: 2012-11-01T06:03:57.000Z (over 13 years ago)
- Default Branch: master
- Last Pushed: 2015-07-10T21:50:37.000Z (almost 11 years ago)
- Last Synced: 2025-06-01T15:06:01.112Z (11 months ago)
- Language: Ruby
- Size: 437 KB
- Stars: 1
- Watchers: 7
- Forks: 3
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://travis-ci.org/zipmark/zipmark-ruby)
[](https://gemnasium.com/zipmark/zipmark-ruby)
[](https://codeclimate.com/github/zipmark/zipmark-ruby)
# Zipmark Ruby Client
The Zipmark Ruby Client library is used to interact with Zipmark's [API](https://dev.zipmark.com).
## Installation
```sh
gem install zipmark
```
or in your Gemfile
```ruby
gem "zipmark"
```
### Instantiating a client
```ruby
require 'zipmark'
client = Zipmark::Client.new(
:application_id => "app-id",
:application_secret => "my-secret",
:vendor_identifier => "vendor-ident"
)
```
Vendor Identifier, Application Identifier, Application Secret should be replaced with the
values provided by Zipmark.
### Production Mode
By default, Zipmark::Client sends all requests to our sandbox environment. This environment is identical to production except money never actually is moved. When you are putting your application into production and want people to actually be able to pay, you need to turn production mode on.
```ruby
client = Zipmark::Client.new(
:application_id => "app-id",
:application_secret => "my-secret",
:vendor_identifier => "vendor-ident",
:production => true
)
```
### Loading a Bill from a known Bill ID
```ruby
client.bills.find("bill-id")
```
Attempting to find a bill that doesn't exist will raise a Zipmark::NotFound error.
### Discovering available resources
Resources will contain an array of all available resources.
```ruby
client.resources.keys
```
### Creating a new Bill
Create a bill object, set required attributes, send it to Zipmark
```ruby
bill = client.bills.create(
:identifier => "1234",
:amount_cents => 100,
:bill_template_id => bill_template_id,
:memo => "My memo",
:content => '{"memo":"My Memo"}',
:customer_id => "Customer 1",
:date => "20130805")
```
As an alternative, it is possible to build an object first and then save it afterwards
```ruby
bill = client.bills.build(
:identifier => "1234",
:amount_cents => 100,
:bill_template_id => bill_template_id,
:memo => "My memo",
:content => '{"memo":"My Memo"}',
:customer_id => "Customer 1",
:date => "20130805")
bill.save
```
Regardless of which method is used, if a bill is valid, it was successfully saved to Zipmark:
```ruby
puts bill.errors unless bill.valid?
```
### Updating an existing Bill
Get the bill, make a change, send it back to Zipmark
### Retrieving a list of all Bills
Retrieve a list of all bills.
Get the number of objects available.
### Basic Iterator
The Zipmark_Iterator class understands Zipmark's pagination system. It loads one page of objects at a time and will retrieve more objects as necessary while iterating through the objects.
Get the current object (returns null if the iterator has passed either end of the list)
Get the next/previous object (returns null if the next/previous object would pass either end of the list)
### Iterating through a list of all Bills
The Zipmark_Iterator can be used to iterate through all objects of a given resource type.
### Callback processing
The client is able to process, verify and extract data from callbacks received from the Zipmark service.
#### Setting up a Callback
Callbacks have to be enabled by creating a callback with an event type and the callback URL. To enable Zipmark to send a callback:
```ruby
callback = client.callbacks.create(
:url => 'https://example.com/callback',
:event => 'name_of_event')
```
The possible event names include:
* bill.create
* bill.update
* bill_payment.create
* bill_payment.update
#### Loading a callback response
#### Verifying a callback
To verify a callback, you need the entire request (headers, request body, etc.) so it has to be done from the context of the controller layer (or a model that is passed the entire request).
```ruby
# In a controller:
client.build_callback(request).valid?
```
Will return true or false, based on a signed header from Zipmark.
#### Retrieving the callback data
Valid callbacks contain events, object types and objects. The below functions will return their respective values/objects, or null if the callback is invalid.
## API Documentation
Please see the [Zipmark API](https://dev.zipmark.com) or contact Zipmark Support via [email](mailto:developers@zipmark.com) or [chat](http://bit.ly/zipmarkAPIchat) for more information.
## Unit/Acceptance Tests
Tests are written in rspec. To run the full test suite, execute the following:
```
bundle install
bundle exec rake spec
```
#### Creating a Token
For a Workflow
```
workflow = client.workflow.create(name: 'enrollment', data: { customer_id: 'some unique permanent id' })
workflow.token
```
For a Display
```
display = client.display.create(name: 'recent-transaction', data: { customer_id: 'some unique permanet id' })
display.token
```
#### Deposits Resource
**Get deposits**
`client.get('deposits')`
**Get a specific deposit**
`client.get('deposits/DEPOSIT_ID')`
**Cancel a deposit**
`client.put('deposits/DEPOSIT_ID/cancel', '')`
**Make a Depost**
```ruby
body = { :deposit => { :customer_identifier => 'their unique and permanent identifier', :amount_cents => 1000, :memo => 'an example memo' } }
client.post('deposits', body)
```
#### Customers Resource
**Get Customers**
`client.get('customers')`
**Get a specific customer**
`client.get('customers/CUSTOMER_ID')`
#### Accounts Resource
**Get accounts**
`client.get('accounts')`
**Get a specific account**
`client.get('accounts/ACCOUNT_ID')`