Zipmark Ruby Client
The Zipmark Ruby Client library is used to interact with Zipmark's API.
Installation
gem install zipmark
or in your Gemfile
gem "zipmark"
Instantiating a client
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.
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
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.
client.resources.keys
Creating a new Bill
Create a bill object, set required attributes, send it to Zipmark
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
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:
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:
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).
# 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 or contact Zipmark Support via email or chat 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
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')