1. Home
  2. Developers
  3. Creating a Payment Gateway

Creating a Payment Gateway

Introduction

  1. Registering the gateway
  2. Gateway backend settings
  3. Add support for recurring payments
  4. Set up the credit card form, if any
  5. Processing the payment
  6. Validating the payment
  7. Handling the Payment Gateway Callbacks

1) Registering the gateway

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' ) );

2) Gateway backend settings

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' ) );

3) Add support for recurring payments

Enable accepting recurring payments

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

Disable accepting recurring payments

/**
 * add_filter( 'wpinv_{GATEWAY_ID}_support_subscription', '__return_false' );
 */
add_filter( 'wpinv_2co_support_subscription', '__return_false' );

4) Set up the credit card form, if any

If gateway has any credit form fields

function wpinv_2co_cc_form() {
    // Your form fields here
}
add_action( 'wpinv_2co_cc_form', 'wpinv_2co_cc_form' );

If gateway does not have any credit form fields

/**
 * add_action( 'wpinv_{GATEWAY_ID}_cc_form', '__return_false' );
 */
add_action( 'wpinv_2co_cc_form', '__return_false' );

5) Processing the payment

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';
            
            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();
        ?>

$value ) { ?>
document.wpi_2co_form.submit();

6) Validating the payment

function wpinv_2co_validate_checkout( $valid_data, $post ) {
    if ( !empty( $post['wpi-gateway'] ) && $post['wpi-gateway'] == '2co' ) {
        $invoice = wpinv_get_invoice_cart();
        
        if ( empty( $invoice ) ) {
            return;
        }

        if ( !( (float)$invoice->get_total() > 0 ) ) {
            wpinv_set_error( 'empty_total', __( '2Checkout unable to process the payment with invoice total equal to zero or in a negative number.', 'wpinv-2co' ) );
            return;
        }
        
        if ( $invoice->is_free_trial() ) {
            wpinv_set_error( 'empty_no_free_trial', __( '2Checkout payment gateway does not support free trial.', 'wpinv-2co'));
            return;
        }
        
        if ( $item = $invoice->get_recurring( true ) ) {
            if ( $item->get_recurring_period() == 'D' )
            wpinv_set_error( 'empty_invalid_period', __( '2Checkout does not process the payment with recurring period in "Day". Can use only # Week, # Month, # Year.', 'wpinv-2co'));
            return;
        }
    }
}
add_action( 'wpinv_checkout_error_checks', 'wpinv_2co_validate_checkout', 11, 2 );

7) Handling the Payment Gateway Callbacks

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' );
    }

    $invoice_id         = $invoice->ID;
    $invoice_status     = isset($request['invoice_status']) ? $request['invoice_status'] : '';
    $current_status     = $invoice->status;
    $item_index         = wpinv_2co_response_get_item_index( $request ); // Response contains main item.
    
    if ( empty( $item_index ) && strtoupper( $request['message_type'] ) != 'REFUND_ISSUED' ) {
        die( '-5' );
    }
    
    switch( strtoupper( $request['message_type'] ) ) {
        case 'ORDER_CREATED' :
            if ($invoice_status == 'approved' || $invoice_status == 'deposited') {
                wpinv_update_payment_status( $invoice_id, 'publish' );
                wpinv_set_payment_transaction_id( $invoice_id, $request['invoice_id'] );
                wpinv_insert_payment_note( $invoice_id, sprintf( __( '2Checkout Sale id: %s, Invoice id: %s', 'wpinv-2co' ), $request['sale_id'], $request['invoice_id'] ) );
                
                if ( !empty( $request['recurring'] ) ) {
                    sleep(1);
                    wpinv_2co_record_subscription_signup( $request, $invoice );
                }
            } else if ($invoice_status == 'declined') {
                wpinv_update_payment_status( $invoice_id, 'wpi-failed' );
                wpinv_record_gateway_error( __( '2CHECKOUT IPN ERROR', 'wpinv-2co' ), __( 'Payment failed due to invalid purchase found.', 'wpinv-2co' ), $invoice_id );
            } else if ($invoice_status == 'pending') {
                wpinv_update_payment_status( $invoice_id, 'wpi-pending' );
            }
            
            die( '1' );
            break;
            
        case 'INVOICE_STATUS_CHANGED' :
            break;

        case 'REFUND_ISSUED' :
            $parent_invoice_id  = $invoice_id;
            $invoice_id = wpinv_get_id_by_transaction_id( $request['invoice_id'] );
            
            if ( empty( $invoice_id ) ) {
                $invoice_id = $parent_invoice_id;
            }
            
            if ( !empty( $request['recurring'] ) && !empty( $request['item_type_' . $item_index] ) && $request['item_type_' . $item_index] == 'refund' ) {
                wpinv_insert_payment_note( $invoice_id, wp_sprintf( __( '2Checkout: %s. Sale id: %s. Invoice id: %s', 'wpinv-2co' ), $request['message_description'], $request['sale_id'], $request['invoice_id'] ) );
                
                do_action( 'wpinv_2co_process_refund', $request, $invoice_id, 'item' );
                
                wpinv_update_payment_status( $invoice_id, 'wpi-refunded' );
                
                die( '1' );
            }
            
            $refunded_amount  = NULL;
            for ( $i = 1; $i <= (int)$request['item_count']; $i++ ) {
                $refunded_amount += $request['item_cust_amount_' . $i];
            }
            if ( $refunded_amount !== NULL ) {
                $refunded_amount = wpinv_sanitize_amount( $refunded_amount );
            }
            
            if ( $refunded_amount !== NULL && $refunded_amount get_total() ) {
                $refunded_amount = wpinv_price( $refunded_amount );
                
                wpinv_insert_payment_note( $invoice_id, wp_sprintf( __( '2Checkout: Partial refund of %s processed. Sale id: %s. Invoice id: %s', 'wpinv-2co' ), $refunded_amount, $request['message_description'], $request['sale_id'], $request['invoice_id'] ) );
                
                do_action( 'wpinv_2co_process_refund', $request, $invoice_id, 'partial' );
            } else {
                wpinv_insert_payment_note( $invoice_id, wp_sprintf( __( '2Checkout: %s. Sale id: %s. Invoice id: %s', 'wpinv-2co' ), $request['message_description'], $request['sale_id'], $request['invoice_id'] ) );
                
                do_action( 'wpinv_2co_process_refund', $request, $invoice_id, 'full' );
                
                wpinv_update_payment_status( $invoice_id, 'wpi-refunded' );
            }
            
            die( '1' );
            
            break;

        case 'RECURRING_INSTALLMENT_SUCCESS' :
            wpinv_insert_payment_note( $invoice_id, wp_sprintf( __( '2Checkout: %s. Sale id: %s. Invoice id: %s', 'wpinv-2co' ), $request['message_description'], $request['sale_id'], $request['invoice_id'] ) );
            
            wpinv_2co_record_subscription_payment( $request, $invoice );
            
            die( '1' );
            break;

        case 'RECURRING_INSTALLMENT_FAILED' :
            wpinv_insert_payment_note( $invoice_id, wp_sprintf( __( '2Checkout: %s. Sale id: %s. Invoice id: %s', 'wpinv-2co' ), $request['message_description'], $request['sale_id'], $request['invoice_id'] ) );
            
            die( '1' );
            break;

        case 'RECURRING_STOPPED' :
            wpinv_insert_payment_note( $invoice_id, wp_sprintf( __( '2Checkout: %s. Sale id: %s. Invoice id: %s', 'wpinv-2co' ), $request['message_description'], $request['sale_id'], $request['invoice_id'] ) );
            
            $invoice->stop_subscription();
            
            die( '1' );
            break;

        case 'RECURRING_COMPLETE' :
            wpinv_insert_payment_note( $invoice_id, wp_sprintf( __( '2Checkout: %s. Sale id: %s. Invoice id: %s', 'wpinv-2co' ), $request['message_description'], $request['sale_id'], $request['invoice_id'] ) );
            
            $invoice->complete_subscription();
            
            die( '1' );
            break;

        case 'RECURRING_RESTARTED' :
            wpinv_insert_payment_note( $invoice_id, wp_sprintf( __( '2Checkout: %s. Sale id: %s. Invoice id: %s', 'wpinv-2co' ), $request['message_description'], $request['sale_id'], $request['invoice_id'] ) );
            
            $invoice->restart_subscription();
            
            die( '1' );
            break;

        case 'FRAUD_STATUS_CHANGED' :
            switch ( $request['fraud_status'] ) {
                case 'pass':
                    wpinv_insert_payment_note( $invoice_id, wp_sprintf( __( '2Checkout fraud review passed. Sale id: %s, Invoice id: %s', 'wpinv-2co' ), $request['sale_id'], $request['invoice_id'] ) );
                    break;
                case 'fail':
                    wpinv_insert_payment_note( $invoice_id, wp_sprintf( __( '2Checkout fraud review failed. Sale id: %s, Invoice id: %s', 'wpinv-2co' ), $request['sale_id'], $request['invoice_id'] ) );
                    break;
                case 'wait':
                    wpinv_insert_payment_note( $invoice_id, wp_sprintf( __( '2Checkout fraud review in process. Sale id: %s, Invoice id: %s', 'wpinv-2co' ), $request['sale_id'], $request['invoice_id'] ) );
                    break;
            }
            
            die( '1' );
            break;
    }
    do_action( 'wpinv_2co_process_ipn_type_' . strtolower( $request['message_type'] ), $request, $invoice );
    
    die( '2' );
}
add_action( 'wpinv_verify_2co_ipn', 'wpinv_2co_process_ipn' );
Was this helpful to you? Yes 3 No