Gateways that allow for payments to be collected and payout delayed until a later time are called Escrow Payment Gateways. These gateways are very useful on sites where the site acts as a mediator between two parties to make sure payment is not issued until services are received.

Payment Gateway Setup

Escrow payment gateways are very similar to regular payment gateways in their setup. They must must implement the APP_Payment_Processor interface as well as define the following methods:

class MyPaymentGateway implements APP_Payment_Processor {
 
    /**
    * Returns an array representing the form to output for admin configuration
    * @return array scbForms style form array
    */
    function form();
 
    /**
    * Provides the unique identifier for this Gateway
    *
    * @return string
    */
    function identifier();
 
     /**
     * Provides the display name for this Gateway
     *
     * @return string
     */
     function display_name( $type = 'dropdown' );
 
     /**
     * Returns if the gateway supports the given service
     * @return bool
     */
     function supports( $service = 'instant' );
 
}

Note: APP_Payment_Processor is a part of Payments 3.0 API. Make sure you are using a supported theme and/or backwards compatibility file.

Escrow-specific Methods

Escrow gateways must also implement APP_Escrow_Payment_Processor which is a separate interface that signals to Payments that this gateway will be able to handle escrow payments. Along with implementing the interface, your gateway must define the following methods:

     /**
     * Processes the initial setup of the escrow payment
     * @param APP_Order $order The order to be processed
     * @param array $options An array of user-entered options
     *              corresponding to the values provided in form()
     * @return void
    */
    function process_escrow( APP_Escrow_Order $order, array $options );
 
    /**
    * Completes the transaction towards the seller
    * @param APP_Order $order The order to be processed
    * @param array $options An array of user-entered options
    *               corresponding to the values provided in form()
    * @return void
    */
    function complete_escrow( APP_Escrow_Order $order, array $options );
 
    /**
    * Refunds the transaction towards the buyer
    * @param APP_Order $order The order to be processed
    * @param array $options An array of user-entered options
    *               corresponding to the values provided in form()
    * @return void
    */
    function fail_escrow( APP_Escrow_Order $order, array $options );
 
    /**
     * Outputs/processes a form for user's escrow account data
     */
    function user_form();

Processing orders

An escrow order’s life cycle goes through three primary stages: Creation, Payment, and Payout.

During creation the order is created and setup with items, currencies, etc. Once it is ready, the order moves into the payment stage where the buyer actually pays the amount on the order. This stage will call the “process_escrow()` method of the processing gateway where the gateway should collect payment and hold it in escrow.

Once the payment has been collected, the payment gateway should call $order->paid() to notify Payments of the successful payment.

public function process_escrow( APP_Escrow_Order $order, array $options ) {
    // Collect user information
    // Process payment
    // Store payment in escrow account
    $order->paid();
}

After the payment stage, the order will move into the payout stage. When the theme signals that the order is ready to be paid out, it will either call complete_escrow() or fail_escrow() on the processing gateway. If fail_escrow() is called, the total amount should be returned to the buyer.

public function fail_escrow( APP_Escrow_Order $order, array $options ) {
    // Return payment to buyer
}

If complete_escrow() is called, the order’s total should be paid to the seller of the order. However, the site administrator has the ability to hold back an amount (flat fee or percentage) of each payout. For this reason, the gateway should use the order’s get_receiver() method to get a list of the different users that should be paid and the amount to be paid to them.

foreach ( $order->get_receivers() as $user_id => $amount ) {
    $this->credit_user( $amount, $user_id );
}

The list returned by get_receivers() will only include third-party payouts. Any money left over after the receivers list has been paid should be returned to the site owner as their transaction fee.