StayPal

StayPal

PayPal for Statamic.

StayPal currently supports PayPal Payments Standard (aka Website Payments Standard). It enables you to create:

  1. encrypted PayPal buttons using native Statamic fields and
  2. a Statamic-powered membership site.

Docs

Settings always display the default value. They also indicate the recommended usage, config file (key: default_value) or tag parameter (parameter="default_value").

You can edit the code within <pre>s on this page before copying and pasting.

Installation

Upload the staypal folder to _add-ons and follow the setup directions below.

Setup

To use encrypted buttons, you need:

  1. a private key,
  2. a public certificate, and
  3. a PayPal public certificate.

To get started, open your terminal and navigate to your site dir.

cd path/to/your/site

Step 1: Keys and Certificates

Perform the following commands above root.

Private Key

Create your private key by pasting the following in your terminal. Replace private_key with your preferred name.

openssl genrsa -out private_key.pem 1024
Public Certificate

Create your public certificate by pasting the following in your terminal. Replace private_key and public_cert with your preferred names.

openssl req -new -key private_key.pem -x509 -days 365 -out public_cert.pem

After entering this command, answer the questions about your business.

Upload this to the PayPal website:

  1. Log in to your PayPal account.
  2. Navigate to Profile > My Selling Tools
  3. Click Encrypted payment settings.
  4. Upload to Your Public Certificates form.
  5. Make sure to copy the Cert ID for your settings.

Your public certificate expires in a year. Simply repeat this step annually to stay in business.

PayPal Public Certificate

On the Encrypted payment settings page, you should see PayPal Public Certificate and a download button underneath.

Download the PayPal Public Certificate and place it above root on your site (next to the private key and public certificate you created).

Step 2: Block Unencrypted Buttons (Optional)

This step makes your setup more secure.

  1. On the Encrypted payment settings page, click the Website Payment Preferences link.
  2. Find Encrypted Website Payments.
  3. Turn on Block Non-encrypted Website Payment.

{{ staypal:encrypt }}

{{ staypal:encrypt }} encrypts buttons on the fly. This means you can use native Statamic fields for things like price, name, color, etc. to securely sell products.

Required Settings

Find more options and detailed explanations in PayPal’s Developer Docs.

Set all paths relative to your root.

private_key
private_key:

The path to your private key.

Do not allow public access to this information or file.

public_cert
public_cert:

The path to the certificate you created.

Do not allow public access to this information or file.

paypal_cert
paypal_cert:

The path to the certificate you downloaded from PayPal.

Do not allow public access to this information or file.

cert_id
cert_id:

The ID associated with the public_cert you uploaded to PayPal.

Do not allow public access to this information.

business
business:

The email address associated with the PayPal account.

cmd
cmd:

The type of button you wish to create.

Button Types

The following examples assume the usage of _config/add-ons/staypal/staypal.yaml with settings similar to:

private_key: '../private_key.pem'
public_cert: '../public_cert.pem'
paypal_cert: '../paypal_cert_pem.txt'
business: iam@curtisblackwell.com
cert_id: CERT_ID_OBTAINED_FROM_PAYPAL
currency_code: USD

Available button types depend on the type of PayPal account you have.

  1. Buy Now

    _xclick
    

    See Table 3. HTML Variables for Individual Items for requirements and options.

    {{ staypal:encrypt
        cmd         = '_xclick'
        item_name   = '{ title }'
        amount      = '{ price }'
        button_text = 'Buy Now'
    }}
    
  2. Cart

    _cart
    

    See Table 4. HTML Variables for Payment Transactions and Table 5. HTML Variables for Shopping Carts for requirements and options.

    {{ staypal:encrypt
        cmd         = '_cart'
        add         = '1'
        item_name   = '{ title }'
        amount      = '{ price }'
        button_text = 'Add to Cart'
    }}
    
  3. Subscription

    _xclick-subscriptions
    

    See Table 6. Subscribe Button HTML Variables for requirements and options.

    {{ staypal:encrypt
        cmd         = '_xclick-subscriptions'
        item_name   = '{ title }'
        a3          = '{ price }'
        p3          = '{ duration }'
        t3          = '{ duration_unit }'
        src         = '{ bool_recur }'
        srt         = '{ recur_times }'
        custom      = '{ get_post:username }|{ get_post:password }'
        button_text = 'Subscribe'
    }}
    
  4. Automatic Billing

    _xclick-auto-billing
    

    See Table 7. Automatic Billing Button HTML Variables for requirements and options.

    You also need to pass a max_amount, which usually gets captured from the customer. Check out Raven if you want to do this and don’t know how on your own.

    {{ staypal:encrypt
        cmd                = '_xclick-auto-billing'
        item_name          = '{ title }'
        max_text           = '{ plan_description }'
        set_customer_limit = 'max_limit_own'
        button_text        = 'Bill Me Automatically'
        min_amount         = '{ charge_min }'
        max_amount         = '{ charge_max }'
    }}
    
  5. Installment Plan

    _xclick-payment-plan
    

    See Table 8. Installment Plan Buttons HTML Variables for requirements and options.

    {{ staypal:encrypt
        cmd                 = '_xclick-payment-plan'
        item_name           = '{ title }'
        disp_tot            = '{ bool_display_total }'
        option_index        = '0'
        option_selectn      = '{ payments_num }'
        option_selectn_name = '{ plan_name }'
        option_selectn_type = 'E'
        option_selectn_am   = '{ payment_amount }'
        option_selectn_pm   = '{ payment_period }'
        option_selectn_tm   = '{ payment_period_unit }'
        option_selectn_nm   = '{ payments_num }'
    }}
    
  6. Donation

    _donations
    

    See Table 3. HTML Variables for Individual Items for requirements and options.

    {{ staypal:encrypt
        cmd         = '_donations'
        item_name   = '{ title }'
        button_text = 'Donate'
    }}
    

Optional Settings

Find more options and detailed explanations in PayPal’s Developer Docs.

item_name
item_name=""

The name of the item.

amount
amount=""

The price.

You can leave out the price to allow customers to name their own price with Buy Now and Donate buttons.

currency_code
currency_code:

The currency of the payment.

button_text
button_text="Buy"

The text of the button.

button_class
button_class=""

A space-separated list of classes to apply to the button.

sandbox
sandbox=""

Setting sandbox="yes" will use the PayPal Sandbox rather than the live site, allowing you to test your buttons if necessary.

{{ staypal:create_member }}

{{ staypal:create_member }} will create a new member. This, along with {{ staypal:edit_field }} and native Statamic tags, will enable you to create a surprisingly powerful membership site. See Creating a Membership Site with StayPal for a more thorough explanation.

You must set custom in {{ staypal:encrypt }} as done in the following example.

custom="username|password"

Other values can be passed in to the custom parameter, but username and password must be first and second, in that order. Any other values passed will be ignored by StayPal.

If you wish to use a different delimiter, you can specify it with the delimiter parameter.

The fields used to collect the username and password must use username and password as the input names.

<input type="text" name="username">
<input type="text" name="password">

Optional Settings

roles
roles: subscriber

Roles is a pipe-separated list of membership roles to assign. See Statamic’s Managing Members for more information.

{{ staypal:create_member roles="subscriber|pretty thing" }}
delimiter
delimiter: '|'

The delimiter is the character used to separate values in {{ staypal:encrypt }}’s custom parameter. This character cannot be used in the username or password.

{{# on subscription page #}}
{{ staypal:encrypt
    cmd         = '_xclick-subscriptions'
    item_name   = '{ title }'
    a3          = '{ price }'
    p3          = '{ duration }'
    t3          = '{ duration_unit }'
    src         = '{ bool_recur }'
    srt         = '{ recur_times }'
    custom      = '{ get_post:username },{ get_post:password }'
    button_text = 'Subscribe'
}}

{{# on IPN page #}}
{{ staypal:create_member
    roles     = "subscriber|pretty thing"
    delimiter = ","
}}

{{ staypal:username_available }}

{{ staypal:username_available }} checks to see if someone already has the desired username (based on a POST variable of username). It returns true or false.

{{ staypal:input_valid }}

{{ staypal:input_valid }} checks the submitted username and password for forbidden characters.

Required Settings

name
name=""

Which input should this check, username or password?

When checking the validity of username, this tag will return true if the input username contains only letters, numbers, and/or underscores. Otherwise, it returns false.

When checking the validity of password, this tag will return true if the input password doesn’t contain any characters you forbade. Otherwise, it returns false.

Optional Settings

forbidden_chars
forbidden_chars="|"

Which characters should be forbidden from use in passwords? You must forbid the delimiter from {{ staypal:create_member }}’s custom setting. Otherwise new members’ information could get messed up.

StayPal checks this parameter only when using name="password".

delimiter
delimiter="a"

The delimiter for the forbidden characters.

{{ staypal:input_valid
    name            = "password"
    forbidden_chars = ",|&|\"
    delimiter       = "|"
}}

The above example would prevent users from using ,, &, and \ in their passwords.

a serves as the default delimiter because you probably shouldn’t ever forbid it.

StayPal checks this parameter only when using name="password".

{{ staypal:forbidden_chars }}

The {{ staypal:forbidden_chars }} tag pair outputs forbidden characters present in the user’s desired password.

Optional Settings

forbidden_chars
forbidden_chars="|"

forbidden_chars forbids characters, delimited by a or the character set in delimiter. These characters should match those in the {{ staypal:input_valid }} forbidden_chars setting.

<ul>
  {{ staypal:forbidden_chars forbidden_chars="|a " }}
    <li>{{ name }}</li>
  {{ /staypal:forbidden_chars }}
</ul>
delimiter
delimiter="a"
<ul>
  {{ staypal:forbidden_chars
      forbidden_chars = " |,"
      delimiter       = "|"
  }}
    <li>{{ name }}</li>
  {{ /staypal:forbidden_chars }}
</ul>

The above example would list , and/or SPACE (or whatever is set in the space parameter) for a literal space if present in the user-submitted password.

space
space="SPACE"

If you forbid a literal space, use space to change the output if present in a user’s password.

<ul>
  {{ staypal:forbidden_chars
      forbidden_chars = "|a "
      space           = "OUTER SPIZZACE"
  }}
    <li>{{ name }}</li>
  {{ /staypal:forbidden_chars }}
</ul>

{{ staypal:member_has_role }}

{{ staypal:member_has_role }} checks to see if the logged in member has a specific role and returns true or false.

Optional Settings

role
role="subscriber"

Which role do you want to check for?

{{ staypal:edit_field }}

{{ staypal:edit_field }} edits a member field. It may not function properly with non-YAML array fields. Use this to manage members’ roles.

Required Settings

value
value=""

The new, appended, or prepended value of the field. See mode.

Optional Settings

mode
mode: append

Do you want to append, prepend, or replace the current settings?

field
field="roles"

Which field do you want to edit?

Recommendations for Settings

Keep all global settings in staypal.yaml. View the included file for an example.

Per-item settings should be handled with tag parameters. See more info on these below.

You can override global settings on a per-item basis with tag parameters.

Checkout Page Settings

You can customize the appearance and function of checkout pages using the options found in Table 9. HTML Variables for Displaying PayPal Checkout Pages

If you collect customer information on your site, you should automatically fill out that info. Check out the options in Table 10. HTML Variables for Filling Out PayPal Checkout Pages Automatically for Buyers.

Third-Party Carts

If you use a non-PayPal cart and the Cart Upload command, you may want to check out Table 11. HTML Variables to Set Up an Instant Update Payment and Table 12. HTML Variables to Set Up an Instant Update Payment for Dimension-Based Shipping Charges.

Support

For now, support requests should be emailed to helpme@curtisblackwell.com.

I have plans to use a forum (or something similar) in the near future, however I’m waiting to see what Statamic offers, if anything, when the Trading Post launches.

Feature Requests

Feature requests are encouraged and should be emailed to ihaveagreatidea@curtisblackwell.com.