Creating a Payment Method

To create a custom payment method for CampTix you will need to extend the CampTix_Payment_Method class, which extends the CampTix_Addon class and implements some payment-specific methods and helpers. There are only a couple of things required from a payment method. The public member variables which describe the payment method:

• Payment method id (lowercase, alpha only, no spaces)
• Payment method name (appears on the front end)
• Description (appears in the payment methods configuration panel)
• Supported currencies (an array of currency codes)

And second, the payment_checkout method implementation. This is called whenever CampTix is ready to checkout with your payment method. Here's a short example of the above:

class CampTix_Payment_Method_Blackhole extends CampTix_Payment_Method {
    public $id = 'mypayment';
    public $name = 'My Payment Method';
    public $description = 'Learning how payment methods work.';
    public $supported_currencies = array( 'USD', 'EUR' );

    public function payment_checkout( $payment_token ) {
        // Will do some checkout here
    }
}

All your actual checkout process is implemented in the payment_checkout method, and could be scattered around other methods as well, especially when a payment method is a redirect-type one, such as PayPal Express Checkout. It's important to keep the $payment_token variable since it's the only thing that connects a concrete payment to an attendee or multiple attendees.

At some point, your class should call the payment_result method, to signal back to CampTix some payment result for a specific payment token. A payment result can be defined by one of the following constants, available in the $camptix global:

• PAYMENT_STATUS_CANCELLED - the payment was cancelled by the user
• PAYMENT_STATUS_COMPLETED - the payment was completed successfully
• PAYMENT_STATUS_PENDING - the transaction is pending and will be updated once it's completed or failed
• PAYMENT_STATUS_FAILED - the transaction failed
• PAYMENT_STATUS_TIMEOUT - the payment has timed out
• PAYMENT_STATUS_REFUNDED - the payment was refunded

Along with the payment result, you can also pass in a data array, which can contain the transaction ID and transaction details, as well as other arbitrary data for further use or logging. Here's an example of a payment_checkout method, which simply always returns a successful transaction:

function payment_checkout( $payment_token ) {
    global $camptix;

    $payment_data = array(
        'transaction_id' => rand( 1, 9999 ),
        'transaction_details' => array(
            'buyer_email' => '[email protected]',
        ),
    );

    return $this->payment_result( $payment_token, $camptix::PAYMENT_STATUS_COMPLETED, $payment_data );
}

Order Contents, CampTix Options, Logging

To get the order contents (the purchased tickets) from a payment token, you should use the get_order method available in the payment gateway class. Here's an example:

$order = $this->get_order( $payment_token );
print_r( $order );

The order will contain all the items the user wants to purchase and their totals. You don't have to worry about verifying the order (such as ticket availability, etc) -- CampTix does this for you automatically and show an error to the user if something has gone wrong.

You can access the CampTix options at any time using the camptix_options member variable, which is an associative array of options. The ones you will most likely use are currency and event_name but you can use others too. Here's an example how you would check for an unsupported currency:

if ( ! in_array( $this->camptix_options['currency'], $this->supported_currencies ) )
    die( 'The selected currency is not supported by this payment method.' );

Don't change the options in that array, since they will have no effect on the real CampTix options.

You can log events at any time by using the log method, available in the payment gateway class. The method takes several arguments:

• Short and descriptive log message
• Post ID - you can assign a log entry to an attendee or ticket
• Data - additional data associated with the log entry
• Section - defaults to "payment", but you can use a different section

Please don't use localization functions with log messages, as they may become difficult to search and aggregate when translated to different languages. Do log important events, such as payment failures, timeouts, etc.

Payment Options

Your payment method can (and probably should) have some options, like username and password, or API keys, or any other settings. To add payment options to your payment method, you should first be familiar with the Settings API. There are predefined callback methods you can use to render common controls, such as text boxes, yes-no fields and more.

Here's a short example how of a username field:

[...] class declaration and other things

// Our payment method options will be stored here
protected $options = array();

// Fired when CampTix initialized, you don't have to call this
function camptix_init() {
    $this->options = array_merge( array(
        'username' => '',
    ), $this->get_payment_options() );
}

// This is also called by CampTix when rendering your payment method sections
function payment_settings_fields() {
    // You can use the helper function along with the helper callback function
    $this->add_settings_field_helper( 'username', 'Username', array( $this, 'field_text' ) );
}

// Called by CampTix when your payment settings are being saved
function validate_options( $input ) {
    $output = $this->options;

    if ( isset( $input['username'] ) )
        $output['username'] = $input['username'];

    return $output;
}

[...] The rest of the implementation

Might be confusing at first, but it's actually really easy. You can then access the $this->options array throughout your class whenever you need to.

Further reading

To better understand how payment methods work, please read the existing payment methods implemented in CampTix. You can find them in the addons directory, their names start with payment-*.php. You might also find the inc/class-camptix-payment-method.php file useful.

If you have any questions or trouble creating your own payment method, please get in touch, we'll be happy to help. If you have created a payment method for CampTix, consider contributing it back to CampTix by opening a pull request.

Open Source Your Work

If you create a new addon for CampTix, we strongly encourage you to release it in the WordPress.org plugin directory, so that others can benefit from the work you've done, and also contribute back to it.