The Act online payment architecture

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.

  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.

PayPal configuration

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.

Payment plugin configuration

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.

  url_bank    =
  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.

  url_bank    =
  pp_cert     = $(home)/conf/paypal-sandbox-cert.pem
  openssl     = /usr/bin/openssl

Creating a certificate

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.

Payment type configuration

We now configure the payment type in the global act.ini.

  plugin      = Paypal
  email       =
  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".

Confirmation URL configuration

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

Bank template

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.


Philippe Bruhat, Éric Cholet


This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.