Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Ruby client library for PoundPay
Ruby

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
examples/marketplace
lib
spec
.autotest
.gitignore
.gitmodules
.rspec
.rvmrc
Gemfile
README.rdoc
Rakefile
poundpay.gemspec

README.rdoc

Poundpay

Poundpay is a payments platform for marketplaces

Adding Poundpay to Rails

  1. Add the following to your Gemfile

    gem 'poundpay', '~> 0.3.1'
  2. At the command prompt, install the gem with bundler

    bundle install
  3. Create the file config/poundpay.yml and add your configurations. Note: Make sure your YAML file ends with a blank line; otherwise, Ruby will give you a completely unintelligible error message

    development:
      developer_sid: DV0383d447360511e0bbac00264a09ff3c
      auth_token: c31155b9f944d7aed204bdb2a253fef13b4fdcc6ae1540200449cc4526b2381a
      callback_url: http://staging.awesomemarketplace.com/payments/callback
      www_url: https://www-sandbox.poundpay.com
      api_url: https://api-sandbox.poundpay.com
    
    production:
      developer_sid: DV8dd93f0f3c6411e0863f00264a09ff3c
      auth_token: d8c4ea1bafd3fcac8c1062a72c22bcdb09321deb1041df257165cd6449def0de
      callback_url: http://www.awesomemarketplace.com/payments/callback
  4. Create the file config/initializers/poundpay.rb and add the following

    Poundpay.configure_from_yaml "config/poundpay.yml"
  5. Protect your callback controller

    before_filter :verify_poundpay_callback

Creating a user

@user = Poundpay::User.create(
  :first_name              => "Dart",
  :last_name               => "Master",
  :email_address           => "dart-master@example.com")

Creating a payment

@payment = Poundpay::Payment.create(
  :amount                  => 20000,
  :payer_fee_amount        => 0,
  :payer_email_address     => "fred@example.com",
  :recipient_fee_amount    => 500,
  :recipient_email_address => "david@example.com",
  :description             => "Beats by Dr. Dre")

Serving the payment IFRAME

<script src="https://www.poundpay.com/js/poundpay.js"></script>

<div id="pound-root"></div>

<script>
  function handlePaymentSuccess() {
    // do something
  }

  function handlePaymentError() {
    // handle error
  }

  PoundPay.init({
    payment_sid: "<%= @payment.sid %>",
    success: handlePaymentSuccess,
    error: handlePaymentError,
    name: "Fred Nietzsche", // Optional
    address_street: "330 Townsend St", // Optional
    address_city: "San Francisco", // Optional
    address_state: "California", // Optional
    address_zip: "94107", // Optional
    server: "<%= Poundpay.www_url %>"
  });
</script>

Payment methods

payment = Poundpay::Payment.find(payment_sid)
payment.escrow                    # AUTHORIZED -> ESCROWED.  Credit card is charged
payment.release                   # ESCROWED or PARTIALLY_RELEASED -> RELEASED.  Recipient receives money
payment.cancel                    # ESCROWED or PARTIALLY_RELEASED -> CANCELED.  Payer receives refund
Poundpay::Payment.batch_update    # Batch update a list of payments.

Creating a charge permission

@charge_permission = Poundpay::ChargePermission.create(
  :email_address           => "fred@example.com")

Serving the charge permission IFRAME

<script src="https://www.poundpay.com/js/poundpay.js"></script>

<div id="pound-root"></div>

<script>
  function handleChargePermissionSuccess() {
    // do something
  }

  function handleChargePermissionError() {
    // handle error
  }

  PoundPay.init({
    charge_permission_sid: "<%= @charge_permission.sid %>",
    success: handleChargePermissionSuccess,
    error: handleChargePermissionError,
    name: "Fred Nietzsche", // Optional
    address_street: "330 Townsend St", // Optional
    address_city: "San Francisco", // Optional
    address_state: "California", // Optional
    address_zip: "94107", // Optional
    server: "<%= Poundpay.www_url %>"
  });
</script>

Charge permission methods

charge_permission = Poundpay::ChargePermission.find(charge_permission_sid)
charge_permission.deactivate      # CREATED or ACTIVE -> INACTIVE. Charge permission is deactivated and can no longer be used to authorize payments for the associated payer.

Batching

In some cases you may wish to batch authorize and escrow a collection of payments. By doing so there will be only one payer charge for that collection of payments. Note that if you do batch authorize a collection of payments that it must also be batch escrowed.

Batching is designed for shopping carts where you want a collection of payments to appear to appear as a single charge.

In order to use batching you simply need to pass `sids` for all payments in the collection you want to batch to the IFrame

<script src="https://www.poundpay.com/js/poundpay.js"></script>

  <div id="pound-root"></div>

  <script>
    function handlePaymentSuccess() {
      // do something
    }

    function handlePaymentError() {
      // handle error
    }

    PoundPay.init({
      payment_sid: [
          "<%= @payment1.sid %>"
          "<%= @payment2.sid %>",
          "<%= @payment3.sid %>"
          ],
      success: handlePaymentSuccess,
      error: handlePaymentError,
      first_name: "Fred", // Optional
      last_name: "Nietzsche", // Optional
      address_street: "990 Guerrero St", // Optional
      address_city: "San Francisco", // Optional
      address_state: "California", // Optional
      address_zip: "94110", // Optional
      server: "https://www-sandbox.poundpay.com"  // Exclude for production
    });
  </script>

Alternatively if you are directly authorizing the payments using a charge permission

Poundpay::Payment.batch_update(
    :sid => [payment1.sid, payment2.sid, payment3.sid],
    :status => 'AUTHORIZED')

Finally you'll need to batch escrow the payments

Poundpay::Payment.batch_update(
    :sid => [payment1.sid, payment2.sid, payment3.sid],
    :status => 'ESCROWED')

Notice that if you did the following instead an error would be triggered since batched payments must be authorized and escrowed collectively

payment = Poundpay::Payment.find(payment1_sid)  
payment.escrow  # fails

However if you cancel some of the payments prior to batch escrow you should exclude them from the batch call

payment1 = Poundpay::Payment.find(payment1_sid)  
payment1.cancel  # ok

Poundpay::Payment.batch_update(
    :sid => [payment2.sid, payment3.sid],
    :status => 'ESCROWED')
Something went wrong with that request. Please try again.