### Example handler for wpinv_complete_payment

Source: https://wpgetpaid.com/docs/developers/wpinv_complete_payment

A simple example function that hooks into wpinv_complete_payment to retrieve the invoice and its cart details.

```php
function _wpi_wpinv_complete_payment( $invoice_id ) {
    // Invoice object
    $invoice = wpinv_get_invoice( $invoice_id );

    // Invoice items
    $cart_items = $invoice->get_cart_details();

    // Do your stuff here
}
add_action( 'wpinv_complete_payment', '_wpi_wpinv_complete_payment', 10, 1 );
```

--------------------------------

### Example handler for wpinv_recurring_add_subscription_payment

Source: https://wpgetpaid.com/docs/developers/wpinv_recurring_add_subscription_payment

Example function that hooks into the wpinv_recurring_add_subscription_payment action to handle the event of a new invoice created for recurring payment. It retrieves the invoice items and allows custom logic.

```php
function _wpi_wpinv_recurring_add_subscription_payment( $invoice, $parent_invoice, $subscription_args ) {
    // Invoice items
    $cart_items = $invoice->get_cart_details();

    // Do your stuff here
}
add_action( 'wpinv_recurring_add_subscription_payment', '_wpi_wpinv_recurring_add_subscription_payment', 10, 3 );
```

--------------------------------

### Example: handle refund of invoice amount with wpinv_post_refund_invoice

Source: https://wpgetpaid.com/docs/developers/wpinv_post_refund_invoice

Simple example to handle refund of invoice amount. The callback receives the WPInv_Invoice object, retrieves cart details and the refunded amount, then performs custom logic. Hooked with priority 10 and accepts 1 argument.

```php
function _wpi_wpinv_post_refund_invoice( $invoice ) {
    // Invoice items
    $cart_items = $invoice->get_cart_details();
    
    // Refunded amount
    $refunded_amount = $invoice->get_total();

    // Do your stuff here
}
add_action( 'wpinv_post_refund_invoice', '_wpi_wpinv_post_refund_invoice', 10, 1 );
```

--------------------------------

### Example usage of wpinv_update_status hook

Source: https://wpgetpaid.com/docs/developers/wpinv_update_status

A simple example that hooks into wpinv_update_status to handle invoice status changes. It retrieves the invoice object and its cart details, then allows custom logic.

```php
function _wpi_wpinv_update_status( $invoice_id, $new_status, $old_status ) {
    // Invoice object
    $invoice = wpinv_get_invoice( $invoice_id );

    // Invoice items
    $cart_items = $invoice->get_cart_details();

    // Do your stuff here
}
add_action( 'wpinv_update_status', '_wpi_wpinv_update_status', 10, 3 );
```

--------------------------------

### Example: Handle event when invoice status changed to Paid (publish)

Source: https://wpgetpaid.com/docs/developers/wpinv_status_new_status

Example callback for the 'wpinv_status_publish' hook. Retrieves the invoice object and its cart details. The hook passes $invoice_id and $old_status.

```php
function _wpi_wpinv_status_paid( $invoice_id, $old_status ) {
    // Invoice object
    $invoice = wpinv_get_invoice( $invoice_id );

    // Invoice items
    $cart_items = $invoice->get_cart_details();

    // Do your stuff here
}
add_action( 'wpinv_status_publish', '_wpi_wpinv_status_paid', 10, 2 );
```

--------------------------------

### Example: Handle status change from Pending Payment to Paid

Source: https://wpgetpaid.com/docs/developers/wpinv_status_old_status_to_new_status

Example callback for the hook when the invoice status changes from wpi-pending to publish. It retrieves the invoice object and cart details, then performs custom actions. The hook is registered with add_action.

```php
function _wpi_wpinv_status_pending_to_paid( $invoice_id, $old_status ) {
    // Invoice object
    $invoice = wpinv_get_invoice( $invoice_id );

    // Invoice items
    $cart_items = $invoice->get_cart_details();

    // Do your stuff here
}
add_action( 'wpinv_status_wpi-pending_to_publish', '_wpi_wpinv_status_pending_to_paid', 10, 2 );
```

--------------------------------

### Simple order form configuration

Source: https://wpgetpaid.com/docs/addons-integrations/contact-form-7-addon

Example configuration for a Contact Form 7 form to order two units of item #17.

```text
## Fill in your details to order two of our #17 items.

 Your Name (required)[text wpinv_customer_name]
 Your Email (required)[email* wpinv_customer_email]
 Phone[tel wpinv_customer_phone]
 Your Message
[textarea wpinv_description] 
[wpinv_items wpinv_cf7_items "17|2"]
[submit "Send"]
```

--------------------------------

### Multiple items configuration

Source: https://wpgetpaid.com/docs/addons-integrations/contact-form-7-addon

Example of modifying the wpinv_items field to include 4 units of item #17 and 1 unit of item #32.

```text
[wpinv_items wpinv_cf7_items “17|4” “32”]
```

--------------------------------

### Handle wpinv_recurring_record_payment action

Source: https://wpgetpaid.com/docs/developers/wpinv_recurring_record_payment

Example handler for the wpinv_recurring_record_payment action. Retrieves the invoice and parent invoice objects, then gets cart details before performing custom logic.

```php
function _wpi_wpinv_recurring_record_payment( $invoice_id, $parent_invoice_id, $subscription_args ) {
    // Invoice object
    $invoice = wpinv_get_invoice( $invoice_id );
    
    // Parent Invoice object
    $invoice = wpinv_get_invoice( $parent_invoice_id );

    // Invoice items
    $cart_items = $invoice->get_cart_details();

    // Do your stuff here
}
add_action( 'wpinv_recurring_record_payment', '_wpi_wpinv_recurring_record_payment', 10, 3 );
```

--------------------------------

### Override visitor IP address

Source: https://wpgetpaid.com/docs/developers/wpinv_get_ip

Example of using the wpinv_get_ip filter to force a specific IP address, useful for testing location-based logic.

```php
function _wpi_wpinv_get_ip( $ip ) {
    /*
     * Sample IP addresses for different countries.
     * 
     * 90.222.150.124    =>    Glasgow, Scotland, United Kingdom (GB)
     * 79.150.150.150    =>    Barcelona, Catalonia, Spain (ES)
     * 106.209.216.208   =>    Mumbai, Maharashtra, India (IN)
     * 220.240.220.240   =>    Sydney, New South Wales, Australia (AU)
     */
    $ip = '90.222.150.124';
    
    return $ip;
}
add_filter( 'wpinv_get_ip', '_wpi_wpinv_get_ip', 10, 1 );
```

--------------------------------

### Example 2: Update item with advanced data

Source: https://wpgetpaid.com/docs/developers/wpinv_update_item

Updates an item with ID 2571 using many optional parameters, including recurring and trial settings. Passes true for $wp_error.

```php
$data = array(
    'ID'                   => 2571,
    'type'                 => 'custom',
    'title'                => __( 'Advance Item', 'textdomain' ),
    'custom_id'            => 123457,
    'price'                => '49.00',
    'status'               => 'publish',
    'custom_name'          => 'Custom name',
    'custom_singular_name' => 'For Sale',
    'vat_rule'             => 'digital',
    'editable'             => true,
    'excerpt'              => __( 'This is my first item.', 'textdomain' ),
    'is_recurring'         => 1,
    'recurring_period'     => 'M',
    'recurring_interval'   => 1,
    'recurring_limit'      => 6,
    'free_trial'           => 1,
    'trial_period'         => 'M',
    'trial_interval'       => 1,
 );
 
$item = wpinv_update_item( $data, true );
```

--------------------------------

### Build 2Checkout payment parameters and redirect

Source: https://wpgetpaid.com/docs/developers/creating-a-payment-gateway

Builds the 2Checkout payment parameters for line items, tax, and recurring settings, then sets the purchase step and redirect text. Applies the 'wpinv_2co_form_extra_parameters' and 'wpinv_2co_redirect_text' filters, and empties the shopping cart before redirecting.

```php
if ( $recurrence ) {
    $params['li_' . $i . '_recurrence'] = $recurrence;
}
if ( $is_recurring && $initial_amount != $recurring_amount ) {
    $params['li_' . $i . '_duration'] = $recurrence;
    $adjust = $recurring_amount - $initial_amount - $discount;
} else {
    if ( $duration ) {
        $params['li_' . $i . '_duration'] = $duration;
    }
}
$i++;
}

// Tax
if ( wpinv_use_taxes() && ( $tax = $invoice->get_tax() ) > 0 ) {
    if ( $adjust > 0 ) {
        $tax += $adjust;
    }
    $params['li_' . $i . '_type']       = 'tax';
    $params['li_' . $i . '_name']       = __( 'Tax', 'wpinv-2co' );
    $params['li_' . $i . '_quantity']   = 1;
    $params['li_' . $i . '_price']      = wpinv_sanitize_amount( $tax );
    $params['li_' . $i . '_tangible']   = 'N';
    $params['li_' . $i . '_product_id'] = 'tax';
    
    if ( $adjust > 0 ) {
        $params['li_0_startup_fee'] = $adjust * -1;
    }
    if ( $recurrence ) {
        $params['li_' . $i . '_recurrence'] = $recurrence;
    }
    if ( $duration ) {
        $params['li_' . $i . '_duration'] = $duration;
    }
}

$params['purchase_step']        = 'payment-method';
$params['x_receipt_link_url']   = wpinv_get_ipn_url( '2co' );

$params = apply_filters( 'wpinv_2co_form_extra_parameters', $params, $invoice );

$redirect_text  = __( 'Redirecting to 2Checkout site, click on button if not redirected.', 'wpinv-2co' );
$redirect_text  = apply_filters( 'wpinv_2co_redirect_text', $redirect_text, $invoice );

// Empty the shopping cart
wpinv_empty_cart();
```

--------------------------------

### Create a simple standard item

Source: https://wpgetpaid.com/docs/developers/adding-a-custom-item-type

Use this snippet to create a basic item by passing an array with required fields like item_id and title to wpinv_create_item.

```php
//=== Example 1: Create an simple standard item. ===//
 
 // An array of elements that make up a item to update or insert.
 $itemarr = array(
     'item_id'            => 1946,                                                    // Required. Any integer number. Must be unique within item type.
     'title'              => __( 'Simple Standard Product', 'wpinv-custom' ),         // Required. Item title.
     'price'              => '49.50',                                                 // Optional. Item price. Default '0.00'.
     'status'             => 'publish',                                               // Optional. pending, publish
 );
 $item = wpinv_create_item( $itemarr ); // Returns invoicing item object on success. The value 0 or WP_Error on failure.
```

--------------------------------

### Create a simple item

Source: https://wpgetpaid.com/docs/developers/wpinv_create_item

Creates a basic item with a title, price, and publish status.

```php
$data = array(
    'title'    => __( 'Simple Item', 'textdomain' ),
    'price'    => '199.00',
    'status'   => 'publish'
 );
 
$item = wpinv_create_item( $data, true );
```

--------------------------------

### Example 1: Update item title and price

Source: https://wpgetpaid.com/docs/developers/wpinv_update_item

Updates only the title and price of the item with ID 2570. Passes true for $wp_error to return a WP_Error on failure.

```php
$data = array(
    'ID'       => 2570,
    'title'    => __( 'Simple Item', 'textdomain' ),
    'price'    => '299.00',
 );
 
$item = wpinv_update_item( $data, true );
```

--------------------------------

### wpinv_get_ip filter

Source: https://wpgetpaid.com/docs/developers/wpinv_get_ip

Filters the IP address of the current visitor. Use this hook to override the detected IP address, for example to simulate a visitor from a specific country.

```APIDOC
## wpinv_get_ip filter

### Description
Filters the IP address of the current visitor.

### Hook
`apply_filters( 'wpinv_get_ip', string $ip )`

### Parameters
- **$ip** (string) - The current visitor's IP address.

### Returns
- (string) The filtered IP address.

### Example
Set the current visitor's IP address from United Kingdom IP address range. It will identify that the current visitor is from United Kingdom.

```php
function _wpi_wpinv_get_ip( $ip ) {
    /*
     * Sample IP addresses for different countries.
     * 
     * 90.222.150.124    =>    Glasgow, Scotland, United Kingdom (GB)
     * 79.150.150.150    =>    Barcelona, Catalonia, Spain (ES)
     * 106.209.216.208   =>    Mumbai, Maharashtra, India (IN)
     * 220.240.220.240   =>    Sydney, New South Wales, Australia (AU)
     */
    $ip = '90.222.150.124';
    
    return $ip;
}
add_filter( 'wpinv_get_ip', '_wpi_wpinv_get_ip', 10, 1 );
```
```

--------------------------------

### wpinv_insert_invoice()

Source: https://wpgetpaid.com/docs/developers/wpinv_insert_invoice

Creates an invoice with the provided data. Returns the invoice object on success, or 0/WP_Error on failure.

```APIDOC
## wpinv_insert_invoice()

### Description
Creates an invoice with the provided data.

### Method
Function

### Signature
`wpinv_insert_invoice( array $invoice_data = array(), bool $wp_error = false )`

### Parameters

#### $invoice_data
(array) (Required) An array of elements to insert an invoice.

- **status** (string) (Optional) The invoice status. Default: 'wpi-pending'
- **user_id** (int) (Optional) The invoice user id. Default: user ID of current logged user
- **post_date** (string) (Optional) The date-time in Y-m-d H:i:s format. Default: current time.
- **cart_details** (array) (Required) The invoice items details.
  - **id** (int) (Required) The item id.
  - **quantity** (int) (Optional) The item quantity. Default: 1
  - **custom_price** (float) (Optional) The item custom price. This price will overwrite the item price. Default: empty
  - **meta** (array) (Optional) The item meta. This stores custom values to be used for this line item.
- **payment_details** (array) (Optional) The invoice payment details. Required for paid invoice.
  - **gateway** (string) (Optional) The payment gateway name. Required for paid invoice. Default: 'manual'
  - **currency** (string) (Optional) The currency code (ISO 4217). ex: USD. Default: Store's default currency.
  - **transaction_id** (string) (Optional) The payment transaction id for paid invoices. Default: Current invoice ID.
- **user_info** (array) (Optional) User billing address details.
  - **first_name** (string) (Optional) Billing address first name. Default: User's saved first name.
  - **last_name** (string) (Optional) Billing address last name or surname. Default: User's saved last name.
  - **phone** (string) (Optional) Billing address phone number. Default: User's saved phone number.
  - **address** (string) (Optional) Billing address street name/street no./block no etc. Default: User's saved phone address.
  - **city** (string) (Optional) Billing address city. Default: User's saved city.
  - **country** (string) (Optional) The country code (ISO2). ex: US. Default: User's saved country or store's default country.
  - **state** (string) (Optional) The state name or state code. Default: User's saved state or store's default state.
  - **zip** (string) (Optional) Billing address postcode. Default: User's saved postcode.
  - **company** (string) (Optional) User's company name. Default: empty
  - **vat_number** (string) (Optional) User's vat number. Default: empty
  - **discount** (string) (Optional) The coupon code to apply discount. Default: empty
- **due_date** (string) (Optional) The invoice due date in Y-m-d. Only for invoice which has payment pending.
- **ip** (string) (Optional) IP address of the system from which invoice created/paid. Default: IP address of the current system.
- **user_note** (string) (Optional) Short message or note for user. User notes will be included in user invoice email sent to users. Default: empty
- **private_note** (string) (Optional) Short message or note for system use. Only admin can see private notes from backend invoice page. Default: empty
- **parent** (int) (Optional) For renewal payment only. Parent invoice ID for which the renewal payment is being paid. Default: 0

#### $wp_error
(bool) (Optional) Whether to return a WP_Error on failure. Default: false

### Return
(int|object|WP_Error) The value 0 or WP_Error on failure. The WPInv_Invoice object on success.

### Example
```php
$invoice_data = array(
    'cart_details' => array(
        array(
            'id' => 123,
            'quantity' => 2,
        ),
    ),
    'payment_details' => array(
        'gateway' => 'stripe',
        'currency' => 'USD',
    ),
    'user_info' => array(
        'first_name' => 'John',
        'last_name' => 'Doe',
        'email' => 'john@example.com',
    ),
);
$invoice = wpinv_insert_invoice( $invoice_data );
```
```

--------------------------------

### Create a simple pending payment invoice

Source: https://wpgetpaid.com/docs/developers/wpinv_insert_invoice

Creates an invoice with basic data and a status of 'wpi-pending'.

```php
$data = array(
    'status'        => 'wpi-pending',
    'user_id'       => 1,
    'cart_details'  => array(
        array(
            'id'    => 2118
        ),
    )
);

$invoice = wpinv_insert_invoice( $data, true );
```

--------------------------------

### Defining gateway backend settings

Source: https://wpgetpaid.com/docs/developers/creating-a-payment-gateway

Use the wpinv_gateway_settings_{GATEWAY_ID} filter to define the configuration fields for your gateway in the admin panel.

```php
public function gateway_settings( $settings = array() ) {
    /**
     * $settings[{GATEWAY_ID}_FIELD_NAME] = array(
     *     'id' => {GATEWAY_ID}_FIELD_NAME,                                         // Field name.
     *     'name' => __( 'Custom Field', 'my-textdomain' ),                         // Field title.
     *     'desc' => __( 'Description for custom field here.', 'my-textdomain' ),   // Field description.
     *     'type' => 'text',                                                        // Field type. Ex: text, checkbox, select etc.
     *     'size' => 'large',                                                       // Field input size. Ex: small, medium, large.
     *     'std' => __( 'Default value', 'my-textdomain' )                          // Field default value.
     * );
     */
    $settings['2co_desc'] = array(
        'id' => '2co_desc',
        'name' => __( 'Description', 'wpinv-2co' ),
        'desc' => __( 'This controls the description which the user sees during checkout.', 'wpinv-2co' ),
        'type' => 'text',
        'size' => 'large',
        'std' => __( 'Pay with your credit / debit card via 2Checkout gateway.', 'wpinv-2co' )
    );
    
    $settings['2co_sandbox'] = array(
        'type' => 'checkbox',
        'id' => '2co_sandbox',
        'name' => __( '2Checkout Sandbox', 'wpinv-2co' ),
        'desc' => __( '2Checkout sandbox can be used to test payments.', 'wpinv-2co' ),
        'std' => 1
    );
    
    $settings['2co_vendor_id'] = array(
        'type' => 'text',
        'id' => '2co_vendor_id',
        'name' => __( '2Checkout Account ID', 'wpinv-2co' ),
        'desc' => __( 'Enter your 2Checkout account id. Example : 1303908', 'wpinv-2co' ),
        'std' => '1303908',
    );

    $settings['2co_ipn_url'] = array(
        'type' => 'ipn_url',
        'id' => '2co_ipn_url',
        'name' => __( '2Checkout Instant Notification Url', 'wpinv-2co' ),
        'desc' => __( 'Configure Instant Notification url at your 2Checkout account. Set this url to Instant Notification Settings at Notifications page and enable all notifications. If you have sandbox mode enabled then set it here as well Sandbox Notifications.', 'wpinv-2co' ),
        'size' => 'large',
        'custom' => '2co',
        'readonly' => true,
        'std' => wpinv_get_ipn_url( '2co' ),
    );
    
    // Extra settings here
    
    return $settings;
}
add_filter( 'wpinv_gateway_settings_2co', array( $this->admin, 'gateway_settings' ) );
```

--------------------------------

### wpinv_create_item()

Source: https://wpgetpaid.com/docs/developers/wpinv_create_item

Creates a new item. If the $args parameter has 'custom_id' set to a value and $force_update is true, then the item will be updated for matching 'item_id' and 'type'.

```APIDOC
## wpinv_create_item()

### Description
Creates a new item. If the $args parameter has 'custom_id' set to a value and $force_update is true, then the item will be updated for matching 'item_id' and 'type'.

### Method
Function

### Signature
wpinv_create_item( array $args = array(), bool $wp_error = false, bool $force_update = false )

### Parameters

#### $args
(array) (Required) An array of elements to create a new item.

- **type** (string) (Optional) The item type. Default: 'custom'
- **title** (string) (Required) The item title.
- **custom_id** (string) (Optional) Any integer or non numeric id. Must be unique within item type. Default: item ID will be set after save.
- **price** (float) (Optional) The item price. Default: '0.00'
- **status** (string) (Optional) The item status. 'publish' => Published item, 'pending' => Pending item. Default: 'pending'
- **custom_name** (string) (Optional) Plural sub title for the item. Default: empty
- **custom_singular_name** (string) (Optional) Singular sub title for the item. Default: empty
- **vat_rule** (string) (Optional) VAT rule to apply if tax enabled. 'digital' => Digital item, 'physical' => Physical item. Default: 'digital'
- **editable** (bool) (Optional) Item editable from backend items page? Default: true
- **excerpt** (string) (Optional) The item excerpt(short description). Default: empty
- **is_recurring** (bool) (Optional) Whether to enable recurring feature for the item? Use 1 => Allow recurring or 0 => Don't allow recurring. Default: 0
- **recurring_period** (string) (Optional) Recurring time period. 'D' => Daily, 'W' => Weekly, 'M' => Monthly, 'Y' => Yearly. Default: 'M'
- **recurring_interval** (int) (Optional) Recurring interval. Integer number between 1 – 90. Default: 1
- **recurring_limit** (int) (Optional) Recurring limit. 0 for recurring forever until cancelled. Default: 0
- **free_trial** (bool) (Optional) Whether to enable free trial if recurring feature is enabled? Default: 0
- **trial_period** (int) (Optional) Free trial time period. 'D' => Daily, 'W' => Weekly, 'M' => Monthly, 'Y' => Yearly. Default: 'M'
- **trial_interval** (int) (Optional) Free trial interval. Integer number between 1 – 90. Default: 1

#### $wp_error
(bool) (Optional) Whether to return a WP_Error on failure. Default: false

#### $force_update
(bool) (Optional) Whether to update an item if parameter 'custom_id' has set value and item already exists with that custom_id. Default: false

### Return
(int|object|WP_Error) The value 0 or WP_Error on failure. The WPInv_Item object on success.
```

--------------------------------

### Create an item with advanced data

Source: https://wpgetpaid.com/docs/developers/adding-a-custom-item-type

Use this snippet to create an item with additional configuration such as recurring billing, free trials, and VAT rules.

```php
//=== Example 2: Create an item with advance data. ===//
 
 // An array of elements that make up a item to update or insert.
 $itemarr = array(
     'type'               => 'product',                                               // Optional. Item type. Default 'custom'.
     'item_id'            => 1947,                                                    // Required. Any integer number. Must be unique within item type.
     'title'              => __( 'First Product', 'wpinv-custom' ),                   // Required. Item title.
     'price'              => '99.50',                                                 // Optional. Item price. Default '0.00'.
     'status'             => 'publish',                                               // Optional. pending, publish
     'vat_rule'           => 'digital',                                               // Optional. digital => Digital item, physical => Physical item
     'cpt_singular_name'  => 'For Sale',                                              // Optional. Sub title for item. Should be singular.
     'cpt_name'           => '',                                                      // Optional. Sub title for item. Should be plural.
     'is_recurring'       => 1,                                                       // Optional. 1 => Allow recurring or 0 => Don't allow recurring
     'recurring_period'   => 'M',                                                     // Optional. D => Daily, W => Weekly, M => Monthly, Y => Yearly
     'recurring_interval' => 1,                                                       // Optional. Integer value between 1 - 90.
     'recurring_limit'    => 6,                                                       // Optional. Any integer number. 0 for recurring forever until cancelled.
     'free_trial'         => 1,                                                       // Optional. 1 => Allow free trial or 0 => Don't free trial
     'trial_period'       => 'M',                                                     // Optional. D => Daily, W => Weekly, M => Monthly, Y => Yearly
     'trial_interval'     => 1,                                                       // Optional. Any integer number.
     'excerpt'            => __( 'This is my first product.', 'wpinv-custom' ),       // Optional. Item short description
 );
 $item = wpinv_create_item( $itemarr ); // Returns invoicing item object on success. The value 0 or WP_Error on failure.
```

--------------------------------

### Registering the payment gateway

Source: https://wpgetpaid.com/docs/developers/creating-a-payment-gateway

Use the wpinv_payment_gateways filter to register your custom gateway by adding it to the gateways array.

```php
public function add_gateway( $gateways = array() ) {
    /**
     * $gateways[{GATEWAY_ID}] = array(
     *     'admin_label'    => __( 'Custom Gateway', 'my-textdomain' ),      // Gateway title to displayed in backend
     *     'checkout_label' => __( 'Custom Gateway', 'my-textdomain' ),      // Gateway title to displayed in checkout
     *     'ordering'       => 2                                             // Gateway display order
     * );
     */
    $gateways['2co'] = array(
        'admin_label'    => __( '2Checkout', 'wpinv-2co' ),
        'checkout_label' => __( '2Checkout - Credit / Debit Card', 'wpinv-2co' ),
        'ordering'       => 2
    );
    
    return $gateways;
}
add_action( 'wpinv_payment_gateways', array( $this, 'add_gateway' ) );
```

--------------------------------

### Process Payment (wpinv_2co_process_payment)

Source: https://wpgetpaid.com/docs/developers/creating-a-payment-gateway

This function processes the payment for the 2Checkout gateway. It verifies the nonce, collects payment data, records a pending invoice, and builds the 2Checkout parameters including recurring payment details, items, and discounts.

```php
function wpinv_2co_process_payment( $purchase_data ) {
    if( ! wp_verify_nonce( $purchase_data['gateway_nonce'], 'wpi-gateway' ) ) {
        wp_die( __( 'Nonce verification has failed', 'wpinv-2co' ), __( 'Error', 'wpinv-2co' ), array( 'response' => 403 ) );
    }
    
    // Collect payment data
    $payment_data = array(
        'price'         => $purchase_data['price'],
        'date'          => $purchase_data['date'],
        'user_email'    => $purchase_data['user_email'],
        'invoice_key'   => $purchase_data['invoice_key'],
        'currency'      => wpinv_get_currency(),
        'items'         => $purchase_data['items'],
        'user_info'     => $purchase_data['user_info'],
        'cart_details'  => $purchase_data['cart_details'],
        'gateway'       => '2co',
        'status'        => 'wpi-pending'
    );

    // Record the pending payment
    $invoice = wpinv_get_invoice( $purchase_data['invoice_id'] );
    
    if ( !empty( $invoice ) ) {
        $quantities_enabled = wpinv_item_quantities_enabled();
        $invoice_id = $invoice->ID;
        $subscription_item = $invoice->get_recurring( true );
        $is_recurring = !empty( $subscription_item ) ? true : false; // Is recurring payment?
        
        $params                         = array();
        $params['sid']                  = wpinv_get_option( '2co_vendor_id', false );
        $params['mode']                 = '2CO';
        $params['currency_code']        = wpinv_get_currency();
        $params['merchant_order_id']    = $invoice_id;
        $params['total']                = wpinv_sanitize_amount( $invoice->get_total() );
        $params['key']                  = $invoice->get_key();
        $params['card_holder_name']     = $invoice->get_user_full_name();
        $params['email']                = $invoice->get_email();
        $params['street_address']       = wp_strip_all_tags( $invoice->get_address(), true );
        $params['country']              = $invoice->country;
        $params['state']                = $invoice->state;
        $params['city']                 = $invoice->city;
        $params['zip']                  = $invoice->zip;
        $params['phone']                = $invoice->phone;
        
        $initial_amount = wpinv_format_amount( $invoice->get_total() );
        $recurring_amount = wpinv_format_amount( $invoice->get_recurring_details( 'total' ) );
            
        // Recurring payment
        $recurrence = '';
        $duration = '';
        if ( !empty( $is_recurring ) ) {
            $interval = $subscription_item->get_recurring_interval();
            $period = $subscription_item->get_recurring_period();
            $bill_times = (int)$subscription_item->get_recurring_limit();
            $time_period = wpinv_2co_get_time_period( $interval, $period );
            $recurrence = $time_period['interval'] . ' ' . $time_period['period'];
            $time_duration = $bill_times > 0 ? wpinv_2co_get_time_period( $bill_times, $period ) : array();
            $duration = !empty($time_duration) ? $time_duration['interval'] . ' ' . $time_duration['period'] : 'Forever';
        }
        
        $i = 0;
        // Items
        foreach ( $invoice->get_cart_details() as $item ) {
            $quantity = $quantities_enabled && !empty( $item['quantity'] ) && $item['quantity'] > 0 ? $item['quantity'] : 1;
            
            $params['li_' . $i . '_type']       = 'product';
            $params['li_' . $i . '_name']       = $item['name'];
            $params['li_' . $i . '_quantity']   = $quantity;
            $params['li_' . $i . '_price']      = wpinv_sanitize_amount( $item['item_price'] );
            $params['li_' . $i . '_tangible']   = 'N';
            $params['li_' . $i . '_product_id'] = $item['id'];
            
            if ( $recurrence ) {
                $params['li_' . $i . '_recurrence'] = $recurrence;
            }
            if ( $duration ) {
                $params['li_' . $i . '_duration'] = $duration;
            }
            $i++;
        }
        
        $adjust = 0;
        // Discount
        if ( ( $discount = $invoice->get_discount() ) > 0 ) {
            $params['li_' . $i . '_type']       = 'coupon';
            $params['li_' . $i . '_name']       = __( 'Discount', 'wpinv-2co' );
            $params['li_' . $i . '_quantity']   = 1;
            $params['li_' . $i . '_price']      = wpinv_sanitize_amount( $discount );
            $params['li_' . $i . '_tangible']   = 'N';
            $params['li_' . $i . '_product_id'] = 'discount';
        }
    }
}
```

--------------------------------

### Create Buy Button Shortcode

Source: https://wpgetpaid.com/docs/addons-integrations/geodirectory

Use this shortcode to create a buy button for additional services, such as a 'Featured Listing Service', by referencing the item ID.

```text
[wpinv_buy items=8 label="Buy Featured Listing Service"]
```

--------------------------------

### Buy Button Shortcode

Source: https://wpgetpaid.com/docs/core-plugin/core-shortcodes

Displays a buy button. Parameters include items (item_id or item_id|quantity), label (button text), and post_id.

```text
[wpinv_buy items=123]
```

```text
[wpinv_buy items=123 label="Buy Me"]
```

```text
[wpinv_buy items="123|2"]
```

```text
[wpinv_buy items="123|2" label="Buy Me"]
```

--------------------------------

### Enabling recurring payments support

Source: https://wpgetpaid.com/docs/developers/creating-a-payment-gateway

Use the wpinv_{GATEWAY_ID}_support_subscription filter to enable recurring payments for your gateway.

```php
/**
 * add_filter( 'wpinv_{GATEWAY_ID}_support_subscription', '__return_true' );
 */
add_filter( 'wpinv_2co_support_subscription', '__return_true' );
```

--------------------------------

### Create a simple paid payment invoice

Source: https://wpgetpaid.com/docs/developers/wpinv_insert_invoice

Creates an invoice with basic data and payment details, set to 'publish' status.

```php
$data = array(
    'status'            => 'publish',
    'user_id'           => 1,
    'post_date'         => '2017-08-08 11:20:38',
    'cart_details'      => array(
        array(
            'id'        => 2118
        ),
    ),
    'payment_details'   => array(
        'gateway'           => 'paypal',
        'currency'          => 'USD',
        'transaction_id'    => '9TK485797B9101342'
    ),
);

$invoice = wpinv_insert_invoice( $data, true );
```

--------------------------------

### wpinv_create_item function signature

Source: https://wpgetpaid.com/docs/developers/wpinv_create_item

The function signature for creating a new item, including parameters for arguments, error handling, and forced updates.

```php
wpinv_create_item( array $args = array(), bool $wp_error = false, bool $force_update = false )
```

--------------------------------

### Checkout Page Shortcode

Source: https://wpgetpaid.com/docs/core-plugin/core-shortcodes

Displays the checkout page. Ensure the page is configured in WPI > Settings > General > Page Settings > Checkout Page.

```text
[wpinv_checkout]
```

--------------------------------

### Process 2Checkout IPN callback

Source: https://wpgetpaid.com/docs/developers/creating-a-payment-gateway

Handles the 2Checkout IPN callback by validating required fields and the MD5 hash, then retrieving the invoice. Dies with error codes -1 through -4 for missing data, invalid hash, or missing invoice.

```php
function wpinv_2co_process_ipn() {
    $request = wpinv_get_post_data( 'post' );

    if ( empty( $request['message_type'] ) || empty( $request['vendor_id'] ) ) {
        die( '-1' );
    }
    
    if ( empty( $request['sale_id'] ) || empty( $request['invoice_id'] ) || empty( $request['md5_hash'] ) ) {
        die( '-2' );
    }
    
    if ( !wpinv_2co_validate_ipn( $request['md5_hash'], $request['sale_id'], $request['vendor_id'], $request['invoice_id'] ) ) {
        die( '-3' );
    }
    
    $vendor_order_id    = sanitize_text_field( $request['vendor_order_id'] );
    $invoice            = wpinv_get_invoice( $vendor_order_id );
    if ( empty( $invoice ) ) {
        die( '-4' );
    }
```

--------------------------------

### wpinv_insert_invoice() function signature

Source: https://wpgetpaid.com/docs/developers/wpinv_insert_invoice

The basic function signature for creating an invoice.

```php
wpinv_insert_invoice( array $invoice_data = array(), bool $wp_error = false )
```