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')