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

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

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

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