How to Create a Custom Payment Gateway with AWPCP

Documentation here pertains to AWPCP 3.3.2 and higher.

Implementation Notes

All payment gateways should extend classAWPCP_PaymentGatewayand implement at least the four methods described below:

• process_payment: called when the payment gateway is about to be used in a transaction. This is the method used to render the payment buttons in PayPal or 2Checkout payment gateways, and the Billing Form in PayPal Pro Direct Payment or Authorize.Net.
• process_payment_notification,process_payment_completedandprocess_payment_canceled: that are called when a notification is received for a transaction associated to the payment gateway, or when the user is redirected to thepayment-completedandpayment-canceledURLs.

Most payment gateways allow developers to specify a notify, return and cancel URL. Those are directly associated with theprocess_payment_notification,process_payment_completedandprocess_payment_canceledmethods above, respectively.

You can use the following code to generate the URLs mentioned above, for a given transaction,

$payments = awpcp_payments_api();
$notify_url = $payments->get_notify_url($transaction);
$return_url = $payments->get_return_url($transaction);
$cancel_url = $payments->get_cancel_url($transaction);

The plugin will handle those URLs automatically and will take care of calling the right method in each case.

The implementation of the methods varies depending on the kind of integration you are trying to develop.

1. Integration by Payment Button (PayPal Standard or 2Checkout)
   1. process_payment: should print the payment button.
   2. process_payment_completed: called when the user returns to your website from the payment gateway’s website, after having made a payment. The method should validate the information received and try to find out if the payment was successful or not, and update the transaction’s payment status. This is how PayPal Standard payment gateway works; seepayment-gateway-paypal-standard.php.
   3. process_payment_canceled: called when the user returns to your website after he or she cancelled the payment request. The method should update the payment status of the transaction.
   4. process_payment_notification: called every time a notification is received for a transaction that used your payment gateway. Similar to whatprocess_payment_completeddoes, this method has to verify the information received and figure out the new payment status and update the transaction accordingly.

   Afterprocess_payment_completedorprocess_payment_canceledhave been called, the plugin continues handling the payment transaction and will let the user post the listing, if the payment was successful, or show him an error, if the payment failed.

2. Integration by Custom Form (Authorize.Net)
   1. process_payment: should print the billing form, but also takes care of precessing the data entered, contacting the payment gateway’s servers and consolidate the payment (update the transaction with a proper payment status).When you are done processing the payment, after you have updated the payment status of the transaction, callreturn awpcp_payments_api()->process_payment_completed($transaction);to let the plugin continue handing the transaction and allow the user to post the listing (if the payment was successful).
   2. process_payment_completedandprocess_payment_cancelledare usually implemented without a body (just areturn;line), because the user is never redirected during the payment transaction.
   3. If the payment gateway supports notifications, theprocess_payment_notificationmethod should be implemented as described in the Integration by Payment Button case.

Registering a payment gateway

Register an action for theawpcp-register-payment-methodshook. The callback will receive an instance of thePayments_APIas its only argument. You should create an instance of your Payment Gateway and pass it to theregister_payment_methodmethod. For example:

public function register_payment_methods( $payments ) {
    $payments->register_payment_method( new AWPCP_PayPalStandardPaymentGateway );
}