This document describes the architecture of Act's online payment subsystem. This system defers the actual purchasing to a third party, usually a bank. We allow for pluggable backends to target various online payment solutions.
Currently implemented backends are YEF, used by the YAPC::Europe Foundation, TPF, used by The Perl Foundation, and PayPal. YEF and TPF online payment funds end up in the selected foundation's bank account. The foundation then forwards them back to the organizers. Using either backend requires prior agreement between the organizers and the relevant foundation.
YEF currently accepts payments in euros. TPF currently accepts payments in US dollars. PayPal accepts payments in various currencies, check the PayPal documentation for available currencies.
There's also a Fake backend which simulates a purchase for testing purposes.
The system is configured from each conference's conf/act.ini configuration
file.
[payment] open = 1 type = YEF
Set open to 1 to enable, or to 0 to disable, the online payment system.
type should be set to the appropriate backend: YEF, TPF or Fake.
Let's now walk through the steps involved in a purchase.
In her main page, a user is invited to purchase a ticket to the conference if she's registered and hasn't yet paid.
Clicking the purchase button invokes Act::Handler::User::Purchase.
This fetches the prices from the database table and displays the
purchase form via templates/user/purchase. This template can be overridden
and customized on a per-conference basis.
When a purchase form with a valid price is submitted, Act::Handler::User::Purchase
creates a new order in the database with a status of init.
We then call the plugged backend (Act::Payment::Foo) to create a form
which contains encrypted information about the purchase order. When this form
is submitted, the user is taken to the bank's web site.
The bank handles credit card input and validation, and offers a link back to the user's main page in the conference.
Meanwhile, the bank sends us an HTTP request with the status of the purchase.
The PayPal payment backend implements PayPal's "Instant Payment" which requires a PayPal "Business Account". Communication between Act and PayPal is encrypted using X509 certificates.
Each distinct PayPal account requires configuring a payment type, which holds
information about the account. In this example we configure Act for a PayPal
account we'll identify as "Foo", and call the payment type payment_type_PaypalFoo.
This type should be used to configure payment for conferences wishing to use this PayPal account.
Using the PayPal payment backend requires a one time configuration of the PayPal plugin.
Encrypted communication requires PayPal's public X509 certificate. Download paypal_cert.pem from the PayPal account's s Profile Summary page on the PayPal web site, section "Selling Preferences", item "Encrypted Payment Settings".
The plugin makes use of the openssl command line utility.
Configure the path to this program on your system.
[payment_plugin_Paypal] url_bank = https://www.paypal.com/cgi-bin/webscr pp_cert = $(home)/conf/paypal_cert.pem.pem openssl = /usr/bin/openssl
PayPal provides a sandbox for testing purposes. To use the sandbox, configure the plugin to use sandbox URLs. You'll need to download PayPal's sandbox public certificate, which is different from the one used in production.
[payment_plugin_Paypal] url_bank = https://www.sandbox.paypal.com/cgi-bin/webscr pp_cert = $(home)/conf/paypal-sandbox-cert.pem openssl = /usr/bin/openssl
Create a key pair (keyFoo.pem) and certificate (certFoo.pem).
# openssl genrsa -out keyFoo.pem 1024 # openssl req -new -key keyFoo.pem -x509 -days 365 -out certFoo.pem
and place them in your conf/ directory.
Now upload the certificate certFoo.pem to the PayPal account: From the account's Profile Summary page on the PayPal web site, section "Selling Preferences", item "Encrypted Payment Settings".
Once the certificate is uploaded, make a note of the Cert ID for the certificate.
We now configure the payment type in the global act.ini.
[payment_type_PaypalFoo] plugin = Paypal email = email@example.com my_key = $(home)/conf/keyFoo.pem my_cert = $(home)/conf/certFoo.pem my_cert_id = XXXXXXXXXXXXX
email is the email address of the PayPal account. It is visible on the
the account's Profile Summary page PayPal web site, section "Account Information",
item "Email".
Act uses PayPal's "Instant Payment Notification" to receive notifications
of payments from PayPal. The URL on your web server used by PayPal to send
those notifications is /<type>confirm, where type is the
payment type.
<Location /PaypalFooconfirm>
PerlSetVar ActPaymentType PaypalFoo
SetHandler perl-script
PerlHandler Act::Handler::Payment::Confirm
</Location>
During the purchase process, Act displays information specific to the payment type. This commonly includes information about the account and the financial institution providing online payment, alternate means of payment, and contact information. If the payment type is configured to use the PayPal Sandbox, this is the place to mention it.
This template must bear the name of the payment type and be stored in directory templates/core/bank. In our example we create a file named templates/core/bank/PaypalFoo.