Custom Gateway Integration
This documentation is provided if you want to build and maintain your own integration with a payment gateway for Event Espresso 3, otherwise we offer Custom Gateway Integration services.
http://developer.eventespresso.com/docs/ee4-payment-method-development/
Step 1 – Add a Gateway Settings Page
When an admin clicks on the “Payment Settings” link in the Event Espresso section of the WordPress admin menu, the page that is loaded causes the execution of a number of PHP scripts that will scan the two directories wp-content/uploads/espresso/gateways and wp-content/plugins/event-espresso/gateways. Any folder that is found is checked to see if it contains a file named settings.php. All settings.php files that are found are then loaded into the PHP interpreter.
Our recommended best practice is to wrap your code that is responsible for saving and displaying the settings for your gateway in a function and to then add your function to the action hook “action_hook_espresso_display_gateway_settings”. Please see gateways/paypal/settings.php for an example.
All gateways that have been activated in the payment settings page have their my-gateway/init.php file loaded into the PHP interpreter when the WordPress action hook “plugins_loaded” is instantiated on every page load. The gateway developer can use the my-gateway/init.php file to cause other gateway files to load and can add their functions to various hooks provided by Event Espresso.
2 – Adding your gateway to the payment page
On-site Gateway?
If you are developing a payment gateway that presents the user with a form for entering the credit card information without leaving the event website, what we call an “on-site gateway”, then you will hook your function that presents the form into the action hook “action_hook_espresso_display_onsite_payment_gateway”.
Off-site Gateway?
If you are developing a payment gateway presents the user with a button that will take the user to a third party site enter the credit card information, what we call an “off-site gateway”, then you will hook your function that presents the user with the button into the action hook “action_hook_espresso_display_offsite_payment_gateway”.
In each case, your function will be passed a single parameter, an array, that contains information about the event, the attendee, etc. The exact information added to the array can be seen in the gateways/gateway_display.php file starting around line 50.
3 – Receiving Payment Notification Messages
Many “off-site gateways” send back a response to your Event Espresso powered website about the status of the transaction. Some gateways require a return message that they will present on their receipt page that must be free of all CSS and JavaScript. For these reasons, Event Espresso sets up a separate “Transactions” page, which can be hidden from the users navigation, and can be customized with a stripped down theme template that does not load any CSS or JavaScript.
For security reasons, the Event Espresso script that runs on this page requires that the registration id be returned in either the POST or GET variables. The success of processing the transaction also requires the script to be aware of the attendee id. For these reasons, we have provided a filter hook, “filter_hook_espresso_transactions_get_attendee_id”, which you can use to accomplish both tasks.
Some gateways allow you to specify the notification URL at the time you create the button in Step 2, allowing you to add the attendee id and registration id as GET variables in the notification URL. However, some gateways force you to specify the notification URL ahead of time in a control panel, in which case you must send back the attendee id and registration id inside of fields provided by the gateway’s API.
In either case, the function that you hook to “filter_hook_espresso_transactions_get_attendee_id” must return the attendee id, and if it is not already present, add the registration id as a field in the REQUEST array, ie, $_REQUEST['registration_id'] = $_REQUEST['REG_ID'];.
The Event Espresso script on the “Transactions” page will then take the attendee id you returned from the “filter_hook_espresso_transactions_get_attendee_id” filter hook and use it to gather information from the database about the registration as well as performing the security check against the $_REQUEST['registration_id'] that you provided.
Your function will receive a single parameter, an array, containing fields for the attendee_id, registration_id, fname (attendee’s first name), lname (last name), etc. You can see some of the fields added in the “espresso_prepare_payment_data_for_gateways()” function in gateways/process_payments.php, and the “espresso_get_total_cost()” function in gateways/process_payments.php.
Processing Transaction Return Values
There are four fields that your function is required to add to the array before you return it: txn_type, payment_status, txn_id, and txn_details. The “txn_type” field should be something to indicate concisely the type of transaction performed, such as “PayPal” or “Authorize.net”. The payment_status should be one of the three recognized by Event Espresso, “Incomplete”, “Pending”, or “Completed”.
How do I determine if the payment status is highly gateway specific?
The “txn_id” should be a unique identifier, sometimes provided by the gateway. The “txn_details” will be saved to the database and a log file to give the site administrator information to reference in case they need to contact the gateway provider about a problem with a transaction. So it should contain as much information as possible, while scrubbing out credit card numbers, etc, if necessary for PCI compliance.
4 – Displaying the Payment Status on the “Thank You” Page
The “Thank You” page is provided as the main destination URL for the on-site gateway forms on the payment page, and as the return URL for off-site gateways. The hooks provided by Event Espresso on the “Thank You” page are almost identical to those on the “Transactions” page, except that the “filter_hook_espresso_transactions_get_payment_data” filter is replaced by the “filter_hook_espresso_thank_you_get_payment_data” filter.
Security
The security requirements are also the same as those on the “Transactions” page. You must provide a function added to the “filter_hook_espresso_transactions_get_attendee_id” filter that returns the attendee id, and the registration id must be a field in the $_REQUEST variable.
Off-site Processing
If you are using the “Thank You” page as a return URL for an off-site gateway provider and your notification processing is being done by the “Transactions” page then there is no need for you to hook into “filter_hook_espresso_thank_you_get_payment_data” filter.
On-site Processing
If you are writing a gateway for an on-site provider, or your off-site provider does not use a separate notifications page but returns the transaction information with the user to the “Thank You” page, then you should add your processing function to the “filter_hook_espresso_thank_you_get_payment_data” filter.
Just like the filter on the “Transactions” page, your function will receive an array of information corresponding to the attendee id that you provided.
For on-site processing this information should be combined with the form POST data to make the cURL request to the gateway provider. Your function should add four fields to the array that is passed into it before returning the array: txn_type, payment_status, txn_id, and txn_details. For details, see the section in step 3, “Processing Transaction Return Values“.