atpay_buttons

@Pay Payment Button Generator

The @Pay payment button generator creates @Pay two-click buttons that you can send to your mailing list to collect funds via email.

When using two-click buttons in emails, you want to make sure that they are compatible in as many environments (clients/browsers/devices) as possible. This can be a painstaking task because all environments render buttons differently. Buttons generated with this tool are cross-platform and cross-browser compatible. This means that the two-click experience can be enjoyed on over 93% of browser, platform, and device combinations. The generator uses domain targeting and outputs html from a specific template depending on the email parameter. These templates include two sets of buttons. A CSS rule set will determine which button will be displayed on the end users device and browser. For more information on cross compatibility, visit https://www.atpay.com/cross-compatible-mailto-links-mobile-browsers.

You can use this library directly from your Ruby-based application, or you can interface with it via the command line from most any language.

The provided Liquid templates are customizable here, or can be used as a starting point for your own implementation.

This library is a convenience wrapper around the @Pay Client Library. You may use both together or each independently, though this library does internally depend on the client library.

Installation

If your application is based on Ruby and you use Bundler, add the following line to your application's Gemfile:

gem 'atpay_buttons'

And then execute:

$ bundle

If you'd like to use the command line interface, or are not using Bundler, you can install the gem on your system with:

$ gem install atpay_buttons

Requirements

Ruby >= 1.9

Command Line Usage

You'll need a partner id, public key and private key from your @Pay signup. More advanced implementations may be using OAuth to collect this information from multiple partners and can generate buttons on behalf of merchants that use their system.

After installing the atpay-button-generator gem, you'll have atpay_buttons script in your gem binpath. Run it with the help flag to get information on how to use it:

$ atpay_buttons --help

The button generator requires a few flags up front:

Parameters

amount (required):
      The amount a user should be charged for transactions after clicking this button

private-key (required):
      The private key given to you by @Pay

public-key (required):
      @Pay's public key, given to you by @Pay

partner-id (required):
      The partner ID given to you by @Pay

^**universal:
      This flag indicates that a universal payment button should be returned.

subject:
      The subject of the mailto: email
      (the message that a user will be sending to @Pay's servers after clicking the button)

signup-url:
      The signup URL for a Universal Button offer. This option should only be present if you use the universal flag.

image:
      The URL to a small thumbnail image to be used in the button
      Default: https://www.atpay.com/wp-content/themes/atpay/images/bttn_cart.png

background-color:
      The background color of the button
      Default: #6dbe45

foreground-color:
      The foreground color of the button
      Default: #ffffff

title:
      The title for each button

wrap:
      Will use wrapped (with a styled div container) version of template
      Default: false

wrap-text:
      Text to use within the wrapper
      Default: "Made for Mobile"

templates:
      Location of button templates
      Default: ./lib/atpay/button/templates

env:
      The environment you want to generate buttons for; currently sandbox or production
      Default: production

user_data:
      Optional user data to be passed in as a string for your use

input:
      Input File
     Default: $stdin^*

^*Reads from STDIN a comma delimmited file with each line containing the email address you're sending the button to and the credit card token you've

^**With a universal button the program doesn't look for an input stream, as it only ever generates one button.

received from @Pay for that button:

[e-mail],TL1UwJFXVN7e4p6+0B5N8hy4qQyqeNxVllmC663MLcMupuAWXdHJ9g8PRAnlIh+AMZBgpaIrfWStZ5/3hYi6vCAV7q6+3M6LLqxk
[e-mail],XKCF2E9QZPwdOSwfTQJzZC7byLt3PH8Tr1KhmLkfRHwfNJD5XbDRMrxGYOiSnfrLEKNzm9+a4r++bpUG2hNrPyYLpNgph3BXAAfC
[e-mail],iQOxdBV4KrFuPFgyywxytfbsD/rURrzmlADmg1QFP2VHd/kTnkXNpnp2Utv4RS0Zz2YeOloilMhljsOcRVA2YwSu9knwF1h6tNjE

Example

$ atpay_buttons --title "Pay" --amount 50.00 --subject "Payment for fifty bucks" --private-key "" --public-key "" --partner-id 20 --input input.txt

Where input.txt contains

[e-mail],TL1UwJFXVN7e4p6+0B5N8hy4qQyqeNxVllmC663MLcMupuAWXdHJ9g8PRAnlIh+AMZBgpaIrfWStZ5/3hYi6vCAV7q6+3M6LLqxk
[e-mail],XKCF2E9QZPwdOSwfTQJzZC7byLt3PH8Tr1KhmLkfRHwfNJD5XbDRMrxGYOiSnfrLEKNzm9+a4r++bpUG2hNrPyYLpNgph3BXAAfC
[e-mail],iQOxdBV4KrFuPFgyywxytfbsD/rURrzmlADmg1QFP2VHd/kTnkXNpnp2Utv4RS0Zz2YeOloilMhljsOcRVA2YwSu9knwF1h6tNjE

will output three buttons, one for each of the email addresses above, in HTML format, one per line. If you're sending out one offer per email, you'll simply include each line in the outgoing message to the recipient (one to [e-mail], one to [e-mail], and one to [e-mail]).

A button from the example above looks like this:

Library Usage

After following the installation instructions above, you'll have the @Pay button generator library loaded in your application. Let's create an array containing hashes with our users' email address and html code for a button to deliver to them:

  require 'atpay_buttons'

  button_maker = AtPay::Button::Generator.new({
    public_key: ATPAY_PUBLIC,
    private_key: ATPAY_PRIVATE,
    partner_id: ATPAY_PARTNER,
    environment: :sandbox,
    amount: 20
  })

  output = []

  User.active.each do |user|
    output << {
      email: user.email,
      button_html: button_maker.generate email: user.email, source: user.source
    }
  end

  puts output.inspect

Generating a Universal button is similar to the process above. However as the same button will work for multiple buyers you only need to make the one call to generate. The source should be the URL a customer should visit to register their card info with @Pay. This can be any page that implements the @Pay Javascript SDK.

  require 'atpay_buttons'

  button_maker = AtPay::Button::Generator.new({
    public_key: ATPAY_PUBLIC,
    private_key: ATPAY_PRIVATE,
    partner_id: ATPAY_PATNER,
    environment: :sandbox,
    amount: 20
  })

  puts button_maker.generate email: 'none', type: :url, source: 'https://special.example.com/signup'

ActionMailer Example

Assume you have a model that represents an offer you'd like to send to a user:

  class OfferMailer < ActionMailer::Base
    default from: '[e-mail]'

    def offer_email(offer)
      @button = generator.generate({
        email: offer.recipient.email,
        source: offer.recipient.card_token
      })

      mail({ 
        to: offer.recipient.email,
        subject: offer.name
      })
    end

    private
    def generator
      AtPay::Button::Generator.new({
        amount: offer.amount
      }.update(atpay_config))
    end

    # NOTE: Just throw this in an initializer if you can
    def atpay_config
      {
        public_key: ATPAY_PUBLIC,
        private_key: ATPAY_PRIVATE,
        partner_id: ATPAY_PARTNER,
        environment: (Rails.env != "production") ? :sandbox : :production
      }
    end
end

Templates

The generator uses a set of four default templates located in "lib/atpay/button/templates/". The yahoo.liquid template will be used for yahoo emails. The default.liquid template is for all other email providers. There are also versions prefixed with "wrap_" that will be used if the wrap parameter is set to "true". These "wrapped" templates are simply versions with a styled div that hold the buttons.

To use your own custom templates, you can download the provided default versions. After making the desired modifications, set the template parameter to the location of your modified templates.