shopp_add_order_event()

issue an order event.

shopp_add_order_event ($order, $type, $message )

@param int $order (conditionally required default:false) Will be false for sale and auth events, but needs the order id otherwise.
@param string $type (required) the order event type
@param array $message (optional default:array()) the event message
@return bool true on success, false on error

Description

issue an order event.

Order Event Types

Action Triggering Events

the following are events that trigger an action. The gateway module implements actions event listeners for these events and performs transactional events and notification events in response.

  • purchasePurchaseOrderEvent typically triggered by the gateway module or shopp_process_order to cause the creation of a purchase order based on the current cart contents. Typically, once the order is created, is it automatically invoiced, and either the auth (payment authorization) or sale (payment authorization and payment capture) is triggered.
  • authAuthOrderEvent triggers the gateway to initiate a payment authorization, but instructs the gateway not to charge the amount authorized.
  • saleSaleOrderEvent triggers the gateway to initiate a payment authorization, and charge the authorized amount.
  • captureCaptureOrderEvent triggers the gateway to initiate a capture on a previously authorized amount. This action is usually initiated by the merchant from the Order manager.
  • refundRefundOrderEvent triggers the gateway to initiate a refund. This action is usually initiated by the merchant from the Order manager, and will cause void and voided by default when the order is fully refunded.
  • voidVoidOrderEvent triggered to void a purchase order that has not been charged.

New Purchase event

The first order event in processing a new order is the purchase order event. Ordinarily, when the user submits an order on the confirm order page (or the checkout page if no confirmation is needed), the order is validated, and then the shopp_process_order action is performed. If the order validates, the purchase order event will be issued automatically, like so:

shopp_add_order_event(false,'purchase',array(
    'gateway' => ShoppOrder->processor() // the payment module the user selected
));

In the case when the checkout flow is interrupted to direct the user off-site to arrange payment, often the purchase order event is issued by the gateway module when the user returns to the Shopp site, and the transaction id (txnid), can be optionally added to the purchase event:

shopp_add_order_event(false,'purchase',array(
    'gateway' => ShoppOrder->processor(), // the payment module the user selected
    'txnid' => 'the_returned_txnid'       // (optional) the txnid returned from the payment website
));

After the purchase order event has been issued, the current order information (cart contents, address information, order data) is committed to the database as a new purchase order, the order total is invoiced using the invoiced order event, and Shopp will determine the next order event action, usually one of:

  • auth – typically issued when the order contains shipped items, and therefore the order amount capture event will be deferred until the time of shipping.
  • sale – typically issued when the order contains only non-shipped items. Therefore the payment can be captured immediately, and the captured order event can be immediately issued.

Auth and Sale Event

In response to the purchase order event, the auth order event is triggered, or the sale order event is triggered as described above. Usually, the gateway module will be listening for one or both of these events, and will process the payment authorization and if applicable the payment capture, and will respond with the appropriate authed order event, or authed and captured order event.

In the event of a failure to authorize the payment, an auth-fail order event will be issued by the gateways module. In the event of a failure to capture the payment, a capture-fail will be issued by the gateway module.

Here is an example of the auth and sale events.
auth event

// given the new Purchase object created from the purchase order event
shopp_add_order_event($Purchase->id,'auth',array(
    'gateway' => $Purchase->gateway,
    'amount' => $Purchase->total
));

sale event

// given the new Purchase object created from the purchase order event
shopp_add_order_event($Purchase->id,'sale',array(
    'gateway' => $Purchase->gateway,
    'amount' => $Purchase->total
));

Responding to an Authorization or Authorization + Capture Event

Depending on whether the gateway module is responding to a system generated auth or sale order event, or a merchant initiated capture request, the gateway module will either issue an authed order event in response to an auth order event, with a deferred captured order event in response to a merchant initiated capture order event, or an authed order event with capture flag / authed event followed immediated by a captured event in response to a sale order event.

Here are some examples of authed, authed+capture, or authed followed by captured.

authed – indicate only a payment authorization, but not payment capture.

// the order_id usually comes from the auth or sale event object $Event->order
shopp_add_order_event( $Event->order, 'authed', array( 
    'txnid' => 'txnid',             // Transaction ID from payment gateway, in some cases will be in $Event->txnid
    'amount' => 1.00,               // Gross amount authorized
    'gateway' => $Event->gateway,   // Gateway handler name (module name from @subpackage)
    'paymethod' => 'Credit Card',   // Payment method (payment method label from your payment settings)
    'paytype' => 'visa',            // Type of payment (check, MasterCard, etc)
    'payid' => '1111'               // Payment ID (last 4 of card or check number)
));

authed+capture – indicates both an authorization, and a capture at the same time

// the order_id usually comes from the auth or sale event object $Event->order
shopp_add_order_event( $Event->order, 'authed', array( 
    'txnid' => 'txnid',             // Transaction ID from payment gateway, in some cases will be in $Event->txnid
    'amount' => 1.00,               // Gross amount authorized
    'gateway' => $Event->gateway,   // Gateway handler name (module name from @subpackage)
    'paymethod' => 'Credit Card',   // Payment method (payment method label from your payment settings)
    'paytype' => 'visa',            // Type of payment (check, MasterCard, etc)
    'payid' => '1111',              // Payment ID (last 4 of card or check number)
    'fees'  => 0.50,                // Optionally pass gateway transaction fee on to the captured event
    'capture' => true               // Shopp will automatically issue the captured event following authed
));

authed and subsequent captured – for an additional measure of control, you can issue the two events in your code

// the order_id usually comes from the auth or sale event object $Event->order
shopp_add_order_event( $Event->order, 'authed', array( 
    'txnid' => 'txnid',             // Transaction ID from payment gateway, in some cases will be in $Event->txnid
    'amount' => 1.00,               // Gross amount authorized
    'gateway' => $Event->gateway,   // Gateway handler name (module name from @subpackage)
    'paymethod' => 'Credit Card',   // Payment method (payment method label from your payment settings)
    'paytype' => 'visa',            // Type of payment (check, MasterCard, etc)
    'payid' => '1111',              // Payment ID (last 4 of card or check number)
));

// either immediately after authed (in the case of a sale event)
// or in response to a capture order event
shopp_add_order_event( $Event->order, 'captured', array( 
    'txnid' => 'txnid',             // Transaction ID from payment gateway, in some cases will be in $Event->txnid
    'amount' => 1.00,               // Gross amount captured
    'gateway' => $Event->gateway,   // Gateway handler name (module name from @subpackage)
    'fees' => 0.50                  // Transaction fee assessed by the payment gateway
));

Refund Event

For payment gateways that have the capability to issue refund requests, a refund order event can be issued to trigger a refund action in the payment gateway module. If the payment gateway module is successful, it will issue a refunded order event to debit the receiveable amount on the order, and usually a voided order event will follow if the refund was for the entire order. A refund-fail event can be issued by the gateway module in the event the refund action fails.

refund event example

shopp_add_order_event($Purchase->id,'refund',array(
    'txnid' => $Purchase->txnid, // the original purchase transaction id
    'gateway' => $module, // the gateway module
    'amount' => $amount, // amount of the refund
    'reason' => $reason, // reason code mapped to reasons settings
    'user' => $user->ID // the wordpress user ID of the user initiating the refund
));

refunded event example

shopp_add_order_event($Event->order, 'refunded', array(
    'txnid' => 'refund_txnid', // Transaction ID for the REFUND event
    'amount' => $Event->amount,
    'gateway' => $Event->gateway
));

Void Event

For payments that have been authorized only, but where the payment has not been charged, the merchant can initiate a void order event from the Order manager. The payment gateway can, if capable and if necessary, void the authorization, and issue a voided order event to credit the receivable amount on the order.

void event example

shopp_add_order_event($Purchase->id,'void',array(
    'txnid' => $Purchase->txnid,
    'gateway' => 'modulename',      // gateway module from the original order
    'reason' => 1,                  // reason code from settings that was selected for the void
    'user' => $user->ID,            // WordPress user ID of the void order issuer
    'note' => $message              // note added to void by the merchant
));

voided event example

shopp_add_order_event($Event->order,'voided',array(
    'txnorigin' =>  $Event->txnid,      // Original transaction ID (txnid of original Purchase record)
    'txnid' => 'void_txn_id',           // Transaction ID for the VOID event
    'gateway' => $Event->gateway        // Gateway handler name (module name from @subpackage)
));

Transactional Events

the following events will cause the receivable balance on the order to change

  • invoicedInvoicedOrderEvent typically triggered after purchase creation to debit receivable balance for an order.
  • rebillRebillOrderEvent triggered to adjust the running balance for an order to accommodate a new recurring payment event. Debits the receivable balance on an order, so the RecapturedOrderEvent can credit the order.
  • refundedRefundedOrderEvent triggered by the gateway to indicate a successful refund. Debits receivable balance on the order.
  • voided-amtVoidedAmountOrderEvent triggered to indicate a partial order amount should be voided. Credits receivable balance on the order.
  • capturedCapturedOrderEvent triggered by the gateway to indicate successful funds capture. Credits receivable balance on the order.
  • recapturedRecapturedOrderEvent triggered by the gateway to indicate success funds recapture. Credits receivable balance on the order.
  • voidedVoidedOrderEvent triggered to indicate a successful voided order. Credits receivable balance on the order.

invoiced event example

// invoice $5 to order 101, which is using the mypaymodule gateway
shopp_add_order_event( 101, 'invoiced',array(
    'gateway' => 'mypaymodule',     // Gateway module name
    'amount' => 5.00                // amount invoiced on the order
));

rebill event example

// assuming you have looked up the Purchase object from recurring billing request
shopp_add_order_event( $Purchase->id, 'rebill', array(
    'txnid' => 'rebill_txnid',          // New Transaction ID
    'gateway' => $Purchase->gateway,    // Gateway class name (module name from @subpackage)
    'amount' => 1.00,                   // Gross amount authorized
    'fees' => 0.50,                     // Transaction fees taken by the gateway net revenue = amount-fees
    'paymethod' => 'check',             // Payment method (check, MasterCard, etc)
    'payid' => '1111'                   // Payment ID (last 4 of card or check number)  
));

recaptured event example

// recaptured payment on recurring order 102
shopp_add_order_event( 102, 'recaptured', array(
    'txnorigin' => 'orig_txnid',            // Original transaction ID (txnid of original Purchase record)
    'txnid' => 'new_txnid',                 // Transaction ID of the recurring payment event
    'amount' => 5.00,                       // Recurring Amount captured
    'gateway' => 'mypaymodule',             // Gateway handler name (module name from @subpackage)
    'balance' => 100.00,                    // Total Balance of the billing agreement over all payments
    'nextdate' => strtotime('+2 weeks'),    // Unix Timestamp of the next scheduled payment
    'status' => 'current'                   // String Status of the billing agreement

));

refunded event example

// if in response to the refund event
shopp_add_order_event( $Event->order, 'refunded', array(
    'txnid' => 'refund_txnid',      // Transaction ID for the REFUND event
    'amount' => $Event->amount,     // Amount refunded
    'gateway' => $Event->gateway    // Gateway module name
));

voided-amt event example

// void $1 on order 101
shopp_add_order_event(101, 'void-amt', array(
    'amount' => 1.00
));

captured event example

// in response to a capture order event
shopp_add_order_event( $Event->order, 'captured', array( 
    'txnid' => 'txnid',             // Transaction ID from payment gateway, in some cases will be in $Event->txnid
    'amount' => 1.00,               // Gross amount captured
    'gateway' => $Event->gateway,   // Gateway handler name (module name from @subpackage)
    'fees' => 0.50                  // Transaction fee assessed by the payment gateway
));

voided event example

// in response to void event
shopp_add_order_event($Event->order,'voided',array(
    'txnorigin' =>  $Event->txnid,      // Original transaction ID (txnid of original Purchase record)
    'txnid' => 'void_txn_id',           // Transaction ID for the VOID event
    'gateway' => $Event->gateway        // Gateway handler name (module name from @subpackage)
));

Notification Events

the following events are for error handling, notification and logging purposes

  • authedAuthedOrderEvent triggered by the gateway to indicate a successful payment authorization. This action will also adjust the authorized amount on the order.
  • auth-failAuthFailOrderEvent triggered by the gateway to indicate a failure to authorize a payment.
  • capture-failCaptureFailOrderEvent triggered by the gateway on a funds capture failure.
  • recapture-failRecaptureFailOrderEvent triggered by the gateway on a funds recapture failure.
  • refund-failRefundFailOrderEvent triggered by the gateway to indicate a refund failure.
  • void-failVoidFailOrderEvent triggered to indicate a void failure.
  • decryptDecryptOrderEvent triggered to indicate payment card decryption has taken place, logging the user account that accessed the information.
  • shippedShippedOrderEvent triggered to indicate that an order shipped.
  • downloadDownloadOrderEvent triggered to indicate that a download asset associated with an order has been downloaded.
  • noticeNoticeOrderEvent triggered to log when a note is sent to the customer from the Order manager.
  • reviewReviewOrderEvent triggered to add order review information, such as address verification, card verification, fraud check results to the order event log

authed event example

// the order id usually comes from the auth or sale event object $Event->order
shopp_add_order_event( $Event->order, 'authed', array( 
    'txnid' => 'txnid',             // Transaction ID from payment gateway, in some cases will be in $Event->txnid
    'amount' => 1.00,               // Gross amount authorized
    'gateway' => $Event->gateway,   // Gateway handler name (module name from @subpackage)
    'paymethod' => 'Credit Card',   // Payment method (payment method label from your payment settings)
    'paytype' => 'visa',            // Type of payment (check, MasterCard, etc)
    'payid' => '1111'               // Payment ID (last 4 of card or check number)
    'capture' => false              // Optionally indicate that payment was captured
));

auth-fail event example

// auth-fail usually in response to auth event
shopp_add_order_event( $Event->order, 'auth-fail', array(
    'amount' => $Event->amount,                     // Amount to be authorized
    'error' => '458',                               // Error code provided by the gateway (specific to payment gateway)
    'message' => 'The authorization failed',        // Error message reported by the gateway
    'gateway' => $Event->gateway,                   // Gateway module
));

capture-fail event example

// capture-fail usually in response to capture event
shopp_add_order_event( $Event->order, 'capture-fail', array(
    'amount' => $Event->amount,                     // Amount to be captured
    'error' => '566',                               // Error code provided by the gateway (specific to payment gateway)
    'message' => 'Unable to charge amount...',      // Error message reported by the gateway
    'gateway' => $Event->gateway,                   // Gateway module
));

recapture-fail event example

// recapture-fail usually in response to recapture event
shopp_add_order_event( $Event->order, 'recapture-fail', array(
    'amount' => $Event->amount,                     // Amount to be captured
    'error' => '785',                               // Error code provided by the gateway (specific to payment gateway)
    'message' => 'Unable to renew amount...',       // Error message reported by the gateway
    'gateway' => $Event->gateway,                   // Gateway module
    'retrydate' => current_time()                   // unix timestamp of the recapture attempt
));

refund-fail event example

// refund-fail usually in response to refund event
shopp_add_order_event( $Event->order, 'refund-fail', array(
    'amount' => $Event->amount,                     // Amount to be refunded
    'error' => '656',                               // Error code provided by the gateway (specific to payment gateway)
    'message' => 'The refund failed...',            // Error message reported by the gateway
    'gateway' => $Event->gateway,                   // Gateway module
));

void-fail event example

// void-fail usually in response to void event
shopp_add_order_event( $Event->order, 'void-fail', array(
    'error' => '656',                               // Error code provided by the gateway (specific to payment gateway)
    'message' => 'The void failed...',              // Error message reported by the gateway
    'gateway' => $Event->gateway,                   // Gateway module
));

decrypt event example

// usually issued by the Order Manager, when decrypting a Manual Processing order
shopp_add_order_event( $Purchase->id, 'decrypt', array(
    'user' => 1     // WordPress user id that decrypted/viewed the credit card
));

shipped event example

// usualled issued by shipping update from the Order manager
shopp_add_order_event($Purchase->id, 'shipped', array(
    'tracking' => '012345678983',   // Tracking number (you know, for tracking)
    'carrier' => 'UPS',             // Carrier ID (name, eg. UPS, USPS, FedEx)  
));

download event example

// download initiated by customer 20
// order 11, has a purchased item with id 51, and download id 110, from ip address 172.0.0.1
shopp_add_order_event( 11, 'download', array(
    'purchased' => 51,      // Purchased line item ID (or add-on meta record ID)
    'download' => 110,      // Download ID (meta record)
    'ip' => '172.0.0.1',    // IP address of the download
    'customer' => 20        // Authenticated customer
));

notice event example

// for order 15, WordPress user 1 sent the following notice to the customer
shopp_add_order_event(15, 'notice', array(
    'user' => 1,            // The WP user ID
    'note' => 'I have reset your download counter. Please try again. Sincerely, Me'     // The message to log for the order
));

review event example

// say that fraud review has failed on order 22
shopp_add_order_event(22, 'review', array(
    'kind' => 'FRT',        // The kind of fraud review: AVS (address verification system), CVN (card verification number), FRT (fraud review team)
    'note' => "The buyer's identity could not be verified." // The message to log for the order
));

Handling Order Events

Note that these are generic examples, to illustrate the event actions usage and handlers.

Generic event action handlers for all order events and for all gateways

// shopp_order_event action called for all order events
add_action('shopp_order_event', 'all_order_event_handler');

function all_order_event_handler ( OrderEventMessage $Event ) {
    $name = $Event->name

    if ( 'auth' == $name ) {
        // handle auth event action
        $orderid = $Event->order;   // the order number
        $gateway = $Event->gateway; // Gateway module slug
        $amount = $Event->amount;   // Amount to authorize
        // ... contact gateway and get authorization ...

        // after authorization, create an authed event
    }

    if ( 'sale' == $name ) {
        // handle sale event action
        $orderid = $Event->order;   // the order number
        $gateway = $Event->gateway; // Gateway module slug
        $amount = $Event->amount;   // Amount to authorize and capture
        // ... contact gateway and get authorization and capture funds ...
    }

    // alternatively by class name
    if ( is_a($Event, 'CaptureOrderEvent') ) {
        // handle refund event action
        $orderid = $Event->order;   // the order number
        $gateway = $Event->gateway; // Gateway module slug
        $txnid = $Event->txnid;     // Transaction ID associated with payment authorization
        $amount = $Event->amount;   // Amount to capture
        $user_id = $Event->user;    // User that initiated the capture
        // ... contact gateway and capture funds ...
    }       

    if ( is_a($Event, 'RefundOrderEvent') ) {
        // handle refund event action
        $orderid = $Event->order;   // the order number
        $gateway = $Event->gateway; // Gateway module slug
        $txnid = $Event->txnid;     // Transaction ID associated with payment authorization
        $amount = $Event->amount;   // Amount to refund
        $user_id = $Event->user;    // User that initiated the refund
        $reason = $Event->reason;   // Reason code
        // ... contact gateway and refund amount ...
    }
}

Specific event action handlers occuring for all gateways

// action hook of the form of shopp_{event}_order_event
add_action('shopp_auth_order_event', 'auth_order_event_handler');
add_action('shopp_sale_order_event', 'sale_order_event_handler');
add_action('shopp_capture_order_event', 'capture_order_event_handler');
add_action('shopp_refund_order_event', 'refund_order_event_handler');

function auth_order_event_handler ( AuthOrderEvent $Event ){
    $orderid = $Event->order;   // the order number
    $gateway = $Event->gateway; // Gateway module slug
    $amount = $Event->amount;   // Amount to authorize
    // ... contact gateway and get authorization ...

    // after authorization, create an authed event

}

function sale_order_event_handler ( SaleOrderEvent $Event ){
    // handle sale event action
    $orderid = $Event->order;   // the order number
    $gateway = $Event->gateway; // Gateway module slug
    $amount = $Event->amount;   // Amount to authorize and capture
    // ... contact gateway and get authorization and capture funds ...
}

function capture_order_event_handler ( CaptureOrderEvent $Event ){
    // handle refund event action
    $orderid = $Event->order;   // the order number
    $gateway = $Event->gateway; // Gateway module slug
    $txnid = $Event->txnid;     // Transaction ID associated with payment authorization
    $amount = $Event->amount;   // Amount to capture
    $user_id = $Event->user;    // User that initiated the capture
    // ... contact gateway and capture funds ...
}

function refund_order_event_handler ( RefundOrderEvent $Event ){
    // handle refund event action
    $orderid = $Event->order;   // the order number
    $gateway = $Event->gateway; // Gateway module slug
    $txnid = $Event->txnid;     // Transaction ID associated with payment authorization
    $amount = $Event->amount;   // Amount to refund
    $user_id = $Event->user;    // User that initiated the refund
    $reason = $Event->reason;   // Reason code
    // ... contact gateway and refund amount ...
}

Specific event action handlers for a specific gateway

// action hook of the form of shopp_{gatewaymodulename}_{event}
add_action('shopp_paypalstandard_auth', 'paypalstandard_auth_handler');
add_action('shopp_paypalstandard_sale', 'paypalstandard_sale_handler');
add_action('shopp_paypalstandard_capture', 'paypalstandard_capture_handler');
add_action('shopp_paypalstandard_refund', 'paypalstandard_refund_handler');

function paypalstandard_auth_handler ( AuthOrderEvent $Event ){
    $orderid = $Event->order;   // the order number
    $gateway = $Event->gateway; // paypalstandard
    $amount = $Event->amount;   // Amount to authorize
    // ... contact gateway and get authorization ...
}

function paypalstandard_sale_handler ( SaleOrderEvent $Event ){
    // handle sale event action
    $orderid = $Event->order;   // the order number
    $gateway = $Event->gateway; // paypalstandard
    $amount = $Event->amount;   // Amount to authorize and capture
    // ... contact gateway and get authorization and capture funds ...
}

function paypalstandard_capture_handler ( CaptureOrderEvent $Event ){
    // handle refund event action
    $orderid = $Event->order;   // the order number
    $gateway = $Event->gateway; // paypalstandard
    $txnid = $Event->txnid;     // Transaction ID associated with payment authorization
    $amount = $Event->amount;   // Amount to capture
    $user_id = $Event->user;    // User that initiated the capture
    // ... contact gateway and capture funds ...
}

function paypalstandard_refund_handler ( RefundOrderEvent $Event ){
    // handle refund event action
    $orderid = $Event->order;   // the order number
    $gateway = $Event->gateway; // paypalstandard
    $txnid = $Event->txnid;     // Transaction ID associated with payment authorization
    $amount = $Event->amount;   // Amount to refund
    $user_id = $Event->user;    // User that initiated the refund
    $reason = $Event->reason;   // Reason code
    // ... contact gateway and refund amount ...
}

See Also

You must be logged in to post a comment.

© Ingenesis Limited. Shopp™ is a registered trademark of Ingenesis Limited.

Skip to toolbar