# EDD_Payment ##### Table of Contents - [Available Properties](#properties) - [Available Methods](#methods) - [Examples](#examples) The EDD\_Payment class makes it easy to create, edit, and delete payment information in Easy Digital Downloads. Here are some examples: ##### Example of creating a new payment ``` $payment = new EDD_Payment(); $payment->add_download( 97 ); $payment->email = 'steve@example.com'; $payment->status = 'complete'; $payment->save(); ``` ##### Example of updating the email on an existing payment: ``` $payment = new EDD_Payment( 4023 ); $payment->email = 'steve@example.com'; $payment->save(); ``` ### Available Properties These are the properties which are available to your object: - $ID - $number - $mode - $key - $total - $subtotal - $tax - $fees - $discounts - $date - $completed\_date - $status - $old\_status - $status\_nicename - $customer\_id - $user\_id - $first\_name - $last\_name - $email - $address - $transaction\_id - $downloads - $ip - $gateway - $currency - $cart\_details - $has\_unlimited\_downloads - $pending - $parent\_payment ### Available Methods #### add\_download( $download\_id = 0, $args = array(), $options = array() ) This method allows you to add a download to a payment. It accepts three arguments: ##### $download\_id This is the ID of the download you wish to attach. It's always an integer. ##### $args This is an array that can over-ride these built in defaults: ``` 'quantity' => 1, 'price_id' => false, 'item_price' => 0.00, 'tax' => 0.00, 'fees' => array() ``` Fees may be anything required, but follows the format of `add_fee()`. For more information [see the docs for EDD\_Fees](https://easydigitaldownloads.com/docs/edd_fees-class/). ##### $options This is an array that can accept arbitrary options for the download. Examples might be `is_renewal` or `is_upgrade` for the Software Licensing extension. **IMPORTANT**: if you add a download to a Completed payment the new download will be set to a zero price. If you add a download to a payment with any other status, that download carries its default financial value, and the total value of the payment increases. This default behavior may be over-ridden by sending an `item_price` in the $args. #### remove\_download( $download\_id, $args = array() ) This method allows you to remove a download from a payment. It accepts two arguments: ##### $download\_id This is the ID of the download you wish to attach. It's always an integer. ##### $args This is an array that can over-ride these built in defaults: ``` 'quantity' => 1, 'price_id' => false, 'item_price' => 0.00, 'cart_index' => false, ``` **NOTE**: if your download is variable then the price\_id is required so that the proper item is removed. **NOTE**: By default `remove_download()` only removes one item. If you have multiple of the same item you'll need to use the quantity option in the $args. #### get\_meta( $meta\_key = '\_edd\_payment\_meta', $single = true ) This method gets the meta data associated with a payment. It accepts a meta key and a boolean to request the meta data in single mode or not. Internally this method runs get\_post\_meta, but then applies some logic to provide backwards compatibility with EDD 1.5 It then runs apply\_filters on `'edd_get_payment_meta_' . $meta_key` and then returns the output after one more filter of `edd_get_payment_meta`#### update\_meta( $meta\_key = '', $meta\_value = '', $prev\_value = '' ) This method allows you to update the post meta for a payment. It accepts a meta key, meta value, and a previous meta value for comparison. Before updating, the meta\_key is run through a filter called `'edd_update_payment_meta_' . $meta_key`. The return value is the output of `update_post_meta`. #### add\_fee( $args = '', $global = true ) This method allows you to attach an arbitrary fee to the payment. It functions exactly like the one in EDD\_Fees, [please read the documentation there](https://easydigitaldownloads.com/docs/edd_fees-class/). #### remove\_fee( $key ) This method allows you to remove a given fee. It functions exactly like the one in EDD\_Fees, [please read the documentation there](https://easydigitaldownloads.com/docs/edd_fees-class/). #### remove\_fee\_by( $key, $value, $global = false ) This method allows you to remove a fee without having to know its position in the fees array. For example, if you have a fee with a label of shipping you could do something like ``` $payment->remove_fee_by( 'label', 'Shipping' ); ``` The above code would remove the first instance of a a fee with a label of Shipping. If you add the gobal true flag like this: ``` $payment->remove_fee_by( 'label', 'Shipping', true ); ``` then it'll remove ALL fees with a label of Shipping. #### add\_note( $note = false ) This method allows you to attach a note to the payment. Results will look something like this: ![](https://easydigitaldownloads.com/wp-content/uploads/2022/07/6184cba760f98.png)#### update\_status( $status = false ) This method allows you to set the status of a given payment. Here are the possible statuses: - Pending - Complete - Refunded - Failed - Abandoned - Revoked #### array\_convert() This method allows you to get all available properties as an array. Example: ``` $payment = new EDD_Payment( 4577 ); $payments_array = $payment->array_convert(); ``` **IMPORTANT:** properties that have been moved to an array with array\_convert will NOT be updated inside that array. If you need an updated version after a change you would need to re-run this method and re-populate your array. #### save() This method takes any changes or updates made by any other method and writes them to the database. **NOTE**: if you don't use save() then none of your changes will actually take place. ### Examples Here are some code examples of some common tasks: #### Creating a payment ``` $payment = new EDD_Payment(); // Instantiates a payment object $payment->add_download( 12 ); // Adds download id 12 to the payment at it's default price $payment->email = 'lisa@example.org'; // Email is required for a payment $payment->status = 'complete'; // Completes the payment $payment->save(); // Writes to the database any changes that were made ``` #### Editing an existing payment ``` $payment = new EDD_Payment( 42 ); // Loads the information for Payment ID 42 $payment->email = 'john@example.org'; // Changes the email address on the payment $payment->save(); ``` #### Changing a payment status ``` $payment = new EDD_Payment( 1337 ); $payment->status = 'revoked'; $payment->save(); ``` #### Adding a variable priced download ``` $payment = new EDD_Payment( 1942 ); $args = array( 'price_id' => 1, // Variable price ID 'item_price' => 0.00, // Makes the item free ); $payment->add_download( 23, $args ); // Adds Download ID 23, variable price 1 to the payment $payment->save(); ``` #### Adding a download with options ``` $payment = new EDD_Payment( 2008 ); $args = array( 'item_price' => 4.00, ); $options = array( 'is_renewal' => true, ); $payment->add_download( 28, $args, $options ); $payment->save(); ``` #### Removing a download ``` $payment = new EDD_Payment( 2008 ); $payment->remove_download( 23 ); $payment->save(); ``` #### Removing a download with variable pricing ``` $payment = new EDD_Payment( 2008 ); $args = array( 'price_id' => 1, ); $payment->remove_download( 28, $args ); $payment->save(); ```