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: '[email protected]',
  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: '[email protected]',
  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: '[email protected]'
)
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.