EasyPing
EasyPing is an out of the box Ping++ Ruby SDK. Once installed, you're ready to set up a minimal configuration and get started using EasyPing.
Note It's released on RubyGems. If something doesn't work, feel free to report a bug or start an issue.
Installation
Add this line to your application's Gemfile:
gem 'easy_ping'
And then execute:
$ bundle
Or install it yourself as:
$ gem install easy_ping
If you prefer to use the latest code, you can build from source:
gem build easy_ping.gemspec
gem install easy_ping-<VERSION>.gem
Configuration
Write these lines of code to your configuration file, for example, easy_ping.rb
.
EasyPing.configure do |config|
config.app_id = 'app_Wzrrb9DW1GaLmbjn' # required
config.api_key = 'sk_test_Dq54mDyHufz9nrPeH8Hm50G8' # required
config.channel = :alipay # optional, default: :alipay, you can modify this option on runtime
end
And put it under config/initiailizers
directory of your Rails project.
Or require this file manually by yourself.
Usage
## Create Charge ##
# Class Method Definitions : Charge Create
EasyPing::Charge.create(order_number, amount, subject, body, options={}) -> charge object
EasyPing::Charge.create(options) -> charge object
# Alias Methods
EasyPing::Charge.create
EasyPing.charge
# Examples
charge = EasyPing::Charge.create 'order_number_1', 100, 'apple', 'one delicous big apple'
charge = EasyPing.charge({
order_number: 'order_number_2',
amount: 100,
subject: 'apple',
body: 'one delicous big apple',
app_id: 'app_Wzrrb9DW1GaLmbjn',
metadata: { color: 'red'},
})
# Returned Charge Object
charge.raw # raw response body, typically json string
charge.values # parsed response body, hash
charge.heasers # response headers
charge.status # response status, http code
charge.live? # livemode or not
charge.amount # attributes defined on Ping++ API
charge.livemode
charge.refunded
## Retrieve Single Charge ##
# Class Method Definitions : Charge Find
EasyPing::Charge.find(charge_id) -> charge object
EasyPing::Charge.find(charge_id: charge_id) -> charge object
# Alias Methods
EasyPing::Charge.find
EasyPing.find
EasyPing.find_charge
# Examples
charge = EasyPing::Charge.find 'ch_8OG4WDTe10q1q5G8aL8aDSmH'
charge = EasyPing.find charge_id: 'ch_8OG4WDTe10q1q5G8aL8aDSmH'
## Retrieve Charge List ##
# Class Method Definitions : Charge ALL
EasyPing::Charge.all(options={}) -> charge object list
# Alias Methods
EasyPing::Charge.all
EasyPing.all
EasyPing.all_charges
EasyPing.get_charge_list
# Examples
charges = EasyPing::Charge.all
charges = EasyPing.all {
limit: 10,
offset: 'ch_8OG4WDTe10q1q5G8aL8aDSmH', # offset & starting_after, synonym
paid: true,
refunded: false
}
# Instance Method Definitions : Charge Pagination
charges.get_next_page(options={}) -> charge object list
# Similar Methods
charges.get_next_page
charges.get_next_page! # change charges itself
charges.get_prev_page
charges.get_prev_page! # same above
# Examples
new_charges = charges.get_next_page # note: ending_before option will be omitted
charges.get_prev_page!(limit: 5) # note: starting_after option will be omitted
# Returned Charge List Object
charges.has_more?
charges.url
charges.each {|ch| puts ch.id }
## Create Refund ##
# Class Method Definitions : Refund Create
EasyPing::Refund.create(description, charge_id) -> refund object
EasyPing::Refund.create(amount, description, charge_id) -> refund object
EasyPing::Refund.create(options) -> refund object
# Alias Methods
EasyPing::Refund.create
EasyPing.refund
# Examples
EasyPing::Refund.create 'refund description', 'ch_0ijQi5LKqT5sEiOePOKWb1mF'
EasyPing.refund({
amount: 50,
description: 'refund description',
charge_id: 'ch_0ijQi5LKqT5sEiOePOKWb1mF'
})
# Instance Method Definitions : Refund Create
charge.refund(amount description) -> refund object
charge.refund(description) -> refund object
charge.refund(options) -> refund object
# Examples
charge = EasyPing::Charge.find 'ch_0ijQi5LKqT5sEiOePOKWb1mF'
refund = charge.refund 10, 'refund description'
# Returned Refund Object
refund.raw # raw response body, typically json string
refund.values # parsed response body, hash
refund.heasers # response headers
refund.status # response status, http code
refund.live? # livemode or not
refund.amount # attributes defined on Ping++ API
refund.description
## Retrieve Single Refund ##
# Class Method Definitions : Refund Find
EasyPing::Refund.find(charge_id, refund_id) -> refund object
EasyPing::Refund.find(options) -> refund object
# Alias Methods
EasyPing::Refund.find
EasyPing.find
EasyPing.find_refund
# Special Note:
# Must provide both charge_id and refund_id,
# if only charge_id provided, it will retrieve a charge object
# Examples
refund = EasyPing::Refund.find 'ch_0ijQi5LKqT5sEiOePOKWb1mF', 're_TmbvDKHiXLCSG0mnj9jnDyjA'
refund = EasyPing.find_refund charge_id: 'ch_0ijQi5LKqT5sEiOePOKWb1mF', refund_id: 're_TmbvDKHiXLCSG0mnj9jnDyjA'
## Retrieve Refund List ##
# Class Method Definitions : Refund All
EasyPing::Refund.all(charge_id, options={}) -> refund object list
EasyPing::Refund.all(options) -> refund object list
# Alias Methods
EasyPing::Refund.all
EasyPing.all_refund
EasyPing.all_refunds # in case of plural format typo
EasyPing.get_refund_list
# Examples
refund_list = EasyPing::Refund.all 'ch_0ijQi5LKqT5sEiOePOKWb1mF', { limit: 5 }
refund_list = EasyPing.all_refund charge_id: 'ch_0ijQi5LKqT5sEiOePOKWb1mF'
# Instance Method Definitions : Refund All
charge.all_refund(options={}) -> refund object list
# Alias Methods
charge.all_refund
charge.all_refunds # in case of typo
charge.get_refund_list
# Examples
charge = EasyPing::Charge.find 'ch_0ijQi5LKqT5sEiOePOKWb1mF'
refund_list = charge.all_refund limit: 5
# Returned Refund List Object
refund_list.has_more?
refund_list.url
refund_list.each {|re| puts re.id }
Retrieve charge or refund object from async notification is easy. EasyPing will automatically detect whether response object is charge or refund.
## Retrieve from Async Notification ##
# Class Method Definitions : Async Notification
EasyPing.from_notification(params) -> charge/refund object
# Alias Methods
EasyPing::Charge.from_notification(params)
EasyPing::Refund.from_notification(params)
# Special Note:
# 1. params can a JSON string or a decoded hash object
# 2. it will automatically detect charge/refund object
# no matter which method you call
# Examples
charge = EasyPing::Charge.from_notification(params)
refund = EasyPing::Refund.from_notification(params)
Advanced Usage
## Runtime Setup ##
# Using different configuration from pre-setup options
ping = EasyPing.new({
app_id: 'app_Wzrrb9DW1GaLmbjn',
api_key: 'sk_test_Dq54mDyHufz9nrPeH8Hm50G8',
channel: :wx
})
# do whatever you want without change of default configuration
ping.charge 'order_number_3' 100, 'apple', 'one delicous big apple'
## Config ##
config = EasyPing.config
config.api_key
config.app_id
config.to_options # return config in hash format
EasyPing.config # return default config
ping = EasyPing.new({
app_id: 'app_Wzrrb9DW1GaLmbjn',
api_key: 'sk_test_Dq54mDyHufz9nrPeH8Hm50G8',
})
ping.config # return config for this ping instance
## Available Channels ##
["alipay", "wx", "upmp", "alipay_wap", "upmp_wap"]
Error Handling
If fail to create or retrieve charge/refund, an error will be raised.
## Error ##
begin
charge = EasyPing::Charge.find 'ch_0ijQi5LKqT5sEiOePOKWb1mF'
rescue EasyPing::APIError => e # Error return by server
puts e.message
puts e.status
puts e.type
puts e.param
rescue EasyPing::Error => e # Top level error of EasyPing
puts e.message
rescue Exception => boom
puts "something wrong with your code, #{boom.message}"
puts boom.backtrace.join("\n")
end
Others
For Ping++ API information, please visit https://pingplusplus.com/document/api