pr-pin

PR::Pin

Installation

Add this line to your application's Gemfile:

gem 'pr-pin'

And then execute:

$ bundle

Or install it yourself as:

$ gem install pr-pin

Usage

Registering Connections

# Require the gem
require 'pr-pin'

# Register a connection using your Pin Payments secret key
PR::Pin.register_connection(
  secret_key: 'your_secret_key',
  # raise on error, defaults to returning PR::Pin::API::Error instance
  error_handler: ->(exception) { raise(exception) },
  sandbox: true # Defaults to true, false for production
)

# You can register another connection by passsing an identifier to
# PR::Pin.register_connection, i.e.
PR::Pin.register_connection(
  :admin, # defaults to :default
  secret_key: 'your_secret_key',
  sandbox: true
)

# Then, you can specify the connection to use when resolving the
# endpoint repository from the PR::Pin container
customers = PR::Pin.customers(:admin).list(page: 1)
# => [#<PR::Pin::Struct::Customer>, ...]
customers.current_page # => 1
customers.per_page # => 25
customers.prev_page # => nil
customers.next_page # => 2
customers.total_count # => 53
customers.total_pages # => 3

One-off charge

# Create a charge using a token, you can get a card token
# using Pin Payments hosted fields, or by creating a card
# via the API, this can be used to take a one-off payment
charge = PR::Pin.charges.create(
  email: '[e-mail]',
  description: 'A $10 donation',
  amount: 1000,
  ip_address: '127.0.0.1',
  card_token: 'card_58b6c52f131956c4394ba7'
)
charge.success? # => true
charge.error? # => false
charge # => #<PR::Pin::Struct::Charge>

# Find a charge by token
PR::Pin.charges.find('ch_1ee2d1')
# => #<PR::Pin::Struct::Charge>

Recurring payments

# For a subscription, create a customer using a card token
customer = PR::Pin.customers.create(
  email: '[e-mail]',
  card_token: 'card_58b6c52f131956c4394ba7'
)
customer.success? # => true
customer.error? # => false
customer # => #<PR::Pin::Struct::Customer>

# And then attach a subscription using the plan token from
# the plans endpoint (you will need to create the plan first)
subscription = PR::Pin.subscriptions.create(
  plan_token: 'plan_2d16b31863015a57820b70',
  customer_token: 'cus_9d18a4516a6ae777-NDecB'
)
subscription.success? # => true
subscription.error? # => false
subscription # => #<PR::Pin::Struct::Subscription>

ledger = PR::Pin.ledger.for_subscription('sub_293857')
subscription.success? # => true
subscription.error? # => false
ledger
# => [
#   #<PR::Pin::Struct::Ledger type="credit" annotation="charge_credit" amount=1026 currency="AUD" created_at=#<DateTime: 2020-07-02T02:19:50+00:00 ((2459033j,8390s,0n),+0s,2299161j)>>,
#   #<PR::Pin::Struct::Ledger type="debit" annotation="interval_fee" amount=1026 currency="AUD" created_at=#<DateTime: 2020-07-02T02:19:47+00:00 ((2459033j,8387s,0n),+0s,2299161j)>>,
#   #<PR::Pin::Struct::Ledger type="debit" annotation="setup_fee" amount=0 currency="AUD" created_at=#<DateTime: 2020-07-02T02:19:47+00:00 ((2459033j,8387s,0n),+0s,2299161j)>>
# ]

Refunds

# List refunds (paginated)
refunds = PR::Pin.refunds.list
# => [#<PR::Pin::Struct::Refund>, ...]

# Find a specific refund
refund = PR::Pin.refunds.find('rf_1e5429')
# => #<PR::Pin::Struct::Refund>

# Create a refund for a charge
PR::Pin.refunds.create_for_charge('ch_1ee2d1')
# => #<PR::Pin::Struct::Refund>

# List all refunds by charge
PR::Pin.refunds.for_charge('ch_1ee2d1')
# => [#<PR::Pin::Struct::Refund>, ...]

Errors - See PR::Pin::API::Error

charge = PR::Pin.charges.create(
  email: '[e-mail]'
)
charge.success? # => false
charge.error? # => true
charge.code # => "invalid_resource"
charge.description # => "One or more parameters were missing or invalid"
charge # => => #<PR::Pin::API::Error>

API Coverage

Coverage of https://pinpayments.com/developers/api-reference

Relation	Endpoint	Description	Docs	Implemented
Balance	GET /balance	Returns the current balance of your Pin Payments account	:link:	:x:
Bank Accounts	POST /bank_accounts	Creates a bank account token	:link:	:x:
Cards	POST /cards	Securely stores a card's details	:link:	:x:
Charges	POST /charges	Creates a new charge	:link:	:heavy_check_mark:
Charges	PUT /charges/#{charge-token}/capture	Captures a previously authorised charge	:link:	:x:
Charges	GET /charges	Returns a paginated list of all charges	:link:	:heavy_check_mark:
Charges	GET /charges/search	Returns a paginated list of charges matching the search criteria	:link:	:heavy_check_mark:
Charges	GET /charges/#{charge-token}	Returns the details of a charge	:link:	:heavy_check_mark:
Customers	POST /customers	Creates a new customer	:link:	:heavy_check_mark:
Customers	GET /customers	Returns a paginated list of all customers	:link:	:heavy_check_mark:
Customers	GET /customers/#{customer-token}	Returns the details of a customer	:link:	:heavy_check_mark:
Customers	PUT /customers/#{customer-token}	Updates the details of a customer	:link:	:heavy_check_mark:
Customers	DELETE /customers/#{customer-token}	Deletes a customer and all of its cards	:link:	:x:
Customers	GET /customers/#{customer-token}/charges	Returns a paginated list of a customer's charges	:link:	:heavy_check_mark:
Customers	GET /customers/#{customer-token}/cards	Returns a paginated list of a customer's cards	:link:	:x:
Customers	POST /customers/#{customer-token}/cards	Creates an additional card for the specified customer	:link:	:x:
Customers	DELETE /customers/#{customer-token}/cards/#{card-token}	Deletes a customer's non-primary card	:link:	:x:
Customers	GET /customers/#{customer-token}/subscriptions	Retrieves the specified customer's subscriptions	:link:	:x:
Events	GET /events	Returns a paginated list of all events	:link:	:x:
Events	GET /events/#{event-token}	Returns the details of the specified event	:link:	:x:
Plans	POST /plans	Creates a new plan	:link:	:heavy_check_mark:
Plans	GET /plans	Returns a paginated list of all plans	:link:	:heavy_check_mark:
Plans	GET /plans/#{plan-token}	Returns the details of a specified plan	:link:	:heavy_check_mark:
Plans	PUT /plans/#{plan-token}	Update the specified plan	:link:	:heavy_check_mark:
Plans	DELETE /plans/#{plan-token}	Deletes a plan and all of its subscriptions	:link:	:x:
Plans	POST /plans/#{plan-token}/subscriptions	Creates a new subscription to the specified plan	:link:	:x:
Plans	GET /plans/#{plan-token}/subscriptions	Returns a paginated list of subscriptions for a plan	:link:	:x:
Subscriptions	POST /subscriptions	Activate a new subscription and returns its details	:link:	:heavy_check_mark:
Subscriptions	GET /subscriptions	Returns a paginated list of all subscriptions	:link:	:heavy_check_mark:
Subscriptions	GET /subscriptions/#{sub-token}	Returns the details of the subscription identified by subscription token	:link:	:heavy_check_mark:
Subscriptions	PUT /subscriptions/#{sub-token}	Updates the card associated with a subscription identified by subscription token	:link:	:heavy_check_mark:
Subscriptions	DELETE /subscriptions/#{sub-token}	Cancels the subscription identified by subscription token	:link:	:x:
Subscriptions	PUT /subscriptions/#{sub-token}/reactivate	Reactivates the subscription identified by subscription token	:link:	:x:
Subscriptions	GET /subscriptions/#{sub-token}/ledger	Fetch the ledger entries relating to a subscription identified by subscription token	:link:	:heavy_check_mark:
Recipients	POST /recipients	Creates a new recipient	:link:	:x:
Recipients	GET /recipients	Returns a paginated list of all recipients	:link:	:x:
Recipients	GET /recipients/#{recipient-token}	Returns the details of a recipient	:link:	:x:
Recipients	PUT /recipients/#{recipient-token}	Updates the details of a recipient	:link:	:x:
Recipients	GET /recipients/#{recipient-token}/transfers	Returns a paginated list of a recipient's transfers	:link:	:x:
Refunds	GET /refunds	Returns a paginated list of all refunds	:link:	:heavy_check_mark:
Refunds	GET /refunds/#{refund-token}	Returns the details of the specified refund	:link:	:heavy_check_mark:
Refunds	POST /charges/#{charge-token}/refunds	Creates a new refund and returns its details	:link:	:heavy_check_mark:
Refunds	GET /charges/#{charge-token}/refunds	Returns a list of all refunds for the specified charge	:link:	:heavy_check_mark:
Transfers	POST /transfers	Creates a new transfer	:link:	:x:
Transfers	GET /transfers	Returns a paginated list of all transfers	:link:	:x:
Transfers	GET /transfers/search	Returns a paginated list of transfers matching the search criteria	:link:	:x:
Transfers	GET /transfers/#{transfer-token}	Returns the details of the specified transfer	:link:	:x:
Transfers	GET /transfers/#{transfer-token}/line_items	Returns a paginated list of line items associated with the specified transfer	:link:	:x:
Webhook Endpoints	POST /webhook_endpoints	Creates a new webhook endpoint	:link:	:x:
Webhook Endpoints	GET /webhook_endpoints	Returns a paginated list of all webhook endpoints	:link:	:x:
Webhook Endpoints	GET /webhook_endpoints/#{webhook-endpoint-token}	Returns the details of the specified webhook endpoint	:link:	:x:
Webhook Endpoints	DELETE /webhook_endpoints/#{webhook-endpoint-token}	Deletes a webhook endpoint and all of its webhook requests	:link:	:x:
Webhooks	GET /webhooks	Returns a paginated list of all webhooks	:link:	:x:
Webhooks	GET /webhooks/#{webhook-token}	Returns the details of a webhook	:link:	:x:
Webhooks	PUT /webhooks/#{webhook-token}/replay	Replays a webhook	:link:	:x:

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/PetRescue/pr-pin.

License

The gem is available as open source under the terms of the MIT License.