Some business models require that payments be stored in an escrow account to be settled at a later date. For instance, if a buyer wants to pay for a task that takes time, a third party (marketplace) could hold the money from the buyer in an account until the seller finishes the task they are being paid for.

With Payments, this is possible through Escrow orders.

The Escrow Order Object

Much like an instant payment order, an escrow is represented by an object that can be manipulated. In fact all of the basic traits of a instant payment order are available to an escrow order.

// General Information
$order->get_id();
$order->get_description();
$order->get_author();
$order->get_ip_address(); // Returns IP address used to create the order
$order->get_currency();
$order->get_gateway();
$order->get_parent(); // Used for recurring orders
 
$order->is_recurring(); // Returns true if the order is recurring
$order->is_escrow(); // Returns true if the order is an escrow order
 
// Payment Gateway helpers
$order->get_return_url(); // URL to redirect after order is completed
$order->get_cancel_url(); // URL to redirect to change gateways
 
// Items
$order->get_item( $index = 0 ); // Returns the nth-item on the order
$order->get_items( $item_type = '' ); // Returns an array of items
$order->get_total();
 
// Event
$order->get_status(); // Returns the current state of the order. See Order States
$order->get_display_status();

However, there are some key differences that allow for this new business model.

Adding Receivers

An escrow order can be split between multiple receivers. A payment might end up being split between the seller of a good and the marketplace in the case of a transaction fee. To add a receiver, you simply must call add_receiver().

$order->add_receiver( $user_id, $amount, $fees = true );
 
// Add any user as a receiver
$order->add_receiver( 5, 10 );
 
// Add a receiver without taking the marketplace fee
$order->add_receiver( 5, 10, false );

The marketplace fee is a setting in the Payments Escrow tab which allows the marketplace to reserve an amount of each payment made out as a transaction fee. By default, this amount is taken from the payout each receiver will receive.

You can get a list of the receivers and their respective amounts by using $order->get_receivers().

Escrow States

An escrow order can be in any of the following states:

$order->pending(); // Waiting for payment
$order->failed(); // Payment has failed.
$order->paid(); // Payment is completed and money is in escrow
$order->refunded(); // Payment has been refunded to buyer.
$order->completed(); // Payment has been transferred to seller.

You can use $order->get_status() to retrieve this from any order. Check out the basic order object to find out more about using states.